WhiteBooks API Architecture

A view from above of how a customer request flows from your ERP / app, through the WhiteBooks API gateway, to the upstream GSTN / IRP / NIC system, and back — including the retry, queueing, webhook, and audit layers that make it work at enterprise scale.

Request flow (logical)

┌─────────────┐    HTTPS     ┌────────────────────┐    OAuth     ┌──────────────────┐
│ Your ERP /  │───────────────│ WhiteBooks API     │──────────────│ Auth + Token     │
│ app / SDK   │  Bearer token │ Gateway (Cloudfront) │            │ Service          │
└─────────────┘               └────────┬───────────┘              └──────────────────┘
                                       │
                                       ▼
                                 ┌──────────────┐
                                 │ Rate-limit + │
                                 │ IP allow-list│
                                 └──────┬───────┘
                                        │
                              ┌─────────┴─────────┐
                              ▼                   ▼
                     ┌────────────────┐  ┌────────────────┐
                     │ Retry queue    │  │ Idempotency    │
                     │ (SQS / Kafka)  │  │ store (Redis)  │
                     └────────┬───────┘  └────────────────┘
                              │
                              ▼
                     ┌────────────────┐
                     │ Upstream       │
                     │ adapter        │
                     └────────┬───────┘
                              │
            ┌─────────────────┼─────────────────┐
            ▼                 ▼                 ▼
      ┌──────────┐      ┌──────────┐     ┌──────────┐
      │ GSTN     │      │ IRP      │     │ NIC EWB  │
      │ portal   │      │ (e-Inv)  │     │ system   │
      └──────────┘      └──────────┘     └──────────┘

                              ▼
                     ┌────────────────┐         ┌────────────────┐
                     │ Audit log      │────────▶│ Your webhook   │
                     │ (immutable)    │  event  │ endpoint        │
                     └────────────────┘         └────────────────┘

Layers

• Edge — TLS 1.2+ termination, CDN cache for static assets, geographic routing.
• Gateway — OAuth 2.0 token verification, rate-limit enforcement (per client_id), optional IP allow-list, optional SHA256-RSA signature check.
• Application — request validation against OpenAPI schema, idempotency key dedup, business-logic mapping (e.g. invoice → IRP payload).
• Queue — retry queue for transient upstream failures (NIC / IRP timeouts), back-pressure for bulk operations.
• Upstream adapters — per-target adapters for GSTN portal, NIC e-Way Bill, IRP (e-Invoice), ZATCA FATOORA. Each handles auth, request shaping, response parsing, and error-code translation.
• Audit + webhook — every state-changing event writes to an immutable audit log and fires a webhook to the customer's registered URL.

Multi-region deployment

Active in ap-south-1 (Mumbai, primary) and ap-south-2 (Hyderabad, secondary). Cross-region replication on the audit log; failover automated. Enterprise customers can request VPC peering or dedicated single-tenant infrastructure.

Data residency

All Indian-business data is stored exclusively in India (ap-south-1 + ap-south-2). KSA business data is stored exclusively in Saudi Arabia (me-south-1). No cross-border transfer of regulated tax data.

Related

Part of the WhiteBooks Enterprise cluster. Last updated 27 May 2026.