Technical enablement · 01

Architecture overview

How {{product.name}} is put together: the system context, its main components, where data lives, how it connects to other systems, and the security and non-functional properties an architect needs to assess. Start here, then drill into the components catalogue and deployment.

Executive summary

{{product.name}} measures, governs and optimises the value delivered by AI investments across client engagements. It is a single Next.js 16 App Router application (TypeScript) that serves both the user interface and the API, backed by PostgreSQL for durable state, Redis for hot state and replay protection, and LiteLLM as the gateway through which AI traffic is observed. The decisions that most shape the design are: calculations are pure server-side functions; protected figures are removed by a server-side projection, never hidden in the browser; and money comes only from the reconciled billing stream.

System context

The context diagram shows {{product.name}} as a single box with the people and systems around it. Capgemini staff and client users use the same application; what each may see is decided server-side (see security and tenancy).

Components

The product is one deployable plus one scheduled job. Per-component detail is in the components catalogue; this table is the map.

Layering rules

1. Domain code is pure

   Calculation modules in lib/domain/ take inputs and a parameter set and return results with provenance. They hold no database or network access, which keeps them unit-testable and out of any client bundle.

2. Everything leaves through the projector

   Route handlers and server components pass domain results through lib/ip-mode/project.ts before they reach a client. A field added to a domain type stays invisible in client mode until someone deliberately adds it (ADR 004).

3. Repositories are tenant-scoped

   Queries take an explicit tenant context. There is no ambient tenant, and every row carries a tenant_id.

Request lifecycle

Two paths matter: the real-time path that observes AI traffic, and the billing path that produces the authoritative money figures.

Real-time path (estimated cost)

1. Model call passes through LiteLLM

   An application or agent calls the gateway. After the call, LiteLLM fires an asynchronous callback; it never blocks the model response.

2. Callback is validated and stored

   POST /api/ingest/litellm verifies the signature, rejects replays using a Redis nonce, resolves tenant, workload and session, and writes a row to token_event_rt. Events are written one at a time, so a single bad event cannot discard a batch.

3. Zone evaluated, change published

   Session counters are updated in Redis, the zone is evaluated by a pure function, and a zone change is published to a Redis channel that feeds the browser over Server-Sent Events (ADR 003).

Billing path (reconciled, authoritative)

1. Sync

   /api/jobs/sync-billing pulls a 72-hour window from every eligible provider connection and upserts token_cost_period on its natural key, so re-runs are safe.

2. Reconcile

   /api/jobs/reconcile compares real-time aggregates with billing per workload and period, classifies discrepancies and recomputes the coverage score.

3. Recompute

   /api/jobs/recompute writes new, immutable calculation_run rows for CPVO, Verified Yield and AYCI. Nothing is edited in place.

Data tiers

The two token tables are structurally separate by design (ADR 006). The real-time table is never a source for a money figure.

Integration points

Every interface that crosses the product boundary. Detail on adding or swapping providers is in Integrations.

Security & tenancy

Orientation only, not a compliance statement. Involve Information Security for approvals.

Non-functional requirements

The targets below are design targets from app-build-brief/03_ARCHITECTURE.md. They are not measured service levels.

Key decisions & open risks

ADR-001  LiteLLM as gateway substrate               Accepted
ADR-002  Postgres, not a time-series database       Accepted
ADR-003  Server-Sent Events, not WebSockets         Accepted
ADR-004  Server-side mode projection                Accepted
ADR-005  No prompt or completion content storage    Accepted
ADR-006  TDAL unified schema lock (FOCUS 1.5)       Locked
ADR-007  Azure Web App deployment                   Accepted (see note)
ADR-008  Govern module architecture                 Accepted
ADR-009  Attribute module: CPVO engine              Accepted
ADR-010  Agentic governance: Gate A and Component 8 Accepted

• Gateway bypass. Agents that call model SDKs directly sit outside Gate A coverage; this is a named gap surfaced on the Connections page (ADR 001).
• Revisit triggers. Postgres for real-time events is revisited if single-day partition queries exceed 200 ms p95 (ADR 002); LiteLLM is revisited at sustained high gateway volume for one tenant (ADR 001). Neither threshold has been observed. ADR 002 sets a numeric trigger (200 ms p95); ADR 001 deliberately leaves its threshold unset until one is seen, so none is recorded.
• Request-path sync. The billing sync runs inside an HTTP request. Persistent deferrals mean more connections than one run can service; the runbook's remedy is to split the schedule or move the sync out of the request path.