Skip to main content

System Overview

This document provides a high-level overview of the Citadel platform's architecture, its key components, and the core architectural patterns that govern its design.

C4 Model: System Context Diagram​

The following diagram illustrates the system's context, showing the primary services, users, and external dependencies in the client-hinted claims enrichment flow.

Core Architectural Patterns​

Claims Enrichment at the Edge​

The iam-service acts as a Policy and Claims Enrichment Engine. This architecture establishes a clear separation of concerns between identity authentication (handled by the IdP) and authorization policy (handled by iam-service).

  1. Authentication is Delegated: The upstream IdP is solely responsible for user authentication.
  2. Client Provides Context: On each API call, the client application sends the IdP token and an X-Active-Tenant-ID header, indicating the user's desired context.
  3. Enrichment and Validation via Internal API: The API Gateway passes the token and the tenant hint to the iam-service's internal /system/enrich-token endpoint.
  4. Policy is Centralized: The iam-service validates the token, and critically, verifies that the user is a member of the hinted tenant. It then returns the specific claims for that context.
  5. Decoupled Authorization: The gateway forwards the validated claims to the downstream service (e.g., as HTTP headers). This allows downstream services to act on an unambiguous, pre-validated authorization context.

This pattern decouples our services from the identity provider and centralizes the management of application-specific authorization policies within the iam-service.

For a detailed explanation, see ADR-0025: Tenant Switching via Client-Hinted Claims Enrichment.