Architecture & Integration Guide

The stack is organised as a set of focused packages with strict dependency boundaries. Every package owns one concern; cross-cutting behaviour is mediated through well-typed interfaces.

Package Dependency Graph

The dependency tree is rooted at the Shared Schema Layer, which has zero internal dependencies. All other components declare their internal dependencies explicitly. External SDK usage is confined to two components.

Architectural Rules

Two Applications

Data Layer

Structured artefacts define each service: a capability manifest, policy ruleset, state model, consent model, and state-specific instructions. These artefacts are the canonical description of what a service does, who can use it, and how it progresses.

The evidence store is append-only. Every significant event — state transitions, consent decisions, policy evaluations, credential presentations — is captured as an immutable trace event. The store supports full replay: given a trace ID, the system can reconstruct the exact conversation state at any point.

Personal data is stored with field-level source attribution. Every value carries metadata indicating which department sourced it, whether it is verified or citizen-submitted, and which consent grant authorised its use.

Artefact Structure

Each service in the store is described by up to five artefact files. Together, these form the complete machine-readable description of a government service.

Package Responsibility Summary

Each component in the system owns a single, well-defined concern. This table summarises what each component does and what it must never do.

The core of the deterministic layer. Four classes enforce policy, manage state, handle consent, and collect citizen data — all without any LLM involvement.

PolicyEvaluator

Evaluates a service’s eligibility rules against a citizen’s data. The evaluator iterates each rule, evaluates conditions using typed operators, and returns a structured result. No fuzzy logic, no LLM interpretation — rules either pass or fail.

class PolicyEvaluator {
  evaluate(
    ruleset: PolicyRuleset,
    context: Record<string, unknown>
  ): PolicyResult
}

The evaluation logic iterates rules, evaluates conditions using operators: >=, <=, ==, !=, exists, not-exists, in. Each rule returns a pass/fail result with the original description as an explanation.

interface PolicyRuleset {
  service_id: string;
  version: string;
  rules: PolicyRule[];
}

interface PolicyRule {
  id: string;
  description: string;
  condition: {
    field: string;
    operator: ">=" | "<=" | "==" | "!=" | "exists" | "not-exists" | "in";
    value?: unknown;
  };
  reason_if_failed: string;
  edge_case?: boolean;
}

interface PolicyResult {
  eligible: boolean;
  passed: PolicyRule[];
  failed: PolicyRule[];
  edgeCases: PolicyRule[];
  explanation: string;
}

StateMachine

A deterministic finite-state machine constructed from a service’s StateModelDefinition. It enforces the legal transitions for a service journey, prevents the LLM from skipping steps, and identifies terminal and receipt-emitting states.

class StateMachine {
  constructor(definition: StateModelDefinition)
  getState(): string
  allowedTransitions(): Array<{ to: string; trigger?: string }>
  transition(trigger: string): TransitionResult
  isTerminal(): boolean
  setState(stateId: string): void
}

Key concepts: initial state (where every journey begins), terminal states (completed, rejected, handed-off), transition guards (condition fields that must be satisfied before a transition is allowed), and receipt-emitting states (states that trigger an immutable receipt on entry).

State Flow: DVLA Driving Licence Renewal

A typical service journey. The state model defines a linear path with a branch point at eligibility, where the journey may diverge to rejection or human handoff.

ConsentManager

Manages the citizen’s consent decisions for a service. Each service defines a ConsentModel 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.

FieldCollector

Tracks the data fields required by a service, pre-fills from persona 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
}

ArtefactStore

Loads and caches structured artefacts from the service registry. Each service’s artefact set is loaded once and held in memory for the duration of the session.

class ArtefactStore {
  loadFromRegistry(serviceId: string): Promise<number>
  fetchArtefacts(serviceId: string): Promise<ServiceArtefacts>
  getServiceArtefacts(serviceId: string): ServiceArtefacts | null
}

interface ServiceArtefacts {
  manifest: CapabilityManifest;
  policy?: PolicyRuleset;
  consent?: ConsentModel;
  stateModel?: StateModelDefinition;
  stateInstructions?: StateInstructions;
}

The five artefact types form a complete service description. The manifest declares identity and input schema. The policy defines eligibility rules. The state model defines the journey. The consent model defines data sharing permissions. The state instructions provide per-state behavioural guidance for the agent.

Policy Operator Reference

The PolicyEvaluator supports seven operators for rule conditions. Each operator has strict type semantics — the evaluator does not perform type coercion.

State Model Transition Guards

Transitions can carry guard conditions that must be satisfied before the transition is allowed. Guards prevent premature advancement — a citizen cannot reach “payment-made” without first passing through “details-confirmed”.

{
  "from": "eligibility-checked",
  "to": "consent-given",
  "trigger": "grant_consent",
  "guard": {
    "condition": "policy_result.eligible == true",
    "message": "Cannot proceed: citizen is not eligible for this service."
  }
}

The state machine evaluates guards synchronously. If a guard fails, the transition is rejected and the machine remains at its current state. The guard’s message is available to the agent for explaining why the journey cannot proceed.

A unified data model for citizen information with field-level provenance, tiered trust levels, and delegation-aware access control.

Three Data Tiers

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

Field Metadata

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"
}

RelationshipStore

Manages delegation relationships: parents acting for children, power of attorney holders acting for vulnerable adults, executors managing a deceased person’s affairs. The store enforces scoped permissions and logs every delegated action for audit.

class RelationshipStore {
  canActOnBehalf(
    actorId: string,
    subjectId: string,
    scope: PermissionScope
  ): boolean
  getPermissions(
    actorId: string,
    subjectId: string
  ): PermissionScope[]
  getSubjects(
    actorId: string
  ): Array<{ userId: string; type: RelationshipType }>
  logDelegatedAction(
    action: DelegatedAction
  ): void
}

Default Permissions by Relationship Type

Unified Citizen Data Model

The citizen data model aggregates fields from multiple departments into a single profile. Each field carries its source metadata, enabling the platform to track provenance across department boundaries.

{
  "identity": {
    "full_name":        { "value": "Margaret Chen",     "tier": "verified",  "source": "HMRC" },
    "date_of_birth":    { "value": "1958-03-14",      "tier": "verified",  "source": "HMRC" },
    "ni_number":        { "value": "QQ123456C",       "tier": "verified",  "source": "HMRC" }
  },
  "contact": {
    "address":          { "value": "12 Oak Lane, Bristol", "tier": "submitted", "source": "citizen" },
    "email":            { "value": "m.chen@email.com",  "tier": "submitted", "source": "citizen" }
  },
  "finance": {
    "annual_income":    { "value": 28400,              "tier": "verified",  "source": "HMRC" },
    "estimated_savings": { "value": "low",              "tier": "inferred",  "source": "agent" }
  }
}

The profile is organised by topic: identity, contact, finance, employment, health, transport, housing. Each topic maps to one or more source departments. When a service requests a field, the platform checks the consent model to determine whether the citizen has granted access to that topic from that source.

Cross-Department Data Flow

When a citizen consents to share data across departments, the platform mediates the exchange. The flow is always explicit: the citizen sees which fields will be shared, which department will receive them, and for what purpose.

Two strategies for connecting services to the runtime, a tool generation pipeline, and a three-tier service store with gap analysis.

Two Service Strategies

Tool Generation Pipeline

The server generates a standard set of integration points per service from its structured artefacts. This ensures a consistent interface regardless of the underlying department system.

Service Store Tiers

Services come from three sources, with descending levels of artefact completeness. The store applies precedence rules: a fully described service always overrides a graph entry, which overrides a catalogue entry.

Gap Analysis

The Legibility Studio computes per-department coverage by comparing full (Tier 1) services against the total catalogue. This surfaces exactly which services need artefact authoring and in what priority order.

Integration teams should start with high-volume, cross-departmental services: bereavement notifications, child benefit claims, driving licence renewals. These appear in multiple life events and benefit the most citizens when made fully legible to agents.

Artefact Authoring Workflow

Departments author artefacts through the Legibility Studio or by editing structured artefacts directly. The following sequence represents the recommended authoring order.

Worked Example: Manifest Structure

The capability manifest is the entry point for any service. Here is the structure for a typical renewal service.

{
  "id": "dvla-renew-driving-licence",
  "name": "Renew a driving licence",
  "department": "Driver and Vehicle Licensing Agency",
  "description": "Renew a photocard driving licence that is expiring or has expired.",
  "version": "1.0.0",
  "input_schema": {
    "required": [
      "full_name", "date_of_birth",
      "driving_licence_number", "national_insurance_number",
      "address", "photo"
    ],
    "optional": ["email", "phone"]
  },
  "output_schema": {
    "produces": ["application_reference", "expected_delivery_date"]
  },
  "estimated_duration": "10 minutes",
  "fee": {
    "amount": 14.00,
    "currency": "GBP"
  }
}

The platform handles sensitive citizen data across department boundaries. Security, data residency, and governance are architectural concerns, not afterthoughts.

Authentication and Identity

Citizen identity is established through integration with GOV.UK One Login, the cross-government identity platform. The agent does not manage credentials directly — authentication is delegated to One Login, and the platform receives a verified identity token. Session management uses standard secure token patterns with appropriate expiry and refresh mechanisms.

Data Residency

All citizen data is processed and stored within UK jurisdiction. The platform infrastructure is hosted in UK data centres. No citizen personally identifiable information (PII) leaves UK borders during processing, storage, or transit. Department data shared through the platform remains subject to each department’s existing data governance framework.

Encryption

In transit: all communications between the citizen application, the platform services, and department APIs use TLS 1.2 or higher. At rest: the evidence store, citizen data profiles, and consent records are encrypted using AES-256. Encryption keys are managed through a dedicated key management service with automatic rotation.

LLM Data Handling

Citizen PII sent to the language model is processed in-session only. The platform’s contract with LLM providers stipulates that citizen data is not used for model training, is not logged beyond the session, and is not accessible to the provider’s staff. The LLM Adapter Layer enforces this boundary — it controls exactly which citizen data fields are included in prompts, and strips sensitive fields (financial details, health records) unless explicitly required by the current service and covered by a consent grant.

Consent as a Technical Control

The Consent Manager is a hard gate, not advisory. When a service requires data that the citizen has not consented to share, the pipeline halts. The LLM cannot override consent decisions through conversational persuasion or prompt injection. Consent decisions are recorded as immutable trace events and are available for audit at any time. Consent can be withdrawn, at which point the platform ceases to share the affected data fields with the relevant service.

Audit Trail

Every significant action is captured in the evidence store as an immutable trace event. The evidence store is append-only — events cannot be modified or deleted after creation. This provides a complete, tamper-evident record of every policy evaluation, consent decision, state transition, LLM interaction, and receipt issued. The replay engine can reconstruct the exact state of any citizen interaction at any point in time.

Prompt Injection Mitigation

The architecture’s separation of deterministic and AI layers provides structural protection against prompt injection. Even if a malicious input manipulates the LLM’s response, the deterministic pipeline (steps 8–14) validates all outputs: state transitions must be legal, consent must be granted, policy rules must pass. The LLM proposes; the platform disposes.

Access Control and Delegation

The RelationshipStore enforces scoped permissions for delegated access. A power of attorney holder, parent, or carer can act on behalf of another citizen only within their declared permission scope. Every delegated action is logged separately in the evidence store, recording both the actor and the subject. Permission boundaries are enforced at the API level and cannot be circumvented through the conversational interface.