govoplan/docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md

# Institutional Governance Target Architecture

## Status and sources

This document is the accepted architectural reconciliation of two product
concepts prepared outside the repositories:

- `govoplan_concept_dev.md`
- `software_big_picture.md`

The source concepts describe GovOPlaN as an operational governance platform for
public institutions. This document merges that direction with the implemented
platform state as of 2026-08-01. It is the canonical repository version of the
direction. Gitea issues remain the source of truth for delivery state.

Read this together with:

- [Connected Governance Platform Roadmap](CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md)
- [Reference Journey Program](REFERENCE_JOURNEY_PROGRAM.md)
- [Module Contracts and Install Boundaries](MODULE_CONTRACTS_AND_INSTALLS.md)
- [Datasource and Definition Graph Architecture](DATASOURCE_AND_DEFINITION_GRAPH_ARCHITECTURE.md)
- [Capability and Infrastructure Fit](CAPABILITY_AND_INFRASTRUCTURE_FIT.md)
- [Core Module Architecture](../../govoplan-core/docs/MODULE_ARCHITECTURE.md)
- [Core External References and Integration Maturity](../../govoplan-core/docs/EXTERNAL_REFERENCES_AND_INTEGRATION_MATURITY.md)
- [Core Action, Effect, and Automation Layer](../../govoplan-core/docs/ACTION_EFFECT_AUTOMATION_LAYER.md)

## Decision

GovOPlaN is a configurable **institutional governance and operations layer** for
public institutions. It should model the institution, coordinate its work,
connect its specialist systems, and preserve why and under whose authority an
action occurred.

GovOPlaN is not intended to become one universal ERP, DMS, groupware suite,
workflow editor, or specialist procedure. It should own the governance concepts
that must remain understandable across those systems and support native,
external, mirrored, synchronized, overlay, and link-only operation explicitly.

This changes product emphasis, not the modular architecture:

1. The current kernel and optional-module model remains.
2. Existing domain owners keep their data and behavior.
3. Cross-module semantics become explicit, versioned contracts.
4. Successful compositions become product and sector packages, not forks or
   monolithic replacement applications.
5. Repository creation follows a proof threshold; a noun in the information
   model does not automatically require a module.

## What recent work already supersedes

The source concepts predate several implemented foundations. These items are
accepted as the current baseline and must not be reopened as greenfield work.

| Concept requirement | Reconciled current state |
| --- | --- |
| Slim kernel plus installable modules | Implemented through entry-point discovery, `ModuleManifest`, migrations, capabilities, interfaces, WebUI contributions, and permutation checks. |
| Versioned cross-module contracts | Implemented through named interface ranges, capability protocols, static workspace graph checks, activation validation, and release checks. |
| Separate headless workflow runtime and editor | Implemented as `govoplan-workflow-engine` and optional `govoplan-workflow`. Module-owned workflow baselines are versioned and reconciled without replacing local overrides. |
| Provider-neutral external references | Implemented in Core with stable external identity and cumulative integration maturity from discovery through replacement. |
| Governed asynchronous effects | Implemented foundations include the action/effect contract, transactional platform event outbox, module outboxes, idempotency, outcome-unknown states, reconciliation, and worker health. Coverage still varies by provider. |
| Acting identity, function assignment, mandate, and ownership recovery | Implemented foundations span Identity, Organizations, IDM, Access, Mandates, generic ownership transfer/recovery, and audit provenance. Effective competence now resolves through a tenant-bound Mandate capability. |
| Governed data foundations | Connectors, Datasources, Dataflow, Reporting, and Search now exist. Datasources already provides live/cached/static modes, staging, immutable materializations, and publication contracts. |
| Task-focused projections and configured documentation | Views, view-surface declarations, configurable dashboards, and manifest-driven user/admin documentation exist. Rollout and content depth remain incremental. |
| Encryption as an optional capability | Core defines provider-neutral contracts; `govoplan-identity-trust` persists public device keys, key epochs and assurance evidence; and `govoplan-encryption` persists opaque vault/key lifecycle, versioned protection envelopes, quorum recovery authorization, outcome-unknown reconciliation, and disable preflight. No concrete cipher/provider or E2EE claim is bundled. |
| Search without mandatory OpenSearch | PostgreSQL-backed, permission-aware search and module provider contracts exist; OpenSearch remains an optional adapter. |
| Scale-out and recovery architecture | Stateless API/worker, shared database/object storage, event delivery, deployment, and recovery contracts are documented and partly exercised. Production profiles and drills remain active work. |

The institutional semantics, provider declaration gate, and first product
compositions described here are now implemented. Subsequent work is
**product depth and stronger maturity evidence**, not another runtime rewrite
or an unimplemented architecture boundary.

## Implementation status (2026-08-01)

The architecture contract is implemented as a bounded, executable vertical
slice. The portfolio declarations and provider governance gates apply to the
whole workspace, while the four semantic domains whose repository thresholds
were proven now have independent persistent owners:

| Area | Implemented state | Remaining rollout |
| --- | --- | --- |
| Module portfolio metadata | Core validates versioned architecture layer/kind, maturity evidence, known limits, ownership boundaries, authority modes, reference packages, target-tested providers, and migration/upgrade/recovery/security/operations documentation. | Complete for all 62 source manifests. Focused and release checks enforce `--require-architecture`; a new module cannot enter the workspace without truthful declaration and repository-local evidence. |
| External providers | Core validates provider objects/field groups, operations, integration maturity, source authority, bounded reads, freshness/health, idempotency, conflicts, outcome-unknown handling, evidence, correction, reconciliation, outage, classification, purpose, retention, and secret handling. Addresses/CardDAV, Files remote storage, Mail SMTP/IMAP, Calendar CalDAV/ICS/Graph/EWS, and Connectors tabular/sanctions providers declare the contract and tenant-bounded secret-free runtime state. | Registry validation rejects any declared external provider without a sanitized state provider. Future adapters must cross the same gate before activation. |
| Institutional context | Core provides versioned temporal, actor/representation, institution/unit/function/task/mandate/jurisdiction/service/case/party/work-item/workflow/approval/decision/record, legal-basis, evidence, information-governance, external-source, presentation, and geographic references. Events, automation actions, audit records, and the transactional Audit outbox preserve the envelope. | Owning modules must progressively require the relevant subset for consequential operations. |
| Semantic provider contracts | Provider-neutral DTOs and protocols cover Mandate resolution, versioned Service definitions, procedure Parties/representation, and formal Decisions. `govoplan-mandates`, `govoplan-services`, `govoplan-parties`, and `govoplan-decisions` now persist immutable revisions behind those contracts with tenant isolation, bounded reads, replay safety, OCC, migrations, uninstall guards, permissions, APIs, capability documentation, and recovery documentation. | The owners are deliberately headless. Procedure-specific UI remains with consuming modules. |
| Formal-outcome proof | Committee persists bodies, meetings, agenda items, minutes, lifecycle events, and an optional protected local Decision projection. Voting separately owns immutable ballot definitions, frozen electorates, recorded casting/replacement, deterministic tally, certification, challenge, annulment, and provider-backed assurance profiles. Committee consumes `voting.ballots` and retains only deliberation linkage and verified aggregate outcome. | Native recorded ballots are reconstructable, not secret. A concrete confidential/secret/certified provider and deployment assurance still require protocol/custody/legal decisions and target evidence. |
| Service-to-case proof | Services owns the persistent exact definitions consumed by Portal discovery and Cases intake. Forms owns immutable multi-page/conditional/localized schemas, accessibility assessment and package fragments. Forms Runtime owns definition-aware drafts, validation, submission receipts, status/evidence history, and durable native Case/Workflow handoffs with intent-before-effect and outcome-unknown reconciliation. Portal delegates URL, Case, Form, or Workflow launch to an installed owner while retaining exact Service/Form provenance. | Anonymous intake and concrete attachment/signature providers remain product depth. Portal and Runtime fail closed and explain any absent launcher, target capability, or provider prerequisite. |
| Generic approvals and process execution | Approvals persists exact-subject chains, delegation, separation of duties, quorum, signatures-as-evidence, escalation, OCC, and replay-safe decisions. Campaign proves an exact-version delivery gate. Workflow Engine owns immutable definitions/instances plus API, schedule, event and parent triggers, durable timer/event waits, scale-out claims, current-authority rechecks, and idempotent starts independently of the optional editor. | Policy-authored Approval template selection, concrete signature providers, cron adapters, and broader BPMN execution profiles are product/provider depth on explicit contracts. |
| Device trust and content protection | Identity Trust separates public device keys, epochs, assurance and key-access decisions from login and Access. Encryption separates resource ownership from opaque provider key custody, versioned envelopes, migration evidence, quorum recovery authorization and uninstall proof. Files/Postbox fixtures prove the optional boundary. | Concrete reviewed KMS/HSM/client providers, feature adapters, backup/restore/key-loss drills, and E2EE interoperability/certification remain required before a deployment protection claim. |
| Procedure-party proof | Parties persists effective procedure roles, frozen contact snapshots, and representation powers. Existing powers cannot disappear or be silently rewritten; explicit OCC-guarded revocation is required. Cases resolves the provider capability and excludes expired/revoked authority from downstream delivery. | Procedure modules still decide which contextual fields and actions to present. |
| Integrated institutional journey | The executable `product.service-to-decision` fixture uses real SQL-backed Services, Cases, Parties, Mandates, Committee, and Decisions providers. It carries one exact Service version through persisted Case intake, representation and frozen delivery authority, effective Mandate resolution, a body/meeting/agendum/vote/minute sequence, a persisted formal Decision, confirmed Postbox effect, Audit/record evidence, remedy/review, and protected reconstruction. A second executable path proves Portal to exact Form revision, persisted submission, and idempotent replay. | This is architecture and composition evidence. Signed, release-bound target accessibility, privacy, security, operator, delivery-provider, and recovery-drill evidence is still required before the package may claim `reference_ready`. |
| Governed data catalogue | Datasources stores typed governance metadata, exposes bounded tenant-scoped filters and update APIs/UI, carries governance through staging, and snapshots it into immutable materializations. Reporting now persists immutable dataset, semantic-model, report, quality-plan, saved-view, and schedule revisions; executes typed semantic queries with quality gates, access checks, replay, pivoting, export/import assessment, and provenance; and exposes the governed analytical WebUI. | Rich dependency/impact traversal, additional expression functions, and policy-specific field visibility can grow on the established contracts without moving connector, transformation, or source ownership. |
| Portfolio and change governance | Projects now persists tenant-safe, immutable portfolio/project/milestone revisions with OCC, replay, lifecycle rules, restricted memberships, Search ACL indexing, outcomes, benefits, dependencies, capacity assumptions, change impact, and institutional references. Its WebUI exposes the planning catalogue and core planning fields. | Advanced planning structures already accepted by the API can receive deeper specialized editors without creating a second Policy, Reporting, Resources, or Goals owner. |
| Product/package governance | Signed configuration packages distinguish reference, product, sector, deployment, and integration classes; preserve parent/evidence provenance; prevent derived packages from loosening constraints; and preflight provider authority, maturity, exact binding, health, freshness, and recovery expectations. Executable product manifests now exist for governed communication and governed data/assurance and are checked in the module matrix. | Both artifacts deliberately remain product-class until target, accessibility, privacy, security, operations, and recovery evidence justifies reference readiness. |
| Projection and release | Platform metadata, signed module catalogs, release synthesis, Ops, and role-aware Docs retain and display architecture/provider declarations. Module-owned state providers add bounded configured/active, authority, health, freshness, conflict, recovery, and observation state; ordinary-user Docs omits binding detail. Static checks validate evidence paths, and the WebUI build verifies consuming types. | Runtime-state adoption and broader portfolio presentation follow truthful provider declaration rollout. |

The implementation deliberately keeps shared reference contracts in Core and
domain tables in their owners. It does not claim unsupported release maturity:
the four extracted owners and package remain `vertical_slice`/`product` until
target evidence supports a stronger claim. Gitea remains authoritative for
feature depth beyond this architecture contract.

## Target capability layers

The layers describe ownership and dependency direction. They are not navigation
groups and do not imply that every installation exposes every module.

| Layer | Responsibility | Current owners and declared directions |
| --- | --- | --- |
| 0. Runtime and meta | Composition, release, migrations, shared contracts, operations, deployment | Core, meta repository, Admin, Ops |
| 1. Institutional foundation | Institution, tenant, identity, organization, function, authority, access, trust | Tenancy, Identity, Organizations, IDM, Access, Identity Trust, Encryption, Mandates |
| 2. Governance and accountability | Policy, audit, risk, control, explainability, configured projection | Policy, Audit, Risk Compliance, Docs, Views, Search, Decisions |
| 3. Human work and procedure | Intake, cases, tasks, approvals, process execution and editing | Services, Forms, Forms Runtime, Cases, Parties, Tasks, Approvals, Workflow Engine, Workflow, Tickets |
| 4. Communication and participation | Delivery, participation, scheduling, channels, consultation | Portal, Postbox, Notifications, Mail, Campaign, Calendar, Scheduling, Poll, Appointments, Booking, Consultation, Committee, Addresses, Distribution Lists |
| 5. Content, records, and evidence | Managed content, templates, records, knowledge, disclosure | Files, Templates, DMS, Records, Wiki, Transparency, Certificates |
| 6. Data, reporting, and integration | Source access, staging, transformation, search, analytics, protocols | Connectors, Datasources, Dataflow, Reporting, Dashboard, REST, SOAP, XOE/V, XTA/OSCI, FIT-Connect, XRechnung, ERP adapters |
| 7. Domain capabilities | Reusable public-sector subject matter | Projects, Procurement, Contracts, Grants, Resources, Assets, Facilities, Learning, Payments, Ledger, Permits, Inspections, Evaluation, Helpdesk |
| 8. Product and sector packages | Versioned compositions, terminology, forms, processes, controls, reports, integration profiles | Signed configuration packages and reference packages; not runtime modules by default |

## Canonical institutional semantics

The connected model must keep these concepts distinct even where one UI
combines them.

| Concept | Canonical answer | Owner or direction |
| --- | --- | --- |
| Institution and tenant | In which governed installation and tenant does work occur? | Tenancy and Organizations |
| Organization and unit | Where is responsibility situated? | Organizations |
| Function | Which named organizational responsibility can an incumbent hold? | Organizations |
| Identity and account | Who is the person or machine, and through which account do they act? | Identity and Access |
| Function assignment | Who holds or represents a function, for which interval and source? | IDM |
| Role and permission | What application behavior may the acting principal perform? | Access, constrained by Policy |
| Mandate and jurisdiction | Why is an institution, unit, or function competent to act on this subject, territory, population, or interval? | Mandates |
| Service | What governed promise can an institution offer, to whom, under which prerequisites, evidence, channel, deadline, and responsibility? | Services; Portal presents it |
| Case | Which concrete administrative matter is being handled? | Cases |
| Party | In what procedural capacity does a person or organization participate, and who may represent or receive for it? | Parties; Identity/Organizations remain the subject owners |
| Work item | What must a responsible actor do next? | Tasks and domain modules |
| Workflow | How is work coordinated, including waits, human hand-offs, and governed actions? | Workflow Engine; Workflow is the optional editor |
| Approval | Has a proposed action passed a configured review or separation-of-duties gate? | Approvals |
| Decision | What formal institutional outcome was reached, by which competent authority, on which facts, rules, evidence, reasoning, and review path? | Decisions |
| Evidence and record | What proves the input, state, action, effect, correction, and retained institutional memory? | Domain owner, Files/DMS/Records, and Audit |

### Extracted semantic modules

Four horizontal concepts passed the repository proof threshold. Their Core
DTOs and provider protocols remain neutral; their persistent data, lifecycle,
security, APIs, migrations, and recovery behavior now live in independent
repositories.

#### Mandates

Mandates should own public or internal tasks, jurisdiction, responsibility,
decision/signature authority, legal or organizational basis, and effective
history. Organizations continues to own structures and functions; IDM owns
incumbency; Access owns permissions; Policy owns constraints.

`govoplan-mandates` answers: *Was this function competent to act for this case
at the relevant time, and on what basis?* Its resolver evaluates effective
time, task, authority, unit, function, jurisdiction, subject, conflicts, legal
basis, and evidence deterministically. Missing or ambiguous authority fails
closed.

#### Services

Services should own versioned service definitions: audience, prerequisites,
legal basis, evidence, fees, deadlines, channels, responsible unit/function,
jurisdiction, forms, case/workflow/result bindings, remedies, service levels,
and publication status. Portal presents and starts services but should not own
their institutional definition.

`govoplan-services` now owns those exact versioned definitions. Portal is the
first presentation consumer and Cases freezes the selected revision into its
intake context. Availability is an independent capability so publication does
not imply that all runtime prerequisites are satisfied.

#### Parties

Parties should own procedure-local roles and relationships: applicant,
respondent, beneficiary, representative, joint applicant, delivery recipient,
power or authority to represent, and permitted/preferred channels for the
matter. Identity answers who the subject is; Organizations answers which
institutional unit it is; Addresses owns contact points; Parties answers how
the subject participates here.

`govoplan-parties` owns the shared effective-dated lifecycle. Cases retains a
bounded compatibility projection only when the module is absent; that fallback
contains no representation lifecycle and cannot silently become a second
authority source.

#### Decisions

Decisions should own formal outcomes: subject, type, competent authority,
facts, evidence, applicable rule versions, reasoning, operative result,
conditions, effect, delivery/publication, remedy/review, correction, revocation,
and links to observed effects. Approvals own review gates; Poll owns response
collection; Committee owns deliberation, meetings, and votes; Workflow owns
coordination.

`govoplan-decisions` owns the persistent lifecycle and protected reconstruction
surface. Committee supplies deliberation context and records through the
provider capability. Consumers retain exact Decision references without
gaining table access.

## Source authority and integration maturity

Two independent dimensions must be recorded. They must not be collapsed into a
single `sync` flag.

### Source-authority mode

| Mode | Meaning |
| --- | --- |
| `native_authoritative` | GovOPlaN owns the authoritative object and lifecycle. |
| `external_authoritative` | The external system owns the object; GovOPlaN reads or acts through it. |
| `external_mirror` | The external system is authoritative and GovOPlaN keeps a governed local projection or immutable snapshots. |
| `governed_sync` | Both sides may change supported fields under explicit conflict and reconciliation rules. |
| `governance_overlay` | GovOPlaN owns policy, responsibility, evidence, or coordination around an externally executed object. |
| `linked_reference` | GovOPlaN keeps only a stable link and minimal display/provenance metadata. |

Authority may be declared per tenant, organization, service, object type,
object, field group, or process step. A broad default must not hide a narrower
override.

### Integration maturity

The implemented maturity ladder remains `discover`, `link`, `search`, `read`,
`publish`, `synchronize`, `migrate`, and `replace`. Maturity says what an
adapter can do. Source-authority mode says who owns truth in a particular
configuration. For example, a connector may support `synchronize`, while a
tenant deliberately configures it as `external_mirror`.

### Provider declaration

Every provider that reads or causes external effects must declare:

- owned object and field groups;
- supported source-authority modes and integration maturity;
- read, write, delete, search, preview, and dry-run operations;
- revision/concurrency tokens, freshness, health, and bounded-read limits;
- idempotency, retry, timeout, conflict, and outcome-unknown behavior;
- evidence, audit, correction, rollback/compensation, and reconciliation paths;
- degraded and outage behavior;
- classification, purpose, retention, and secret-handling requirements.

The common provider declaration composes the external-reference, action/effect,
connector-lifecycle, capability, operational-check, and documentation
contracts. Core, release tooling, Ops, Docs, and configuration-package
preflight validate it; Registry refuses to activate a declared external
provider without bounded, sanitized runtime state.

## Cross-cutting contracts

The following contracts are mandatory for consequential domain objects. They
should be shared reference DTOs and provider protocols, not shared domain
tables in Core.

1. **Time and history:** valid-from/to, recorded-at, superseded-at, revision,
   change reason, and stable identity.
2. **Actor and representation:** real account/identity, system or service
   account, represented account/function/party, delegation or power, and
   mandate reference.
3. **Institutional context:** tenant, institution, organization unit, function,
   task/mandate, jurisdiction, service, case, and decision references.
4. **Legal and policy basis:** typed, versioned references to rules,
   obligations, policies, exceptions, and the effective decision source.
5. **Requested and observed effect:** intent, approval, dispatch, possible
   execution, confirmation, reconciliation, correction, and terminal evidence.
6. **Evidence and provenance:** source, version, checksum, derivation,
   responsible actor, timestamps, and inspection links.
7. **Information governance:** classification, purpose, legal basis, retention,
   hold, minimization, and disclosure state.
8. **External source:** system/profile/object identity, authority mode,
   maturity, version, freshness, health, and conflict state.
9. **Presentation:** language, accessibility, channel, explanation, and
   configured availability.

Existing contracts already cover substantial parts of items 1, 2, 5, 6, 8,
and 9. New work should extend those contracts instead of creating parallel DTO
families.

## Existing module direction changes

### Datasources becomes the governed data and register catalogue

The implemented live/cached/static, staging, immutable materialization, and
publication model includes typed governance metadata for owner/steward,
authoritative source and authority mode, legal basis and purpose, semantic
definition, quality and freshness policy, classification, transfer agreement,
correction process, affected services/processes, and dependent flows,
reports, controls, and decisions. Connector credentials and protocol behavior
remain outside Datasources.

### Projects grows into portfolio and change governance

The Projects boundary already includes portfolios and goals. Extend it through
versioned objectives/outcomes, dependencies, capacity, benefits, change impact,
and links to mandates, services, risks, contracts, resources, and indicators.
Do not create a separate Goals module before more than one domain proves an
independent goal lifecycle.

### Reporting becomes evidence-backed institutional measurement

Every report, measure, and indicator should explain the institutional question
or obligation it serves, owner, source/materialization and flow revision,
freshness/quality, calculation version, visibility/purpose limits, publication,
and decisions or actions that consumed it. Reporting owns presentation and
execution; source and transformation owners retain their domains.

### Risk Compliance becomes the horizontal assurance model

Sanctions screening remains a complete vertical slice. The broader reusable
model is:

```text
Obligation -> governed object -> risk -> control -> evidence -> finding -> measure -> effectiveness review
```

Risk Compliance now persists that effective-dated, immutable-revision assurance
graph, exposes bounded tenant-safe traversal/search/editing, and projects each
completed sanctions run into it idempotently. Policy
owns enforceable rules and decisions; Audit owns immutable event evidence;
domain modules own the governed objects and corrective actions.

### Connectors exposes authority and effect behavior

Connector direction (`consume`, `publish`, `bidirectional`) remains useful but
is not enough. Profiles and bindings need the source-authority mode and
provider declaration above. ERP remains an integration family: finance,
workforce, procurement, asset, or other domain modules own semantics while
connectors own transport and source interaction.

### Geography starts as a reference contract

Before adding a `govoplan-geo` module, define a common reference shape for
coordinates, geometry, administrative area, address/location, CRS, source,
accuracy, validity, and external GIS identity. Create a repository only when
GovOPlaN must own spatial datasets, topology, or independent geospatial
lifecycles rather than link to an external GIS.

## Product and sector packages

A module says what capability can exist. A product package says how capabilities
work together for a bounded outcome. A sector package specializes vocabulary,
forms, rules, process baselines, controls, reports, and integration profiles
without forking the platform.

The signed configuration-package mechanism distinguishes:

- **reference package:** tested composition proving a journey and its recovery
  behavior;
- **product package:** reusable operating capability such as governed
  communication, service-to-decision, procurement/contracts, or governed BI;
- **sector package:** institutional specialization such as municipality,
  university/research, ministry/program, regulator, grants authority, or
  committee/council;
- **deployment profile:** supported infrastructure and operational topology;
- **integration profile:** supported set of external systems, authority modes,
  bindings, and health expectations.

Packages may require modules and capabilities, but package definitions remain
configuration and evidence. They do not gain access to module-owned tables.

## Module portfolio metadata

Repository category is not capability maturity. The runtime manifest, release
catalog, Docs projection, and meta repository inventory use one
machine-readable declaration with at least:

- architecture layer and module kind;
- lifecycle/maturity claim: `concept`, `scaffold`, `vertical_slice`,
  `reference_ready`, `supported`, or `lts`;
- evidence supporting the claim and known limits;
- supported source-authority modes;
- owned and explicitly non-owned concepts;
- provided/required capabilities and interfaces;
- reference packages and target-tested providers;
- migration, upgrade, recovery, security, and operations documentation.

Maturity is a release claim and must be checked against evidence. A manifest
must not become “supported” merely because a maintainer changes one string.

Create a repository only when the capability has distinct data ownership,
independent installability, technical assets, a security/lifecycle profile, a
release reason, more than one consumer or a proven reference process, and tests
that justify the boundary. Otherwise use a shared DTO, provider capability,
submodule, configuration fragment, package, or profile.

## Implemented migration sequence

### 0. Align the portfolio and contracts - complete

- This reconciliation is canonical in the meta repository and mirrored to the
  Gitea wiki.
- All 62 source manifests carry validated evidence-based architecture metadata.
- External-reference, action/effect, operational-health, ownership, policy,
  audit, and documentation primitives compose into one enforced provider
  declaration and sanitized runtime-state contract.
- Institutional context, legal basis, evidence, presentation, external source,
  information governance, temporal revision, and geo references are shared
  Core DTOs rather than shared domain tables.

### 1. Prove responsibility and formal outcome - complete

- Mandate and Decision contracts, deterministic resolution, lifecycle
  transitions, persistence providers, APIs, permissions, migrations, recovery,
  and tests are implemented.
- Committee and the SQL-backed institutional fixture prove effective-time
  authority, persisted meeting/agendum/vote/minute context, approval context,
  reasoning, evidence, observed effect, correction/revision rules, protected
  reconstruction, and review references.
- The independent Mandates and Decisions repositories were created only after
  persistence and reuse passed the repository threshold.

### 2. Separate service and party semantics - complete

- Portal remains the presentation surface while Services owns reusable,
  versioned definitions and explainable availability.
- Parties owns procedure roles, contact snapshots, and append-only
  representation/revocation authority; Cases consumes the common resolver.
- `product.service-to-decision` proves both through a portable administrative
  service composition.
- Forms owns immutable, versioned schemas while Forms Runtime owns drafts,
  server validation, submission receipts, status/evidence history, and exact
  Service/Form provenance. Portal delegates Form launch through the runtime
  capability and fails closed when it is unavailable.

### 3. Complete governed data, portfolio, and assurance - vertical slices complete

- Datasources carries typed governance through staging and immutable
  materializations, with bounded catalogue filters and dependency references.
- Reporting owns immutable semantic definitions, safe execution, quality gates,
  provenance, schedules, saved views, pivoting, and export/import assessment
  without taking source or transformation ownership.
- Risk Compliance persists the horizontal obligation/risk/control/evidence/
  finding/measure graph and projects sanctions runs idempotently.
- Projects persists portfolio/outcome/change-governance revisions as a
  consuming domain without becoming a second policy or reporting engine.

### 4. Package repeatable public-sector outcomes - complete at product maturity

- Governed communication, governed data/assurance, and service-to-decision are
  portable product package manifests with repository-local evidence.
- Package preflight enforces module, capability, provider authority, health,
  freshness, and recovery expectations without cross-module table access.
- Sector and `reference_ready` claims remain gated on target-environment,
  recovery, accessibility, privacy, security, and operator evidence. This is a
  maturity gate, not missing architecture implementation.

## What remains after the executable architecture slice

The remaining work is not another Core or cross-module architecture rewrite.
It falls into two explicitly different categories, neither of which can be
truthfully completed by adding generic platform code:

1. **Concrete provider packages:** the Committee ballot adapter contract is
   complete, but a real secret/electronic ballot provider requires a selected
   protocol and product decisions for voter eligibility, custody, secrecy,
   recount, challenge, retention, and operational assurance. Equivalent future
   adapters must satisfy the declared provider and recovery gates.
   Provider selection and certification are tracked in
   [Committee #1](https://git.add-ideas.de/GovOPlaN/govoplan-committee/issues/1).
2. **Target-produced maturity evidence:** `reference_ready`, `supported`, and
   `lts` cannot be generated from source code. An exact release and deployment
   must produce signed, expiring accessibility, privacy, security, operator,
   provider, backup/restore, rollback, and recovery-drill evidence. The verifier
   and schemas are implemented; the actual claims require those real runs.
   The pinned-release evidence run is tracked in
   [GovOPlaN #37](https://git.add-ideas.de/GovOPlaN/govoplan/issues/37).

Forms and Forms Runtime no longer constitute an architecture gap. Conditional
multi-page/localized authoring, package-fragment import, and durable native
Case/Workflow handoffs are implemented. Remaining depth is limited to
anonymous/public identity profiles, concrete file/signature providers, and
additional handoff target adapters. Those use the implemented immutable
definition, runtime, policy, evidence, service-launch, and domain-owner
boundaries rather than requiring another split. Public/provider decisions stay
tracked in Forms Runtime
[#2](https://git.add-ideas.de/GovOPlaN/govoplan-forms-runtime/issues/2) and
[#3](https://git.add-ideas.de/GovOPlaN/govoplan-forms-runtime/issues/3).

Approvals, Voting, Workflow trigger/wait dispatch, Identity Trust, and
Encryption now likewise have repository owners, neutral Core contracts,
persistence, migrations, recovery/disable semantics, documentation and focused
tests. Their remaining tickets concern concrete providers, deeper adapters and
target evidence, not an unresolved institutional architecture boundary.

Everything else described as architecture in this document now has a
repository owner, versioned contract, bounded implementation, migration and
recovery boundary where state exists, documentation, and executable evidence.
Further work in those modules is product breadth, UX depth, provider adoption,
and evidence renewal.

## Delivery tracking

The completed cross-repository architecture epic is
[GovOPlaN #29](https://git.add-ideas.de/GovOPlaN/govoplan/issues/29).
Its implementation work packages and resulting owners are:

- [Core #279](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/279):
  validated module architecture and provider authority declarations;
- [Core #280](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/280):
  shared institutional-context and governed reference primitives;
- [GovOPlaN #30](https://git.add-ideas.de/GovOPlaN/govoplan/issues/30) and
  [govoplan-mandates](https://git.add-ideas.de/GovOPlaN/govoplan-mandates):
  Mandates semantics and persistent resolver;
- [GovOPlaN #31](https://git.add-ideas.de/GovOPlaN/govoplan/issues/31) and
  [govoplan-services](https://git.add-ideas.de/GovOPlaN/govoplan-services):
  Services semantics, catalogue, and availability;
- [GovOPlaN #32](https://git.add-ideas.de/GovOPlaN/govoplan/issues/32) and
  [govoplan-parties](https://git.add-ideas.de/GovOPlaN/govoplan-parties):
  Parties and representation semantics and resolver;
- [GovOPlaN #33](https://git.add-ideas.de/GovOPlaN/govoplan/issues/33) and
  [govoplan-decisions](https://git.add-ideas.de/GovOPlaN/govoplan-decisions):
  formal Decisions semantics and registry;
- [Datasources #6](https://git.add-ideas.de/GovOPlaN/govoplan-datasources/issues/6):
  governed data/register catalogue;
- [Risk Compliance #7](https://git.add-ideas.de/GovOPlaN/govoplan-risk-compliance/issues/7):
  horizontal assurance graph;
- [GovOPlaN #34](https://git.add-ideas.de/GovOPlaN/govoplan/issues/34):
  product and sector package classes; and
- [Docs #19](https://git.add-ideas.de/GovOPlaN/govoplan-docs/issues/19):
  configured architecture, maturity, and source-authority explanations;
- [Forms #2](https://git.add-ideas.de/GovOPlaN/govoplan-forms/issues/2):
  immutable reusable definitions and the designer surface; and
- [Forms Runtime #1](https://git.add-ideas.de/GovOPlaN/govoplan-forms-runtime/issues/1):
  definition-aware submissions and Portal service launch;
- [Forms #3](https://git.add-ideas.de/GovOPlaN/govoplan-forms/issues/3) and
  [Forms Runtime #4](https://git.add-ideas.de/GovOPlaN/govoplan-forms-runtime/issues/4):
  conditional/localized definition depth and governed native handoffs;
- [Approvals #1](https://git.add-ideas.de/GovOPlaN/govoplan-approvals/issues/1)
  and [Campaign #22](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/22):
  generic exact-subject approval chains and one consequential delivery gate;
- `govoplan-voting`: governed recorded ballots plus fail-closed provider-backed
  assurance profiles consumed by Committee; and
- Identity Trust #1 and Encryption #1-#3: public device trust, provider-neutral
  key/protection lifecycle, recovery authorization and disable proof, while
  concrete provider conformance remains separately gated.

Existing Projects #1, Reporting #4, Portal #1, Cases #1, Datasources #1,
Risk Compliance #2, GovOPlaN #14, and GovOPlaN #19 carry product-depth and
reference-readiness work instead of duplicating the completed architecture
contract.

## Completion evidence

The architecture direction is established by the following executable and
machine-enforced evidence:

- the `product.service-to-decision` composition and SQL-backed golden fixture
  retain institutional context from service entry through a persisted case,
  party, authority/work context, committee deliberation, decision, observed
  communication effect, minute/record, and review references;
- the Portal/Form journey retains the exact published Service and Form
  revisions through persisted draft state, validates on the server, and returns
  the same submission on an idempotent launch replay;
- the system can answer who acted, for whom, in which function, under which
  mandate and jurisdiction, using which rule and evidence versions;
- every implemented external binding declares authority mode, maturity,
  operations, health, freshness, conflict, and recovery behavior, and Registry
  rejects a declaration without sanitized runtime state;
- every material report or decision can be reconstructed from governed source
  and transformation versions;
- product/package manifests are portable without cross-module table access or
  code forks, while future sector packages inherit the same signed-package
  constraints; and
- documentation and Ops explain the configured composition and its limits to
  users, administrators, operators, and auditors.

These criteria complete the architecture contract at `vertical_slice` and
`product` maturity. They do not waive the separately enforced evidence needed
for a module or package to claim `reference_ready`, `supported`, or `lts`.
The capability-fit verifier now computes that cumulative readiness gate from
independently signed, expiring claims bound to the exact assessed release,
installed payload, deployment subject, controls, and artifact hashes. Actual
target runs and recovery drills remain operator-produced evidence.