Technical architecture

• 01 System architecture
• 02 The runtime pipeline
• 03 Service description schemas
• 04 Data model
• 05 Policy evaluator and state machine
• 06 Consent manager and field collector
• 07 Evidence plane
• 08 FLEX and UDP integration

Every citizen interaction passes through this 14-step orchestrator pipeline. Deterministic code runs before and after the language model; the platform always has the final word.

Service strategy pattern

The orchestrator does not know how a service is implemented. It delegates through a pluggable ServiceStrategy interface. Three modes exist today.

interface ServiceStrategy {
  buildTools(ctx: ServiceStrategyContext): ToolDefinition[];
  buildServiceContext(ctx: ServiceStrategyContext): string | Promise<string>;
  dispatchToolCall(name: string, input: unknown): Promise<string>;
  extractStateTransitions(messages: unknown[]): StateTransitionResult[];
}

JsonServiceStrategy (deterministic, inline) — no tools are given to the LLM. Service context is built entirely from structured service descriptions and the field collector. All state transitions are proposed by the LLM in its structured output and validated by the state machine.

McpServiceStrategy (tool-based) — the LLM receives check_eligibility and advance_state tools. It calls these during the agentic loop. Tool results are parsed for state transitions.

Demo mode — scripted responses bypass the orchestrator entirely. Each persona has a pre-authored script that drives the conversation deterministically, with no LLM calls. Used for conference demonstrations and stakeholder walkthroughs.

All three modes produce identical output contracts. The citizen application cannot distinguish which strategy was used.

OrchestratorOutput

Every pipeline run produces a single typed output. This is the contract between the runtime and the citizen application.

interface OrchestratorOutput {
  response: string;
  reasoning: string;
  toolsUsed: string[];
  conversationTitle: string | null;
  tasks: TaskEntry[];
  policyResult?: { eligible: boolean; explanation: string };
  handoff?: { triggered: boolean; reason: string };
  serviceState?: { currentState: string; stateHistory: string[] };
  consentRequests?: ConsentRequest[];
  extractedFields?: FieldExtraction[];
  serviceCompletions?: Array<{ serviceId: string; status: string }>;
  versionMetadata: {
    promptHash: string;
    rulesetVersion: string;
    stateModelVersion: string
  };
  pipelineTrace: {
    traceId: string;
    steps: PipelineStep[];
    totalDurationMs: number
  };
}

A unified data model for citizen information with field-level provenance, tiered trust levels, and deduplication across services.

Three tiers of trust

Every data field carries a trust tier that determines how it can be used, whether it requires consent to share, and whether the citizen can edit it.

Field source attribution

Every field in the citizen data model carries source metadata. This enables the platform to show exactly where each piece of data came from and which consent grant authorised its use.

interface FieldSource {
  source: string;     // "HMRC", "DVLA", "Home Office"
  tier: "verified" | "submitted" | "inferred";
  topic: string;     // "identity", "finance", "employment"
}

Canonical alias map for deduplication

When a life event triggers multiple services, the field merger deduplicates data fields using a canonical alias map. Different services may use different names for the same piece of data — "ni_number", "national_insurance_number", and "nino" all resolve to the same canonical field. The agent asks once, and the answer fans out to all services that need it.

{
  "national_insurance_number": ["ni_number", "nino", "niNumber"],
  "full_name": ["fullName", "name", "legal_name"],
  "date_of_birth": ["dateOfBirth", "dob", "birth_date"],
  "address": ["postal_address", "home_address", "correspondence_address"]
}

Pre-fill logic

When a service is loaded, the FieldCollector seeds from the identity's input_schema.required array and checks each field against the citizen's profile using the alias map. Fields already present are marked as collected with their source attribution. The remaining fields become the "missing" list that the prompt layer injects into the system prompt, enabling the LLM to ask targeted questions rather than repeating information the citizen has already provided.

Base fields (all citizens)

Persona-specific fields (examples)

How consent is enforced as a hard gate, and how the platform tracks every data field from collection through to sharing.

ConsentManager

Manages the citizen's consent decisions for a service. Each service defines a data sharing model with required and optional grants. The manager tracks which grants have been presented, accepted, or declined, and gates progress accordingly.

class ConsentManager {
  getRequiredGrants(): ConsentGrant[]
  getOptionalGrants(): ConsentGrant[]
  recordDecision(
    grantId: string,
    granted: boolean
  ): ConsentDecision
  allRequiredGranted(): boolean
}

Consent is never assumed or inferred. The platform renders consent cards (deterministic task injection at pipeline step 11) and records the citizen's explicit decision. If a required grant is declined, the journey cannot proceed past the consent state.

Standing preferences allow a citizen to set a consent scope: once (this service interaction only), service (all future uses of this service), department (all services from this department), or cross-government (all services). Standing preferences are resolved before the consent card is shown — if a matching preference exists, the grant is auto-satisfied.

Revocation is supported at any time. When consent is withdrawn, the platform ceases to share the affected data fields. The revocation is recorded as an immutable trace event.

FieldCollector

Tracks the data fields required by a service, pre-fills from citizen data where available, and records new fields extracted from conversation. The collector tells the prompt layer what is still missing, enabling the LLM to ask targeted questions.

class FieldCollector {
  seed(personaData: Record<string, unknown>): void
  recordField(
    key: string,
    value: unknown,
    source: string
  ): void
  getMissing(): string[]
  isComplete(): boolean
}

The field collector uses the canonical alias map to recognise that "niNumber" and "national_insurance_number" are the same field. When a citizen provides their NI number for one service, the collector marks it as collected for every service in the active plan that needs it. This is how the system avoids asking the same question twelve times across a bereavement journey.

The Agentic Legibility Stack sits on top of the FLEX platform and Unified Data Platform. FLEX provides the secure pipes; ALS adds the intelligence that turns those pipes into a joined-up citizen experience.

Two layers, complementary

CapabilityInvoker as the bridge

Every department service call routes through the CapabilityInvoker, which calls the FLEX Public Gateway. The invoker logs the request, checks consent, calls the gateway, logs the response, and emits a trace event. No service call ever bypasses this path.

What ALS adds that FLEX does not

FLEX is the plumbing — how data moves securely between departments and the app. ALS is the intelligent front-of-house — how an AI agent uses those pipes on behalf of a citizen. Six capabilities sit above FLEX: