Partner API Gateway Architecture

packages/api is a Partner API Gateway that provides a unified entry point for enterprise partners. It handles partner authentication, rate limiting, usage tracking, and service routing.

Architecture Layers

Partner Request
    ↓
[Partner API Gateway] (packages/api)
    ├── Partner Auth (API Key + Tenant ID)
    ├── Rate Limiting (per partner)
    ├── Usage Tracking
    ├── Service Access Control
    ↓
[Service-Specific Gateways] (packages/workers/*)
    ├── pharmacy-api-gateway → Firebase Functions
    ├── (future) brand-api-gateway → Backend Service
    ├── (future) clinician-api-gateway → Backend Service
    ↓
[Backend Services]
    ├── Firebase Functions (Pharmacy operations)
    ├── Other backend services

Key Components

1. Partner Authentication

File: packages/api/src/middleware/partner-auth.ts

Validates API key + tenant ID against D1 database and attaches partner context to request.

Authentication Methods:

• Authorization: Bearer <api_key> + X-Tenant-ID: <tenant_id>
• X-API-Key: <api_key> + X-Tenant-ID: <tenant_id>
• Authorization: Bearer <api_key> + ?tenant_id=<tenant_id>

2. Rate Limiting

File: packages/api/src/middleware/rate-limit.ts

Per-partner rate limits (minute/hour/day) using Cloudflare KV for distributed rate limiting. Configurable per partner.

3. Service Access Control

File: packages/api/src/middleware/service-access.ts

Checks if partner has access to requested service and prevents unauthorized service access.

4. Usage Tracking

File: packages/api/src/middleware/usage-tracking.ts

Tracks API usage per partner, logs to KV or analytics service, used for billing/analytics.

5. Service Client

File: packages/api/src/services/client.ts

Proxies requests to backend services, adds partner context headers, handles timeouts and errors.

Technical Stack

• Framework: Hono (Cloudflare Workers compatible)
• Database: Cloudflare D1 (SQLite) for partner authentication
• Validation: Zod schemas
• Documentation: Auto-generated OpenAPI/Swagger specs