AI Usage Billing Gateway

flowchart LR
    UserClient["User Client"]
    ApiClient["API Client"]
    subgraph App["Spring Boot Application"]
      Auth["JWT Auth"]
      Tenant["TenantAccessService"]
      ApiKey["API Key Auth"]
      Gateway["Mock AI Gateway"]
      Usage["Usage Ingestion"]
      Billing["Invoice Generation"]
      Webhook["Payment Webhook"]
      Ledger["Ledger Service"]
      Audit["Audit Service"]
    end
    Postgres[("PostgreSQL")]
    Redis[("Redis Rate Limit")]
    UserClient --> Auth
    Auth --> Tenant
    Tenant --> Billing
    Tenant --> ApiKey
    ApiClient --> ApiKey
    ApiKey --> Gateway
    ApiKey --> Usage
    Gateway --> Redis
    Gateway --> Usage
    Billing --> Ledger
    Webhook --> Ledger
    Tenant --> Audit
    ApiKey --> Audit
    Billing --> Audit
    Webhook --> Audit
    Usage --> Postgres
    Billing --> Postgres
    Ledger --> Postgres
    Audit --> Postgres

erDiagram
    user_accounts ||--o{ organization_members : "belongs"
    organizations ||--o{ organization_members : "has"
    organizations ||--o{ api_keys : "issues"
    organizations ||--o{ usage_events : "records"
    organizations ||--o{ subscriptions : "owns"
    plans ||--o{ subscriptions : "selected"
    organizations ||--o{ invoices : "billed"
    invoices ||--o{ invoice_items : "contains"
    invoices ||--o{ payments : "paid_by"
    organizations ||--o{ payment_webhook_events : "receives"
    organizations ||--o{ ledger_entries : "records"
    organizations ||--o{ audit_logs : "audits"

    user_accounts {
      bigint id PK
      varchar email UK
      varchar password_hash
      timestamp created_at
    }
    organizations {
      bigint id PK
      varchar name
      timestamp created_at
    }
    organization_members {
      bigint id PK
      bigint organization_id FK
      bigint user_id FK
      varchar role
    }
    api_keys {
      bigint id PK
      bigint organization_id FK
      varchar key_prefix
      varchar key_hash
      varchar status
    }
    usage_events {
      bigint id PK
      bigint organization_id FK
      varchar idempotency_key
      varchar request_hash
      varchar metric
      bigint quantity
    }
    invoices {
      bigint id PK
      bigint organization_id FK
      varchar billing_period
      varchar status
      bigint total_amount
      varchar currency
    }
    ledger_entries {
      bigint id PK
      bigint organization_id FK
      uuid transaction_group_id
      varchar account
      varchar direction
      bigint amount
      varchar currency
    }
    audit_logs {
      bigint id PK
      bigint organization_id FK
      varchar event_type
      json metadata
    }

sequenceDiagram
    participant Client as API Client
    participant Filter as ApiKeyAuthenticationFilter
    participant Gateway as Mock Gateway
    participant Redis as Redis Rate Limit
    participant Usage as UsageService
    participant DB as PostgreSQL
    Client->>Filter: X-API-Key
    Filter->>DB: key_prefix lookup + hash compare
    DB-->>Filter: organization context
    Client->>Gateway: POST /v1/gateway/mock-completion
    Gateway->>Redis: fixed-window rate limit
    Gateway->>Usage: record usage event
    Usage->>DB: insert organizationId + Idempotency-Key
    alt duplicate same payload
      DB-->>Usage: existing event
      Usage-->>Client: duplicate=true
    else same key different payload
      DB-->>Usage: request hash mismatch
      Usage-->>Client: 409 Conflict
    end

sequenceDiagram
    participant Admin as Admin User
    participant Billing as BillingService
    participant Webhook as PaymentWebhookService
    participant Ledger as LedgerService
    participant Audit as AuditService
    participant DB as PostgreSQL
    Admin->>Billing: generate invoice(period)
    Billing->>DB: unique organizationId + billingPeriod
    Billing->>Ledger: invoice issued entries
    Ledger->>DB: debit/credit entries
    Billing->>Audit: INVOICE_GENERATED
    Admin->>Webhook: payment.succeeded providerEventId
    Webhook->>DB: reserve providerEventId
    Webhook->>Ledger: payment entries
    Ledger->>DB: balanced entry group
    Webhook->>Audit: PAYMENT_WEBHOOK_PROCESSED

sequenceDiagram
    participant Service as Billing/Payment Service
    participant Ledger as LedgerService
    participant DB as PostgreSQL
    Service->>Ledger: create entry group
    Ledger->>Ledger: positive amount check
    Ledger->>Ledger: single currency check
    Ledger->>Ledger: debit sum == credit sum
    alt valid group
      Ledger->>DB: append ledger_entries
      DB-->>Ledger: saved
    else invalid group
      Ledger-->>Service: reject
    end