API Gateway¶

Overview¶

The API Gateway serves as the single entry point into the VitalBridge platform.

All external requests from web applications, mobile applications, and third-party integrations pass through the gateway before reaching domain services.

The gateway centralizes several cross-cutting concerns including:

Request routing
Authentication
Authorization
Tenant context propagation
API versioning
Request validation
Rate limiting
Request aggregation

Domain services remain focused on business logic while the gateway handles platform-wide concerns.

Responsibilities¶

The API Gateway is responsible for:

Request Routing¶

Routes incoming requests to the appropriate domain service.

Examples:

Route	Target Service
`/v1/tenants`	Tenant Registry Service
`/v1/providers`	Doctor Service
`/v1/patients`	Patient Service
`/v1/schedules`	Doctor Schedule Service
`/v1/appointments`	Appointment Service

Authentication¶

Validates JWT access tokens issued by Keycloak.

Unauthenticated requests are rejected before reaching domain services.

Authorization¶

Performs initial role validation.

Examples:

Super Administrator
Tenant Administrator
Provider
Patient

Domain services perform additional authorization checks.

Tenant Context Propagation¶

Extracts tenant information from the authenticated user context and forwards it to downstream services.

This enables service-level tenant isolation.

API Versioning¶

Provides a stable public API surface.

Example:

/v1/appointments
/v1/providers
/v1/patients

Future versions may coexist without affecting existing clients.

High-Level Architecture¶

flowchart TB

    CLIENT["Client Application"]

    GATEWAY["API Gateway"]

    KC["Keycloak"]

    CLIENT --> GATEWAY

    GATEWAY --> KC

    GATEWAY --> TENANT["Tenant Registry Service"]

    GATEWAY --> ADMIN["Admin Service"]

    GATEWAY --> DOCTOR["Doctor Service"]

    GATEWAY --> PATIENT["Patient Service"]

    GATEWAY --> SCHEDULE["Doctor Schedule Service"]

    GATEWAY --> APPOINTMENT["Appointment Service"]

    GATEWAY --> VIDEO["Video Session Service"]

Hold "Alt" / "Option" to enable pan & zoom

Request Lifecycle¶

The following diagram illustrates the lifecycle of a typical request.

sequenceDiagram

    participant Client

    participant Gateway

    participant Keycloak

    participant Service

    Client->>Gateway: HTTP Request + JWT

    Gateway->>Keycloak: Validate Token

    Keycloak-->>Gateway: Token Valid

    Gateway->>Gateway: Validate Role

    Gateway->>Gateway: Extract Tenant Context

    Gateway->>Service: Forward Request

    Service-->>Gateway: Response

    Gateway-->>Client: Response

Hold "Alt" / "Option" to enable pan & zoom

Authentication Flow¶

Authentication is delegated to Keycloak.

sequenceDiagram

    participant User

    participant Keycloak

    participant Gateway

    User->>Keycloak: Login

    Keycloak-->>User: Access Token

    User->>Gateway: Request + JWT

    Gateway->>Gateway: Validate JWT

    Gateway-->>User: Authorized

Hold "Alt" / "Option" to enable pan & zoom

The gateway never stores credentials.

Identity management remains externalized.

Tenant Context Propagation¶

Multi-tenancy is enforced using tenant context.

flowchart LR

    JWT["JWT Token"]

    GATEWAY["API Gateway"]

    TENANT["Tenant Context"]

    SERVICE["Domain Service"]

    JWT --> GATEWAY

    GATEWAY --> TENANT

    TENANT --> SERVICE

Hold "Alt" / "Option" to enable pan & zoom

Each request forwarded to a domain service includes:

User ID
Role
Tenant ID
Correlation ID

Role-Based Access¶

The gateway performs initial authorization checks.

flowchart TB

    REQUEST["Incoming Request"]

    JWT["Validate JWT"]

    ROLE["Validate Role"]

    TENANT["Extract Tenant"]

    ROUTE["Route Request"]

    REQUEST --> JWT

    JWT --> ROLE

    ROLE --> TENANT

    TENANT --> ROUTE

Hold "Alt" / "Option" to enable pan & zoom

Authorization failures are rejected immediately.

Correlation IDs¶

Every request receives a correlation identifier.

flowchart LR

    CLIENT["Client"]

    GATEWAY["Gateway"]

    SERVICE_A["Service A"]

    SERVICE_B["Service B"]

    CLIENT --> GATEWAY

    GATEWAY -->|"Correlation ID"| SERVICE_A

    SERVICE_A -->|"Same Correlation ID"| SERVICE_B

Hold "Alt" / "Option" to enable pan & zoom

Benefits:

Distributed tracing
Auditability
Easier debugging
Request tracking

Error Handling¶

The gateway standardizes platform-wide error responses.

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Access denied"
  }
}

This ensures a consistent experience across all services.

Security Boundaries¶

The gateway performs:

JWT validation
Initial authorization
Tenant extraction

However, security is not delegated entirely to the gateway.

flowchart LR

    USER["User"]

    GATEWAY["API Gateway"]

    SERVICE["Domain Service"]

    USER --> GATEWAY

    GATEWAY --> SERVICE

    SERVICE -->|"Authorization"| SERVICE

    SERVICE -->|"Tenant Validation"| SERVICE

Hold "Alt" / "Option" to enable pan & zoom

Every service remains responsible for:

Authorization
Resource ownership validation
Business-level security rules

What the Gateway Does Not Do¶

The gateway does not:

Execute business logic
Access service databases
Publish domain events
Manage appointments
Manage schedules
Manage patient data

Those responsibilities belong to the owning domain services.

Design Principles¶

The VitalBridge API Gateway follows several principles:

Thin Gateway¶

Business logic belongs in services.

Single Entry Point¶

All external requests enter through the gateway.

Stateless Processing¶

Requests can be processed by any gateway instance.

Centralized Security¶

Authentication and routing are centralized.

Tenant Awareness¶

Tenant context is propagated consistently across all services.

Future Enhancements¶

The gateway architecture supports future capabilities including:

API rate limiting
Request throttling
GraphQL federation
API analytics
Service mesh integration
WebSocket gateway support
Edge caching

These features can be introduced without affecting downstream services.