docs: organize cross-product documentation

docs/architecture/INSTITUTIONAL_DIGITAL_TWIN.md

@@ -0,0 +1,149 @@
+# 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](https://git.add-ideas.de/GovOPlaN/govoplan/issues/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.