Technical enablement · 02

Components & services catalogue

A reference for every building block of {{product.name}}: what it is responsible for, its interfaces, what it depends on and how to operate it. Every entry follows the same four-part structure so readers can compare components consistently. Filter by category or search, and click an entry to expand it.

ⓘ

One application, several layers. {{product.name}} is a modular monolith: most "components" below are directories in one repository that ship in one container image. Paths are relative to the repository root, so you can verify each entry against source.

How each component is documented

Section	Answers
Responsibility	What single job it does, and what it does not do.
Interfaces	Routes, functions or events it exposes.
Dependencies	What it calls and what happens when that is down.
Operations	Source path, runtime, configuration keys and tests.

Experience & API

What users and calling systems touch. Route groups under app/ separate the internal workspace from the client workspace.

Responsibility

Capgemini-only surfaces: Home, Engagements (portfolio, create, manage), Checkpoints (queue, detail, capacity), Escalations, Calibration and Admin. Not visible to client roles.

Interfaces

Server components and server actions (actions.ts, checkpoint-actions.ts). Navigation is filtered by role in components/nav/sidebar.tsx.

Dependencies

Repositories in lib/db/repositories/; domain library; session from lib/auth.

Operations

Deployed with the app image. See roles for which role sees which page.

Responsibility

The engagement workspace: Overview, Connections, Govern, Attribute, Agentic and Optimise. Every page can render in internal or client mode.

Interfaces

URL segment [tenantSlug] resolved against the session's authorised tenants. Period selection is a URL search parameter (?period=YYYY-MM), so views are bookmarkable. Mode can be set with ?mode=.

Dependencies

Mode projector (lib/ip-mode/project.ts); repositories; domain library.

Operations

Tenants carry a tier (diagnostic, tier_1, tier_2, tier_3) that gates parts of the navigation. Tenants flagged as demo show a DEMO badge.

Responsibility

The HTTP surface outside the pages: ingest webhooks, Gate A, checkpoints and escalations, optimisation, exports, job triggers, SaaS connectors, health and Auth.js handlers.

Interfaces

ingest/litellm, ingest/outcomes; gate-a; agentic/sessions/[sessionId]/events (SSE); checkpoints (+ decide, escalate); escalations (+ resolve, route-l3); optimise (+ authorise, execute, measure); export/{govern,attribute,agentic,savings}; ayci; saas/connectors; jobs/{sync-billing,reconcile,recompute}; health.

Dependencies

Repositories, domain library, Redis (ingest and SSE). Machine paths (/api/jobs, /api/ingest, /api/gate-a) are exempt from the session check and authenticate with their own credential.

Operations

/api/health is a public liveness probe returning status and timestamp only; it does not check the database or Redis.

Responsibility

Presentational components grouped by module (govern, attribute, agentic, optimise, checkpoints, connections, calibration, admin, engagements), plus navigation, brand and help. One checkpoint console component serves every gate.

Interfaces

React props. Client components never receive protected values; uncertainty is shown with an inferred-value marker (components/brand/inferred-marker.tsx) rather than a dismissible modal.

Dependencies

Tailwind CSS 4, Recharts for charts.

Operations

Built with the app. No separate release.

Core logic

The calculation and policy code. It is deliberately free of I/O so it can be tested against fixtures.

Responsibility

Pure functions for CPVO (cpvo.ts), Verified Yield (verified-yield.ts), AYCI (ayci.ts), zone evaluation (zones.ts), Gate A policy (gate-a.ts), checkpoint confidence and options (confidence.ts, checkpoint-options.ts), drivers and opportunities, optimisation categories, baselines and gateway-key resolution. It does not read the database or the network.

Interfaces

Exported functions taking inputs and a parameter set, returning a result plus provenance. CPVO has six explicit states and returns no number for any state other than OK (ADR 009).

Dependencies

Calibration parameters passed in by the caller.

Operations

Tests in tests/domain/. A structural test asserts CPVO code never references the real-time table. Shared formulas such as Verified Yield are imported, never reimplemented.

Responsibility

Decides what a given role and mode may see (project.ts) and holds the protected-field policy (protected.ts). Resolves the effective mode: client roles are locked to client mode whatever the toggle says.

Interfaces

resolveMode, isInternalRole, isClientRole and the projection functions used by route handlers and server components.

Dependencies

Role definitions. Server-only.

Operations

Tests in tests/ip-mode/ (leakage, tenancy, redaction) run in CI and block merge. Every new domain result type needs a declared client-mode shape (ADR 004).

Responsibility

Versioned parameter sets that every calculation records. Publishing a new version never rewrites history. Parameter values are protected and are not documented here.

Interfaces

Calibration page in the internal workspace; sets move through a draft, published, superseded and archived lifecycle.

Dependencies

Database tables for parameter sets; default tables under config/.

Operations

Restricted to capability_owner and platform_admin. Values are marked calibrated or default, and confidence is capped when defaults are in use.

Data & ingestion

Everything between a provider's data and the tables the calculations read.

Responsibility

Maps every provider into one schema using FOCUS 1.5 field names (schema.ts), normalises records (normalise.ts), reconciles real-time against billing (reconcile.ts) and scores data completeness (completeness.ts). The schema is locked (ADR 006): adding a column is safe, renaming one is not.

Interfaces

The ProviderAdapter contract in adapters/base.ts, registered in adapters/registry.ts, which is the single list of providers that can actually sync.

Dependencies

Provider billing and metrics APIs; retry profiles in adapters/retry.ts.

Operations

Contract tests per adapter in tests/domain/adapters-*.test.ts. See Integrations.

Responsibility

One adapter per provider. Registered today: OpenAI, Anthropic, Azure OpenAI, AWS Bedrock and Google Vertex AI. Supporting modules handle AWS request signing, Azure and Google token acquisition, BigQuery decoding, Google price catalogue lookup and credential resolution.

Interfaces

verify() (promotes a connection to active and reports the granted scope) and fetchPeriod() (pulls billing for a window).

Dependencies

Per-connection credentials resolved by credentials.ts. Generic SaaS connections are configurable but have no sync adapter, so they stay disconnected by design and the UI says so. Where Google publishes no cost API and no billing export is configured, Vertex cost is estimated from list prices and marked as estimated.

Operations

Two retry profiles: interactive (fails within seconds) and background (outlasts a rate-limit window within the request ceiling).

Responsibility

Drizzle client and schema (schema.ts), tenant context (tenant-context.ts), migrations, seed data and tenant-scoped repositories: admin, agentic, attribute, checkpoints, gateway-keys, govern, optimise, tenants, workloads.

Interfaces

Functions taking an explicit tenant context. Billing and real-time reads live in separate repository modules so a mistaken join is visible in review.

Dependencies

PostgreSQL through DATABASE_URL.

Operations

Partitioned tables are created in raw SQL migrations, not by Drizzle. Additive migrations in scripts/migrate-*.ts run before the release that needs them. See migrations.

Responsibility

Shared ioredis connection used for session counters, zone pub/sub behind the SSE stream and the replay nonce for gateway callbacks.

Interfaces

getRedis().

Dependencies

A managed Redis reachable through REDIS_URL. Gateway callbacks need it for replay protection, so make deploy refuses to run without it.

Operations

Non-durable by design; state is journalled to PostgreSQL for audit.

Platform & shared

Cross-cutting services: identity, scheduling, the gateway and packaging.

Responsibility

Auth.js v5 configuration for Microsoft Entra ID (config.ts), session helpers (index.ts), log redaction (redact.ts). The proxy applies the session check to every route that is not public or machine-authenticated.

Interfaces

OIDC callback at /api/auth/callback/azure-ad. Environment variables: AUTH_SECRET, AUTH_URL, AUTH_TRUST_HOST, ENTRA_CLIENT_ID, ENTRA_CLIENT_SECRET, ENTRA_TENANT_ID.

Dependencies

Microsoft Entra ID; the user table for the provisioned role.

Operations

A misconfigured tenant id shows as an unresolvable issuer; a wrong AUTH_URL as a redirect-URI mismatch. AUTH_BYPASS=true grants a fixed admin session and is local development only.

Responsibility

Calls sync-billing, then reconcile, then recompute over HTTP so they execute inside the web app's process, which holds the database pool, the adapters and the managed identity. lib/jobs/ holds the shared secret check (cron-auth.ts), the recompute engine and spend attribution.

Interfaces

Environment: JOBS_BASE_URL, CRON_SECRET, JOBS_LOOKBACK_HOURS (default 72). Does not follow redirects, because a 3xx means something intercepted the request.

Dependencies

The web app's job routes. One job failing does not stop the others; the run exits non-zero on failure.

Operations

Runs as the Container Apps Job ca-ai-yield-cron. See scheduled jobs.

Responsibility

Receives LiteLLM callbacks and resolves each event to a workload. Resolution order: the key's own workload id (when it is a valid id the tenant actually holds), then a stored key-to-workload map, then unattributed. Unattributed events are stored, not lost, and can be named later in the app.

Interfaces

POST /api/ingest/litellm; secret LITELLM_CALLBACK_SECRET must match the gateway's.

Dependencies

LiteLLM proxy (separate container); Redis.

Operations

Warnings naming a key and a missing workload are logged with the [litellm] prefix. Gateway traffic never changes a CPVO figure; it feeds the real-time stream only.

Responsibility

Two-stage build on Node 20 Alpine producing a Next.js standalone bundle that runs as a non-root user and listens on port 3000. The same image runs the web app (node server.js) and the scheduled job (node /app/scripts/run-jobs.mjs).

Interfaces

Port 3000; build needs no environment variables, which is what keeps CI secret-free.

Dependencies

Azure Container Registry for storage.

Operations

Tagged with the short git commit SHA. See Deployment.

ⓘ

Owner: the product team owns every area listed here; there is no per-area split. Support route: the contact address and support link in the page footer; infrastructure and deploy issues go to whoever holds admin access to the Azure resource group, and privacy questions to the Data Privacy Officer. Proposed: name one owner each for the web app, scheduled jobs, connection adapters and gateway integration once the team grows. For the user-facing view of these components see the feature reference.