govoplan/docs/architecture/INSTITUTIONAL_DIGITAL_TWIN.md

Institutional Digital Twin

Definition

The institutional digital twin is a governed, time-aware projection of how an institution is constituted and operates. It connects structure, authority, services, work, information, technology, obligations, controls, evidence, and outcomes without becoming a second source of truth.

The twin is not one editable graph database and not an employee-surveillance system. Domain modules and external systems keep ownership. The twin stores or materializes exact references, declared relationships, provenance, confidence, and projection versions. Changes flow through owner actions.

Implementation is tracked in GovOPlaN #43.

Questions It Should Answer

• Which unit and function is responsible for a service, decision, record, system, dataset, control, or risk at a given valid and recorded time?
• Which mandates and policies permit or constrain an action?
• Which processes, providers, staff capacities, data sources, and records are required to deliver a service?
• What is affected if a system, provider, organizational unit, role, package, or legal rule changes?
• Where are responsibilities missing, conflicting, expired, or concentrated?
• Which controls are evidenced, stale, failed, or dependent on an unverified assertion?
• How do actual process traces differ from defined workflows?
• Which public outcomes can be explained from protected internal evidence?

Projection Planes

Plane	Meaning
Current	Valid now, reconstructed from owner projections and current provider state
Historical	Valid at and recorded by selected instants, with present-day security enforced
Planned	Approved or proposed future structures, services, policies, projects, and package changes
Observed	Events, process traces, service measures, incidents, effects, and evidence actually recorded
Scenario	Non-authoritative simulation of a proposed change and its estimated consequences

The UI must label these planes unambiguously. Scenario output never becomes an institutional fact until an authorized owner action accepts it.

Canonical Graph

Nodes are stable institutional references, including institution, tenant, unit, function, assignment, mandate, jurisdiction, service, case, party, task, workflow, approval, decision, record, file, message, appointment, dataset, report, provider, system, control, risk, project, asset, and configuration package.

Edges have:

• owner and source authority;
• relationship type and direction;
• valid-from/valid-to and recorded/superseded times;
• exact source revision and evidence digest;
• institution/tenant boundary;
• purpose and visibility classification;
• confidence and derivation method for inferred relationships;
• correction and replacement references.

Inferred edges are never displayed as owner assertions. They remain explainable analytical products with source lineage.

Ownership And Implementation

• Core owns neutral institutional references, temporal context, provider registration, and graph projection contracts.
• Domain modules publish bounded nodes and edges through provider interfaces.
• Search indexes discoverable identities and links.
• Reporting materializes governed analytical projections.
• Dataflow computes derived relationships, quality checks, and scenarios.
• Policy evaluates visibility, purpose, retention, and allowed scenario/action transitions.
• Audit supplies observed events and evidence references.
• Projects supplies planned change and benefit relationships.
• Views renders role- and task-focused twin perspectives.
• Workflow Engine coordinates accepted changes but does not edit owner tables.

No new digital-twin module is required for the first slice. A dedicated owner is justified later if persisted scenario models, graph revisions, and cross-domain projection lifecycle become independent product objects.

Beyond The Current Platform

Continuous assurance

Controls become versioned assertions with evidence requirements, evaluation frequency, responsible function, exception workflow, and freshness. Dataflow and provider checks evaluate them continuously; Policy decides whether a stale or failed control advises, requires review, or blocks an effect.

Process mining and conformance

Governed event histories can derive actual paths, wait times, rework, and exceptions. Comparison to Workflow definitions should improve procedures, not rank individuals. Access to personal or small-cohort detail is purpose-limited and separately governed.

Change-impact simulation

A proposed organizational, provider, policy, or package change can be assessed against dependencies, mandates, open work, records, controls, capacity, and recovery plans before activation. Results identify uncertainty rather than inventing precision.

Federated institutional models

Installations can exchange signed public or partner-specific subsets of their service, mandate, provider, and evidence graph. Every side maps the references locally and retains autonomy. Federation does not create one supranational master graph.

Accountable assistance

Assistance may summarize context, identify missing evidence, draft a decision or workflow, propose mappings, and explain policy. Every output records model, inputs, constraints, uncertainty, human review, and accepted edits. Assistance does not become the acting authority.

Public evidence chains

Transparency packages can publish a minimized chain from rule and aggregate facts to decision and observed outcome, with digests proving relation to protected evidence. Public verification does not require disclosure of the underlying personal data.

Guardrails

• Do not infer competence, misconduct, intent, or personal performance from graph proximity or incomplete events.
• Do not centralize protected content merely to make graph queries easier.
• Do not use historical authorization to expose data now prohibited.
• Do not let a scenario engine write domain state directly.
• Do not hide source authority, freshness, uncertainty, or missing evidence.
• Do not retain analytical detail longer than the declared purpose requires.

Delivery Slices

1. Publish exact institutional reference/edge providers for the service-to- decision and monthly-data journeys.
2. Build a current/historical dependency explorer with source and access explanations.
3. Add planned Project/package changes and bounded impact reports.
4. Add control evidence/freshness and process conformance for one journey.
5. Prove a minimized federated projection and a public evidence package.