Usage Guide

Learn How to Integrate and Use the Panglot Platform

Getting Started

This guide provides practical examples and workflows for integrating with and using the Panglot platform. Each section includes sequence diagrams showing the flow of requests and responses through the system.

API Access Patterns

The platform supports multiple access patterns depending on your client type and use case.

Pattern 1: REST API for Web Applications

sequenceDiagram
    participant Client as Web Client
    participant GW as API Gateway
    participant Auth as Auth Service
    participant BFF as BFF-Web
    participant Service as Orders Service

    Client->>GW: GET /api/v1/orders
    Note over Client,GW: Authorization: Bearer {token}

    GW->>Auth: Validate JWT token
    Auth-->>GW: Token valid, claims

    GW->>GW: Check rate limits
    GW->>BFF: Forward request + user context

    BFF->>Service: ListOrders(gRPC)
    Note over BFF,Service: gRPC with metadata
trace_id, user_id

    Service->>Service: Query database
    Service-->>BFF: Order list (protobuf)

    BFF->>BFF: Convert to JSON
    BFF-->>GW: JSON response
    GW-->>Client: 200 OK + orders data

    Note over Client,Service: Full request traced
with distributed trace_id

Key Components

Creating an Order - Complete Flow

End-to-end workflow showing synchronous and asynchronous processing. 

sequenceDiagram
    participant C as Client
    participant GW as Gateway
    participant BFF as BFF-Web
    participant O as Orders
    participant DB as Orders DB
    participant K as Kafka

    rect rgb(227, 242, 253)
        Note over C,K: Phase 1: Synchronous Order Creation
        C->>GW: POST /api/v1/orders
{items, customer, shipping}
        GW->>GW: Validate schema
        GW->>BFF: Forward
        
        BFF->>O: CreateOrder(gRPC)
        O->>O: Validate business rules
        
        par Database Transaction
            O->>DB: BEGIN TRANSACTION
            O->>DB: INSERT INTO orders
            O->>DB: INSERT INTO outbox
(OrderCreated event)
            O->>DB: COMMIT
        end
        
        O-->>BFF: OrderResponse
{id, status: PENDING}
        BFF-->>C: 201 Created
    end

    rect rgb(255, 243, 224)
        Note over O,K: Phase 2: Asynchronous Event Processing
        loop Outbox Relay (every 100ms)
            O->>DB: SELECT * FROM outbox
WHERE published = false
            O->>K: Publish OrderCreated event
            O->>DB: UPDATE outbox
SET published = true
        end
    end

    rect rgb(232, 245, 233)
        Note over K,C: Phase 3: Downstream Processing
        Note over K: Payments Service subscribes
        Note over K: Inventory Service subscribes
        Note over K: Notification Service subscribes
    end

✅ Transaction Guarantees

The Outbox pattern ensures that events are published atomically with database changes. Even if the service crashes after the database commit, the outbox relay will publish the event when the service restarts.

Saga Orchestration - Order Fulfillment

Distributed transaction spanning multiple services with automatic compensation. 

sequenceDiagram
    participant O as Orders
    participant K as Kafka
    participant P as Payments
    participant I as Inventory
    participant N as Notifications

    Note over O,N: Happy Path Saga

    O->>K: OrderCreated
    K->>P: Consume event
    
    P->>P: Authorize payment
    alt Payment Successful
        P->>K: PaymentAuthorized
        K->>I: Consume event
        
        I->>I: Reserve inventory
        alt Inventory Available
            I->>K: InventoryReserved
            K->>P: Consume event
            
            P->>P: Capture payment
            P->>K: PaymentCaptured
            
            K->>O: Update order status
            O->>O: Status = CONFIRMED
            O->>K: OrderConfirmed
            
            K->>N: Send confirmation email
        else Inventory Unavailable
            Note over I,N: Compensation Flow
            I->>K: InventoryReservationFailed
            K->>P: Void payment authorization
            P->>K: PaymentVoided
            K->>O: Mark order as failed
            O->>K: OrderFailed
            K->>N: Send failure notification
        end
    else Payment Failed
        P->>K: PaymentFailed
        K->>O: Update order
        O->>K: OrderFailed
        K->>N: Send failure notification
    end

Saga Characteristics

Property Implementation Guarantee
Atomicity Compensating transactions All or nothing eventually
Consistency Event ordering per partition State transitions ordered
Isolation Optimistic locking Concurrent saga handling
Durability Kafka persistence Events never lost

Querying Data Across Services

Retrieving data that spans multiple service boundaries.

Approach 1: BFF Aggregation

sequenceDiagram
    participant C as Client
    participant BFF as BFF-Web
    participant O as Orders
    participant P as Payments
    participant I as Inventory

    C->>BFF: GET /api/v1/orders/123/details

    par Parallel gRPC Calls
        BFF->>O: GetOrder(123)
        BFF->>P: GetPayment(order.payment_id)
        BFF->>I: GetInventoryStatus(order.items)
    end

    O-->>BFF: Order data
    P-->>BFF: Payment data
    I-->>BFF: Inventory data

    BFF->>BFF: Aggregate response
    BFF-->>C: Complete order details

Approach 2: GraphQL Federation

sequenceDiagram
    participant C as Client
    participant GQL as GraphQL Gateway
    participant O as Orders
    participant P as Payments
    participant I as Inventory

    C->>GQL: query {
  order(id: "123") {
    items { name, price }
    payment { status }
    inventory { available }
  }
}

    Note over GQL: Parse query,
plan execution

    par Federated Queries
        GQL->>O: GetOrder(123)
        GQL->>P: GetPaymentStatus(...)
        GQL->>I: CheckInventory(...)
    end

    GQL->>GQL: Merge results
    GQL-->>C: {order: {...}}

Choosing the Right Approach

  • BFF: Best for specific client needs, mobile optimization
  • GraphQL: Flexible queries, reduce over-fetching, client-driven
  • CQRS Read Models: Pre-computed views, eventual consistency acceptable

Error Handling and Resilience

How the platform handles failures at different layers. 

graph TB
    START[Request Initiated]
    
    START --> GW_CHECK{Gateway Available?}
    GW_CHECK -->|No| FAIL_FAST[503 Service Unavailable]
    GW_CHECK -->|Yes| AUTH_CHECK{Auth Valid?}
    
    AUTH_CHECK -->|No| UNAUTH[401 Unauthorized]
    AUTH_CHECK -->|Yes| RATE_CHECK{Within Rate Limit?}
    
    RATE_CHECK -->|No| RATE_LIMIT[429 Too Many Requests]
    RATE_CHECK -->|Yes| SVC_CALL[Call Backend Service]
    
    SVC_CALL --> MESH_CHECK{Service Healthy?}
    MESH_CHECK -->|Circuit Open| FALLBACK[Return Cached/Default]
    MESH_CHECK -->|Circuit Closed| GRPC_CALL[gRPC Request]
    
    GRPC_CALL --> TIMEOUT{Response in Time?}
    TIMEOUT -->|No| RETRY{Retry Allowed?}
    TIMEOUT -->|Yes| SUCCESS[200 OK]
    
    RETRY -->|Yes| BACKOFF[Exponential Backoff]
    BACKOFF --> GRPC_CALL
    RETRY -->|No| TIMEOUT_ERR[504 Gateway Timeout]
    
    style SUCCESS fill:#4caf50,color:#fff
    style FAIL_FAST fill:#f44336,color:#fff
    style UNAUTH fill:#ff9800,color:#fff
    style RATE_LIMIT fill:#ff9800,color:#fff
    style TIMEOUT_ERR fill:#f44336,color:#fff

Error Response Format

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Order with ID 123 not found",
    "details": [
      {
        "field": "order_id",
        "issue": "No order exists with this identifier"
      }
    ],
    "trace_id": "a1b2c3d4e5f6",
    "timestamp": "2026-01-09T10:30:00Z"
  }
}

Authentication and Authorization

Security flows using OIDC/OAuth2 for user authentication. 

sequenceDiagram
    participant U as User
    participant App as Application
    participant GW as API Gateway
    participant IDP as Identity Provider
    participant API as Backend API

    Note over U,IDP: Initial Authentication
    U->>App: Access application
    App->>IDP: Redirect to login
    IDP->>U: Login page
    U->>IDP: Credentials
    IDP->>IDP: Validate credentials
    IDP-->>App: Authorization code
    App->>IDP: Exchange code for tokens
    IDP-->>App: access_token + refresh_token

    Note over U,API: API Request with Token
    U->>App: Perform action
    App->>GW: API request
Authorization: Bearer {access_token}
    GW->>GW: Validate JWT signature
    GW->>GW: Check expiration
    GW->>GW: Extract claims (user_id, roles)
    
    alt Token Valid
        GW->>API: Forward with user context
        API->>API: Check authorization (RBAC)
        API-->>GW: Response
        GW-->>App: 200 OK
    else Token Expired
        GW-->>App: 401 Unauthorized
        App->>IDP: Refresh token
        IDP-->>App: New access_token
    end

Security Headers

Header Purpose Example
Authorization Bearer token authentication Bearer eyJhbGciOiJSUzI1...
X-Request-ID Request correlation 550e8400-e29b-41d4-a716
X-Trace-ID Distributed tracing a1b2c3d4e5f6g7h8
X-Client-Version API version negotiation v1.2.0

Monitoring and Debugging

Using observability tools to track request flows and diagnose issues.

Distributed Trace Example

gantt
    title Request Trace Timeline (trace_id: abc123)
    dateFormat X
    axisFormat %L ms

    section API Gateway
    Validate Token :0, 5
    Rate Limit Check :5, 8
    
    section BFF-Web
    Receive Request :8, 10
    Parse JSON :10, 15
    
    section Orders Service
    gRPC Call :15, 20
    DB Query :20, 65
    Build Response :65, 70
    
    section BFF-Web
    Convert to JSON :70, 75
    
    section API Gateway
    Send Response :75, 80

Key Metrics to Monitor

Metric Description Alert Threshold
Request Rate Requests per second > 1000 rps
Latency p95 95th percentile response time > 500ms
Error Rate Percentage of failed requests > 1%
Circuit Breaker State Open/Closed/HalfOpen Open state

API Versioning Strategy

How the platform manages API evolution without breaking clients. 

graph LR
    subgraph Clients[Clients]
        C1[Old Client v1]
        C2[New Client v2]
    end

    subgraph Gateway[API Gateway]
        V1[API v1 orders]
        V2[API v2 orders]
    end

    subgraph BFF[BFF Layer]
        BFF1[BFF v1 Logic]
        BFF2[BFF v2 Logic]
    end

    subgraph Services[Backend Services]
        SVC[Orders Service
gRPC v2 compatible]
    end

    C1 -->|/api/v1/orders| V1
    C2 -->|/api/v2/orders| V2

    V1 --> BFF1
    V2 --> BFF2

    BFF1 -->|gRPC v1 adapter| SVC
    BFF2 -->|gRPC v2 native| SVC

    style Clients fill:#e3f2fd
    style Gateway fill:#fff3e0
    style BFF fill:#f3e5f5
    style Services fill:#e8f5e9

Versioning Best Practices

Integration Example - Partner API

Complete example of a third-party system integrating with Panglot.

Step 1: Authentication

POST https://api.panglot.io/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=partner_xyz&
client_secret=secret_abc&
scope=orders:write payments:read

Step 2: Create Order

POST https://api.panglot.io/api/v1/orders
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "customer_id": "cust_123",
  "items": [
    {
      "product_id": "prod_456",
      "quantity": 2,
      "unit_price": 29.99
    }
  ],
  "shipping_address": {
    "street": "123 Main St",
    "city": "Springfield",
    "postal_code": "12345",
    "country": "US"
  }
}

Step 3: Poll Order Status

GET https://api.panglot.io/api/v1/orders/ord_789
Authorization: Bearer {access_token}

Response:
{
  "id": "ord_789",
  "status": "CONFIRMED",
  "created_at": "2026-01-09T10:30:00Z",
  "total_amount": 59.98,
  "payment_status": "CAPTURED"
}

Best Practices

🔐 Security

  • Always use HTTPS in production
  • Rotate API keys and tokens regularly
  • Implement request signing for sensitive operations
  • Validate all input data on client and server

⚡ Performance

  • Use appropriate pagination for large datasets
  • Implement client-side caching with ETags
  • Batch requests when possible to reduce round trips
  • Use WebSockets for real-time updates instead of polling

🔄 Reliability

  • Implement exponential backoff for retries
  • Handle idempotency with client-generated request IDs
  • Gracefully degrade when optional services are unavailable
  • Monitor error rates and set up alerts

📊 Observability

  • Include trace IDs in all logs
  • Track business metrics alongside technical metrics
  • Set up dashboards for key user journeys
  • Implement structured logging with consistent formats