docs: organize cross-product documentation
This commit is contained in:
@@ -0,0 +1,167 @@
|
||||
# Assisted and Non-Digital Channels
|
||||
|
||||
## Purpose
|
||||
|
||||
GovOPlaN must support people who cannot or do not use a self-service portal.
|
||||
Telephone, paper, in-person service, authorized representation, mobile staff,
|
||||
interpreters, and temporary offline work are not exceptional side systems.
|
||||
They are governed channels into the same service, case, workflow, record, and
|
||||
decision.
|
||||
|
||||
The goal is equivalent institutional treatment, not forced channel identity.
|
||||
The system preserves which channel was used and which evidence is available
|
||||
without giving digitally confident users stronger substantive rights.
|
||||
|
||||
The first end-to-end journey is tracked in
|
||||
[GovOPlaN #42](https://git.add-ideas.de/GovOPlaN/govoplan/issues/42).
|
||||
|
||||
## Actor Model
|
||||
|
||||
Every assisted interaction distinguishes:
|
||||
|
||||
- the affected person or organization;
|
||||
- the real staff member or external helper entering information;
|
||||
- the represented party and representation basis;
|
||||
- an interpreter, witness, guardian, or support person where relevant;
|
||||
- the responsible institutional function;
|
||||
- the channel and location;
|
||||
- the person who reviewed or confirmed the captured information.
|
||||
|
||||
"Entered by" is not "declared by". "Declared by" is not "verified by".
|
||||
Authentication assurance, representation authority, and evidence quality are
|
||||
separate fields.
|
||||
|
||||
## Channel-Neutral Intake Contract
|
||||
|
||||
All channels create the same versioned service/form submission contract with
|
||||
additional provenance:
|
||||
|
||||
- service, form, schema, language, and accessibility version;
|
||||
- valid and recorded time;
|
||||
- channel (`portal`, `counter`, `telephone`, `paper`, `email`, `mobile`,
|
||||
`representative`, `offline_import`, or configured extension);
|
||||
- affected and represented parties;
|
||||
- capture actor and responsible function;
|
||||
- consent, notice, purpose, legal basis, and information source;
|
||||
- field-level source and confidence where staff transcribed or inferred data;
|
||||
- attachments, scans, originals, signatures, recordings, and attestations as
|
||||
governed evidence references;
|
||||
- read-back/confirmation result and correction path;
|
||||
- receipt and chosen return channels;
|
||||
- duplicate/matching assessment and any manual resolution.
|
||||
|
||||
Forms Runtime owns the submission lifecycle. Parties owns procedural capacity
|
||||
and representation. Identity/Addresses own subject and contact references.
|
||||
Cases owns the matter. Records owns filing and retention. Audit preserves the
|
||||
action/effect evidence.
|
||||
|
||||
## Assisted Session
|
||||
|
||||
An assisted session is a resumable work item, not a privileged bypass. It:
|
||||
|
||||
1. selects service, language, channel, affected party, and represented capacity;
|
||||
2. shows the staff member only fields and evidence relevant to the service;
|
||||
3. explains why sensitive data is requested and what evidence quality is
|
||||
required;
|
||||
4. records source per value when information comes from speech, paper, an
|
||||
existing register, or staff observation;
|
||||
5. validates and previews consequences before submission;
|
||||
6. supports read-back, correction, confirmation, and a second-person check
|
||||
where policy requires it;
|
||||
7. generates an accessible receipt through the requested channel;
|
||||
8. creates follow-up tasks when original documents, signatures, translation,
|
||||
or verification remain outstanding.
|
||||
|
||||
The helper's normal account and represented function remain in the audit
|
||||
chain. Assistance never grants access to unrelated records about the person.
|
||||
|
||||
## Paper And Scanning
|
||||
|
||||
- Register receipt before scanning so custody and deadlines do not depend on
|
||||
successful OCR.
|
||||
- Store the original scan or external archive reference with digest, pages,
|
||||
capture device/provider, time, operator, and quality assessment.
|
||||
- Treat OCR and extracted fields as derived data with confidence and source
|
||||
coordinates. A person confirms consequential values.
|
||||
- Support separation, ordering, missing-page, duplicate, malware, and
|
||||
readability review.
|
||||
- File the resulting document and submission into the appropriate eAkte;
|
||||
retain or return the physical original according to policy.
|
||||
- Produce cover sheets, barcodes, and return instructions through Templates,
|
||||
not a separate print domain.
|
||||
|
||||
## Telephone And In-Person Handling
|
||||
|
||||
- Show a scripted but adaptable interview from the same Form definition.
|
||||
- Record how identity and representation were checked; do not equate caller ID
|
||||
with identity proof.
|
||||
- Require explicit confirmation of consequential declarations and capture the
|
||||
method (read-back, signed summary, one-time code, witness, later letter).
|
||||
- Record call audio only when a lawful, declared profile permits it; an
|
||||
interaction note is the default.
|
||||
- Make interrupted sessions resumable without exposing prior answers to an
|
||||
unauthorized caller or visitor.
|
||||
|
||||
## Offline And Mobile Work
|
||||
|
||||
Offline packages are encrypted, device-bound, time-limited, purpose-limited,
|
||||
and contain only the required forms/reference data. Synchronization uses
|
||||
idempotent intents and exposes conflicts rather than last-write-wins. Device
|
||||
loss, expiry, revocation, duplicate submission, clock drift, and outcome
|
||||
unknown have explicit recovery paths.
|
||||
|
||||
## Outbound Non-Digital Delivery
|
||||
|
||||
Campaign and Postbox model one delivery intent with channel choices and policy:
|
||||
|
||||
- portal/postbox delivery;
|
||||
- email;
|
||||
- print and postal fulfillment through a managed provider or local handoff;
|
||||
- in-person collection;
|
||||
- telephone notification followed by durable confirmation;
|
||||
- accessible or language-specific variants.
|
||||
|
||||
Distribution preferences are purpose- and service-specific, effective-dated,
|
||||
and may be overridden only by a documented legal or urgent-delivery rule. A
|
||||
fallback occurs only before a channel has accepted the effect unless policy
|
||||
explicitly authorizes duplicate delivery. Receipts distinguish creation,
|
||||
provider acceptance, dispatch, delivery, return, and acknowledgement.
|
||||
|
||||
## Accessibility And Equality
|
||||
|
||||
- The person can request language, easy-language, large-print, screen-reader,
|
||||
sign-language, relay, interpreter, or representative support without those
|
||||
preferences becoming a general-purpose profile visible everywhere.
|
||||
- Staff interfaces support keyboard-only capture, clear focus, error summary,
|
||||
read-back, and printable/offline alternatives.
|
||||
- Channel choice and need for assistance must not be used as an adverse risk
|
||||
signal.
|
||||
- Reports compare completion, wait, correction, abandonment, and outcome by
|
||||
channel only under a declared equality/service-quality purpose and with
|
||||
privacy thresholds.
|
||||
|
||||
## Security And Abuse Controls
|
||||
|
||||
- purpose-aware field access and session timeout;
|
||||
- current authority checks for every read and effect;
|
||||
- dual control for high-risk identity, payment, address, or representation
|
||||
changes;
|
||||
- immutable source/attestation evidence and correction history;
|
||||
- rate and anomaly controls that do not silently reject a person;
|
||||
- explicit safe handling of domestic-abuse, protected-address, witness, or
|
||||
sealed-record cases;
|
||||
- no secret answers or full documents in ordinary operational logs.
|
||||
|
||||
## First Reference Journey
|
||||
|
||||
Implement the permit-to-payment/service-to-decision journey through three
|
||||
equivalent starts:
|
||||
|
||||
1. self-service portal submission;
|
||||
2. staff-assisted counter/telephone submission;
|
||||
3. paper receipt, scan, extraction, confirmation, and filing.
|
||||
|
||||
All three must create the same Case and Workflow contract, preserve different
|
||||
provenance, support correction, produce a receipt, file an eAkte, reach the same
|
||||
decision rules, and prove accessibility, privacy, recovery, and channel
|
||||
fallback in browser and operator tests.
|
||||
@@ -0,0 +1,90 @@
|
||||
# Datasource And Definition Graph Architecture
|
||||
|
||||
## Two-Layer Data Boundary
|
||||
|
||||
GovOPlaN separates governed data identity from external acquisition:
|
||||
|
||||
| Layer | Owner | Responsibilities |
|
||||
| --- | --- | --- |
|
||||
| Datasource layer | `govoplan-datasources` | Governed data/register catalogue, tenant visibility, live/cached/static mode, source authority, staging, immutable materializations, frozen states, schema, quality/freshness policy, institutional provenance, dependencies, and bounded reads |
|
||||
| Connector layer | `govoplan-connectors` and protocol/provider modules | External protocols, endpoints, connection profiles, credentials, discovery, provider maturity/authority support, health, source-side filtering, query pushdown, and effect reconciliation |
|
||||
|
||||
Connectors publish versioned datasource origins. Datasources registers those
|
||||
origins and presents one stable capability to Dataflow, Workflow, Reporting,
|
||||
Risk Compliance, and other consumers. Consumers must not import connector
|
||||
implementations or retain credentials.
|
||||
|
||||
The initial provider path is:
|
||||
|
||||
1. Connectors imports a bounded JSON/CSV snapshot and exposes it as an origin.
|
||||
2. Datasources registers it as live or cached, or accepts a direct static upload
|
||||
through staging.
|
||||
3. Cached refreshes and static promotions append immutable materializations.
|
||||
4. Any datasource may expose a frozen state for reproducible execution evidence.
|
||||
5. Dataflow stores an opaque datasource reference, state policy, and expected
|
||||
fingerprint.
|
||||
6. A pinned Dataflow run may publish a complete bounded result as a new
|
||||
immutable materialization through an idempotent Datasources capability.
|
||||
|
||||
Database, REST/HTTP, LDAP/directory, managed file, watched-directory, feed, and
|
||||
stream providers fit behind the same origin contract. Provider-specific
|
||||
configuration remains in Connectors.
|
||||
|
||||
## Shared Definition Graph
|
||||
|
||||
Core owns domain-neutral graph primitives:
|
||||
|
||||
- nodes, typed ports, edges, and configuration field descriptors;
|
||||
- node libraries and category labels;
|
||||
- graph size, connectivity, cycle, and node-count constraints;
|
||||
- shared backend validation and frontend connection checks.
|
||||
|
||||
Domain modules own their semantics:
|
||||
|
||||
- Dataflow provides load, combine, filter, transform, and output nodes. Its
|
||||
graph is acyclic and has one output.
|
||||
- Workflow Engine provides trigger, activity, review, decision, wait,
|
||||
module-action, Dataflow, and outcome semantics. It permits governed loops and
|
||||
has exactly one trigger plus one or more outcomes. The optional Workflow
|
||||
module supplies the editor over the same native graph/BPMN language.
|
||||
|
||||
This division permits a shared editor shell without making Workflow a special
|
||||
kind of Dataflow or leaking either module into Core.
|
||||
|
||||
## Current Implementation
|
||||
|
||||
- Core graph and datasource contracts are versioned at `0.1.0`.
|
||||
- Workflow Engine owns tenant-isolated definitions, immutable revisions,
|
||||
activation pinning, module-contributed versioned baselines, runtime instances,
|
||||
governed action/effect execution, retries, waits, and reconciliation. The
|
||||
optional Workflow module exposes the reusable native BPMN graph editor.
|
||||
- Datasources exposes catalogue, origins, staging, promotion, preview,
|
||||
materialization history, refresh, freeze, retirement, and producer
|
||||
publication APIs.
|
||||
- Datasources WebUI exposes all current lifecycle views.
|
||||
- Connectors adapts existing tabular snapshots to datasource origins.
|
||||
- Dataflow consumes only Datasources catalogue/lifecycle capabilities and can
|
||||
request current, live, or latest-frozen state.
|
||||
- Dataflow exposes typed graph/IR, registry-driven validation/execution/SQL
|
||||
compilation, expressions and reusable subflows, a pinned run-lifecycle
|
||||
capability, production worker boundary, and Run/Publish surface. Runs record
|
||||
lineage and intermediate artifacts and publish only complete bounded results.
|
||||
- The focused composition check proves Connector origin -> Datasource ->
|
||||
pinned Dataflow run -> frozen published materialization, including replay.
|
||||
|
||||
## Next Slices
|
||||
|
||||
1. Add the provider declaration and source-authority binding used consistently
|
||||
by Connectors, Datasources, configuration packages, Ops, and Docs.
|
||||
2. Add typed datasource owner/steward, legal/purpose, quality/freshness,
|
||||
classification, correction, service/process, and downstream dependency
|
||||
metadata under
|
||||
[Datasources #6](https://git.add-ideas.de/GovOPlaN/govoplan-datasources/issues/6).
|
||||
3. Add SQL database and governed REST origin providers with credential-envelope
|
||||
references and bounded pushdown.
|
||||
4. Add managed-file and directory origins.
|
||||
5. Complete datasource quality rules, schema compatibility policy, retention, and
|
||||
promotion approvals.
|
||||
6. Complete scheduled/event/API/chained Dataflow trigger governance, reusable
|
||||
template inheritance, Reporting publication, human reconciliation transforms,
|
||||
and target resource/recovery evidence for large runs.
|
||||
@@ -0,0 +1,155 @@
|
||||
# Federated GovOPlaN Architecture
|
||||
|
||||
## Purpose
|
||||
|
||||
Federation lets autonomous GovOPlaN installations exchange data,
|
||||
configuration, work, messages, records, and evidence without sharing a database
|
||||
or surrendering local policy. It is institution-to-institution cooperation,
|
||||
not multi-tenancy across an untrusted network.
|
||||
|
||||
The first implementation should prove a bounded exchange between two
|
||||
installations. A new federation module is not justified until the shared
|
||||
protocol has at least two independent consumers. Core owns neutral envelopes
|
||||
and trust contracts; Connectors owns transport providers; domain modules own
|
||||
the objects and effects they exchange.
|
||||
|
||||
Implementation is tracked in
|
||||
[GovOPlaN #41](https://git.add-ideas.de/GovOPlaN/govoplan/issues/41).
|
||||
|
||||
## Invariants
|
||||
|
||||
1. Every installation remains authoritative for its tenants, identities,
|
||||
policies, keys, records, and local mappings.
|
||||
2. A remote identity or permission never becomes a local authorization claim.
|
||||
3. Every exchange declares purpose, legal/organizational basis, classification,
|
||||
minimization, retention expectation, and permitted onward use.
|
||||
4. Every object reference identifies origin instance, owner tenant, object type,
|
||||
object ID, exact revision, and source-authority mode.
|
||||
5. Payloads and receipts are signed; sensitive transports use mutually
|
||||
authenticated encrypted channels.
|
||||
6. Acceptance, rejection, outcome unknown, retry, revocation, correction, and
|
||||
reconciliation are durable states.
|
||||
7. Local policy may reject or narrow a remote request. It cannot silently claim
|
||||
to have accepted an effect that did not occur.
|
||||
8. Federation works asynchronously and can exchange signed offline bundles
|
||||
where continuous connectivity is unavailable.
|
||||
|
||||
## Trust Domains
|
||||
|
||||
An instance publishes a signed, versioned federation descriptor containing:
|
||||
|
||||
- stable instance and operator identity;
|
||||
- supported protocol and schema versions;
|
||||
- signing and transport key identifiers with rotation history;
|
||||
- accepted object and exchange profiles;
|
||||
- endpoint locations and size/rate limits;
|
||||
- support, incident, revocation, and data-protection contacts;
|
||||
- evidence and conformance references.
|
||||
|
||||
Pairing is a two-sided administrative workflow. Each side verifies the other,
|
||||
maps the remote institution to a local trusted-party record, selects permitted
|
||||
profiles and purposes, sets policy ceilings, and records approvals. Trust is
|
||||
directional and profile-specific; trusting signed Postbox delivery does not
|
||||
automatically permit case transfer or configuration import.
|
||||
|
||||
## Exchange Envelope
|
||||
|
||||
Every request, response, receipt, correction, and revocation uses one neutral
|
||||
envelope with:
|
||||
|
||||
- message ID, correlation ID, causation ID, creation and expiry;
|
||||
- origin and destination instance/institution/tenant references;
|
||||
- real actor and represented institutional capacity where disclosure is
|
||||
permitted;
|
||||
- exchange profile and semantic schema version;
|
||||
- exact domain object references and content digests;
|
||||
- purpose, legal basis, classification, data categories, retention expectation,
|
||||
onward-transfer constraint, and subject notice status;
|
||||
- requested action and idempotency key;
|
||||
- encryption recipients and signature chain;
|
||||
- attachment/object manifests rather than unbounded embedded blobs;
|
||||
- previous-envelope references for correction, replacement, or revocation.
|
||||
|
||||
The envelope is evidence, not a universal domain object. Each owner validates
|
||||
and imports or links its own payload.
|
||||
|
||||
## Exchange Profiles
|
||||
|
||||
| Profile | First owners | Behavior |
|
||||
| --- | --- | --- |
|
||||
| Postbox delivery | Postbox, Campaign, Notifications | Address or derive a remote function-bound postbox, obtain acceptance receipt, and track acknowledgement where permitted |
|
||||
| Case handoff | Cases, Parties, Services, Workflow Engine | Offer exact context and evidence; destination accepts into a new local case and returns the mapping |
|
||||
| Record transfer | Records, Files, DMS, Audit | Transfer or offer a signed record package with file-plan, metadata, content digests, holds, and disposition constraints |
|
||||
| Decision/evidence reference | Decisions, Committee, Audit | Publish a protected exact outcome or verifiable reference without transferring unrelated case content |
|
||||
| Data product publication | Datasources, Dataflow, Reporting | Publish immutable governed materializations with schema, quality, freshness, lineage, and use constraints |
|
||||
| Configuration package | Core, Policy, Views, Workflow, Forms, Templates | Exchange signed definitions; destination assesses compatibility, maps values, derives locally, and never imports secrets |
|
||||
| Search discovery | Search and domain providers | Return permission-filtered metadata or a handoff link; never expose raw remote indexes as local authority |
|
||||
|
||||
## State Machine
|
||||
|
||||
```text
|
||||
draft -> authorized -> queued -> transmitted -> received
|
||||
| |
|
||||
v v
|
||||
outcome_unknown rejected
|
||||
|
|
||||
received -> validating -> accepted -> applied -> acknowledged
|
||||
| | |
|
||||
v v v
|
||||
rejected accepted_ reconciled
|
||||
pending
|
||||
```
|
||||
|
||||
Acceptance means the destination durably owns the received intent. It does not
|
||||
mean the requested domain effect completed. Receipts distinguish transport,
|
||||
validation, acceptance, application, and human acknowledgement.
|
||||
|
||||
## Conflict And Autonomy
|
||||
|
||||
- Incoming native objects become local references, mirrors, or newly owned
|
||||
objects according to the profile. They do not overwrite local authority by
|
||||
ID coincidence.
|
||||
- Local mappings are effective-dated and auditable.
|
||||
- Corrections create a linked revision. They do not erase what the destination
|
||||
previously observed.
|
||||
- Revocation is a request and evidence event; the destination applies its own
|
||||
legal and retention rules.
|
||||
- Configuration imports use assessment and derivation. A remote package cannot
|
||||
weaken local policy or install code implicitly.
|
||||
- A disconnected partner remains a visible pending/failed state; work can be
|
||||
rerouted through an approved alternative channel.
|
||||
|
||||
## Security And Privacy
|
||||
|
||||
- Use mTLS for paired online transports and signed envelopes for end-to-end
|
||||
origin evidence.
|
||||
- Encrypt payload objects for the destination, with key rotation and outcome-
|
||||
unknown recovery; transport encryption alone is insufficient for queued
|
||||
bundles.
|
||||
- Do not put bearer credentials, local permission scopes, or reusable secrets
|
||||
in an exchange.
|
||||
- Rate-limit and size-bound discovery and transfer; quarantine unknown schemas
|
||||
and active content.
|
||||
- Evaluate current local authorization at every effect even when the envelope
|
||||
describes historical authority.
|
||||
- Log metadata separately from protected content so operators can reconcile
|
||||
without broad content access.
|
||||
- Subject access, correction, restriction, legal hold, and deletion requests
|
||||
become federated workflows with local decisions and receipts, not remote
|
||||
direct database operations.
|
||||
|
||||
## First Reference Proof
|
||||
|
||||
1. Pair two disposable installations with independent tenants, keys, and
|
||||
policies.
|
||||
2. Exchange signed descriptors and approve only the Postbox delivery profile.
|
||||
3. Deliver one Campaign message to a remote function-bound Postbox.
|
||||
4. Prove replay safety, rejection, timeout/outcome unknown, retry,
|
||||
acknowledgement, correction, key rotation, and revoked trust.
|
||||
5. Export the complete evidence bundle and restore both sides from backup.
|
||||
6. Add configuration-package exchange only after the delivery proof passes.
|
||||
|
||||
The result is a provider-neutral federation contract. A future dedicated
|
||||
module becomes appropriate only when pairing, trust administration, exchange
|
||||
queues, and evidence have a lifecycle independent of Connectors and the first
|
||||
domain owner.
|
||||
@@ -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.
|
||||
@@ -0,0 +1,616 @@
|
||||
# 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 is the canonical repository version of that
|
||||
durable architectural direction. Its implementation table records the accepted
|
||||
2026-08-01 baseline; it is not a rolling status report. Current reconciliation
|
||||
lives in [Strategy Status](../strategy/STRATEGY_STATUS.md), and Gitea issues remain the
|
||||
source of truth for delivery state.
|
||||
|
||||
Read this together with:
|
||||
|
||||
- [Connected Governance Platform Roadmap](../strategy/reference/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md)
|
||||
- [Platform Core Ideas](../strategy/PLATFORM_CORE_IDEAS.md)
|
||||
- [Strategy Status](../strategy/STRATEGY_STATUS.md)
|
||||
- [Reference Journey Program](../strategy/REFERENCE_JOURNEY_PROGRAM.md)
|
||||
- [Module Contracts and Install Boundaries](../operations/MODULE_CONTRACTS_AND_INSTALLS.md)
|
||||
- [Datasource and Definition Graph Architecture](DATASOURCE_AND_DEFINITION_GRAPH_ARCHITECTURE.md)
|
||||
- [Capability and Infrastructure Fit](../evidence/snapshots/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. A bundled local AES-256-GCM server-envelope provider now stores wrapped key material and supports Files/Postbox protection, rotation, revocation, destruction, rewrap, tamper detection, and fail-closed restore behavior. It is explicitly neither E2EE nor a certified KMS/HSM. |
|
||||
| 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.
|
||||
|
||||
## Accepted implementation baseline (2026-08-01)
|
||||
|
||||
This section is retained as the dated baseline against which the architecture
|
||||
decision was accepted. Later implementation must be reconciled in
|
||||
`STRATEGY_STATUS.md` rather than editing individual rows here into a competing
|
||||
status report.
|
||||
|
||||
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 the source manifests in the 2026-08-01 snapshot. Focused and release checks enforce `--require-architecture`; current portfolio counts belong in `STRATEGY_STATUS.md`. |
|
||||
| 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. A bundled `local_confidential` reference provider encrypts server-readable casts outside native ballot rows and exposes only receipts plus aggregate evidence to Committee. | Native recorded ballots remain reconstructable, and the reference confidential provider is neither secret nor certified: its server can decrypt casts while tallying. Secret/electronic-ballot protocol selection, custody, legal acceptance, independent review, and target evidence remain explicit product decisions. |
|
||||
| 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. Its local server-envelope provider and Files/Postbox adapters prove ciphertext persistence, integrity, rotation/rewrap and fail-closed key loss without leaking plaintext keys across the capability boundary. | Reviewed KMS/HSM/client providers, more owner adapters, target backup/restore/key-loss drills, and E2EE interoperability/certification remain required before stronger deployment claims. |
|
||||
| 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 source manifests in the accepted 2026-08-01 baseline carried validated
|
||||
evidence-based architecture metadata; current counts belong in
|
||||
`STRATEGY_STATUS.md`.
|
||||
- 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 within the accepted 2026-08-01 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.
|
||||
A bounded issuer now hashes retained reports, checks role-scoped signing
|
||||
authority and exact installed-release origin, emits sanitized signed
|
||||
receipts, verifies them immediately, and exposes admission-enforcing CLI
|
||||
gates. The real 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 in the accepted baseline of 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.
|
||||
|
||||
## Strategic extensions accepted after the baseline
|
||||
|
||||
The completed baseline does not imply that institutional product architecture
|
||||
can no longer grow. The 2026-08-05 strategic review accepted four extensions
|
||||
that consume the existing contracts without reopening the kernel or moving
|
||||
domain ownership into Core:
|
||||
|
||||
- [Product Experience and Module Boundaries](PRODUCT_EXPERIENCE_AND_MODULE_BOUNDARIES.md)
|
||||
separates technical package topology from stable task/object/product
|
||||
surfaces; implementation is tracked in Core #283.
|
||||
- [Federated GovOPlaN Architecture](FEDERATED_GOVOPLAN_ARCHITECTURE.md)
|
||||
defines governed exchange between autonomous installations; implementation
|
||||
is tracked in GovOPlaN #41.
|
||||
- [Assisted and Non-Digital Channels](ASSISTED_AND_NON_DIGITAL_CHANNELS.md)
|
||||
makes channel inclusion part of the service-to-decision journey; the first
|
||||
reference proof is tracked in GovOPlaN #42.
|
||||
- [Institutional Digital Twin](INSTITUTIONAL_DIGITAL_TWIN.md) defines a
|
||||
time-aware, policy-filtered projection over owner data; implementation is
|
||||
tracked in GovOPlaN #43.
|
||||
|
||||
The eAkte depth required by those journeys is owned by Records and specified in
|
||||
`govoplan-records/docs/EAKTE_ARCHITECTURE.md`, tracked in Records #1. These are
|
||||
new product-depth programs with bounded contracts and acceptance journeys, not
|
||||
evidence that the original institutional semantics or module architecture
|
||||
failed.
|
||||
|
||||
## 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, plus a
|
||||
bounded local server-envelope provider and Files/Postbox fixtures; external
|
||||
KMS/HSM/client-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.
|
||||
@@ -0,0 +1,483 @@
|
||||
# GovOPlaN Interface Pattern Language
|
||||
|
||||
This document is the cross-repository pattern language for GovOPlaN user
|
||||
interfaces. It turns the existing ethical doctrine, binding UI/UX decisions,
|
||||
layout rules, and module boundary into a common composition and review grammar.
|
||||
This document also owns the former standalone frontend-layout principles.
|
||||
|
||||
The dated [interface surface inventory](../evidence/snapshots/INTERFACE_SURFACE_INVENTORY.md)
|
||||
records the 2026-08-03 rollout snapshot. Current implementation state belongs
|
||||
in Gitea and generated inventory evidence, not in this durable pattern
|
||||
language.
|
||||
|
||||
## Source Of Truth And Precedence
|
||||
|
||||
Use the narrowest owning document when changing a rule:
|
||||
|
||||
1. `govoplan-core/docs/INTERFACE_ETHICS_AND_DESIGN_DOCTRINE.md` owns why a
|
||||
consequential interface must preserve context, decision, consequence,
|
||||
responsibility, contestability, and traceability.
|
||||
2. `govoplan-core/docs/UI_UX_DECISION_LEDGER.md` owns accepted product decisions
|
||||
such as progressive disclosure, adaptive forms, blocker language, guided
|
||||
operations, and the platform theme contract.
|
||||
3. `govoplan-core/docs/MODULE_ARCHITECTURE.md` owns the shell, route, navigation,
|
||||
UI-capability, and shared-component boundaries.
|
||||
4. This document owns the high-level layout choice, common pattern names,
|
||||
placement grammar, wording and state conventions, focused-view composition,
|
||||
and definition of done across those sources.
|
||||
|
||||
If two rules appear to conflict, do not create a third local convention. Record
|
||||
the conflict in the owning decision ledger, resolve it there, and update the
|
||||
affected patterns and surfaces together.
|
||||
|
||||
## Product Contract
|
||||
|
||||
GovOPlaN should feel calm because it shows what is relevant to the task, not
|
||||
because it hides authority, risk, or evidence. Every surface follows these
|
||||
rules:
|
||||
|
||||
- Start with the user's current object and task.
|
||||
- Show common actions before advanced controls.
|
||||
- Keep context, status, problems, and the next action spatially connected.
|
||||
- Make consequential effects explicit before execution and observed effects
|
||||
inspectable afterwards.
|
||||
- Treat permissions, policy, privacy, and module availability as behavior, not
|
||||
decoration.
|
||||
- Keep optional modules optional. Compose through core route and UI-capability
|
||||
contracts, never sibling-private components.
|
||||
- Use the centrally exported core components wherever a matching contract
|
||||
exists. A module-local replacement is not an implementation choice: it is a
|
||||
product exception that requires explicit product-owner authorization.
|
||||
- Preserve a stable way back to the containing object and the broader system.
|
||||
- Do not let navigation, selection, or a view switch imply consent.
|
||||
|
||||
## Surface Archetypes
|
||||
|
||||
Choose an archetype from the task, then specialize it for the domain. A route
|
||||
may contain more than one bounded archetype, but it should have one dominant
|
||||
one.
|
||||
|
||||
| Archetype | Use when | Standard anatomy | Do not use when |
|
||||
| --- | --- | --- | --- |
|
||||
| Directory or explorer | Users browse hierarchical collections such as files, mailboxes, calendars, addresses, or records. | Collection/source pane, collection actions, filter in the pane it affects, main list/content pane, optional detail pane. | The content is a set of unrelated settings or workflow stages. |
|
||||
| List-detail workspace | Users repeatedly find objects, inspect one, and act without losing list context. | Search/filter/list, persistent selected-object context, detail/actions, stable selection and URL. | A single guided operation is the primary task. |
|
||||
| Focused task view | Only a bounded composition is needed to complete one task. | Task identity and reason, selected object, necessary module regions/actions, progress or status, obvious exit to the full system. | Hiding a surface would obscure a consequence, blocker, or required evidence. |
|
||||
| Create or edit | Users change one coherent object state. | Adaptive typed form, field-level validation, advanced section, save/cancel, unsaved-change guard. | Discovery-heavy setup or a broad consequential change needs staged review. |
|
||||
| Guided setup or import | The user must discover, upload, map, test, or preflight before a safe result exists. | Named steps, current progress, preserved inputs, validation/problem list, review, resumable completion where work is durable. | An ordinary edit can be understood as one coherent form. |
|
||||
| Review or decision | A person must inspect evidence and deliberately approve, reject, send, publish, or otherwise commit. | Decision context, evidence/problems, consequence and reversibility, authority/provenance, explicit action, resulting record. | The interaction is passive inspection. |
|
||||
| Monitoring, progress, or report | Users observe asynchronous or aggregate state and intervene when needed. | Summary, filters, durable job/item state, last update, retry/reconcile/intervention, detail and evidence. | A toast is sufficient for a short, non-durable local action. |
|
||||
| Administration or configuration | Users compare and configure separate concerns. | Heading and scope, grouped subnavigation, overview/list plus selected details, adaptive editor or guided risky operation, effective policy and source. | The primary task is browsing one structured object space. |
|
||||
| Dashboard | Users need a task-oriented starting point across modules. | Prioritized actionable widgets, scoped status, clear destination per widget, explicit refresh/staleness. | It merely duplicates every module navigation item or metric. |
|
||||
| Public service or entry | An unauthenticated or external participant starts or resumes a service. | Service identity, eligibility/context, privacy and evidence expectations, accessible form/task, save/resume or handoff. | The actor is performing internal administration. |
|
||||
|
||||
## Placement Grammar
|
||||
|
||||
### Shell And Navigation
|
||||
|
||||
- The global title bar and rail belong to core. A module contributes routes,
|
||||
navigation metadata, and explicit UI capabilities; it does not reproduce the
|
||||
shell.
|
||||
- Global navigation answers "which service area?" Local subnavigation answers
|
||||
"which stable facet of this object or area?" A progress indicator answers
|
||||
"where am I in this operation?" Do not use those three controls
|
||||
interchangeably.
|
||||
- Keep the current tenant, actor, object, and selected version or scope stable
|
||||
across local navigation. Guard unsaved work before navigation.
|
||||
- Permission and capability filtering happens before view composition. A
|
||||
missing menu item is not evidence that an actor lacks backend access, and a
|
||||
visible item is never authorization by itself.
|
||||
- Route, selection, panel, and view changes must not execute consequential
|
||||
actions.
|
||||
|
||||
### Page And Workspace
|
||||
|
||||
- Structured directories use the full available content space and persistent
|
||||
panes. They do not add a decorative heading row that reduces working height.
|
||||
Give navigation and list panes bounded widths and let the main content or
|
||||
detail pane consume the remaining space.
|
||||
- In a list-detail workspace, related lists may be stacked in the left pane
|
||||
while the main pane owns view, create, and edit. Keep one create action in
|
||||
the relevant list heading instead of adding a second launcher or permanent
|
||||
creation panel.
|
||||
- Workflow, configuration, dashboard, and explanatory pages may use a heading.
|
||||
The heading names the task or scoped object and contains only route-level
|
||||
actions.
|
||||
- Put a collection-wide create action in the heading of the collection it
|
||||
affects. Use a short, specific label such as `Add` when the heading already
|
||||
names the object. Do not duplicate that action in a permanently visible side
|
||||
panel. A side panel used as the creation surface appears for creation and is
|
||||
otherwise absent or returns to its documented non-creation purpose.
|
||||
- Put filters beside the list or pane they affect. Put bulk actions immediately
|
||||
above or beside the current selection. Put object actions with the object
|
||||
detail, not in the global title bar.
|
||||
- Full-page create and edit surfaces put their persistent action cluster in the
|
||||
upper-right of the page heading. `Discard` comes before `Save …`, with the
|
||||
primary save action at the far right. Keep both controls in the same place
|
||||
across validation, loading, and saved states; guard unsaved work when the
|
||||
user discards or navigates away. Explicit Discard and dirty in-application
|
||||
navigation use the same central unsaved-changes dialog and registered
|
||||
save/discard callbacks. A browser-controlled tab/window unload warning is the
|
||||
only unavoidable different surface.
|
||||
- A page or panel has one visually primary action for its current state. Put
|
||||
secondary actions beside it. Separate destructive actions and name their real
|
||||
effect.
|
||||
- Dialog actions use a stable footer: cancel/back first, then the primary action
|
||||
at the end. Header and footer stay fixed while long bodies scroll.
|
||||
- Use cards for independent groups, summaries, and settings blocks. Do not wrap
|
||||
every region in a card or nest cards merely to create spacing.
|
||||
- When a collapsible card contains one table and no other content, the table
|
||||
uses the card's full available width and body height. The card/table region
|
||||
owns overflow; do not add an inner max-width, decorative wrapper, duplicate
|
||||
padding, or nested scroll container that reduces the working area.
|
||||
- Row actions in tables are icon-only controls in a stable rightmost action
|
||||
column. Order them by intent: inspect/open, edit, copy/duplicate,
|
||||
transfer/share/download, retry/restore, then remove/delete last. Omit actions
|
||||
only when they are structurally irrelevant to the entire table. An action
|
||||
that belongs to the table but is unavailable for one row remains in its
|
||||
normal position and is disabled; when the reason is not obvious from row
|
||||
state, provide it through the central focusable disabled-action explanation.
|
||||
It does not disappear. Every icon has a translated accessible name and matching tooltip.
|
||||
Separate destructive actions visually, and use a named confirmation/review
|
||||
surface when the consequence cannot be understood from the icon and row
|
||||
context. In an empty editable table, place Add in the same left-most action
|
||||
slot it occupies in a populated row and reserve the remaining slots so the
|
||||
column geometry does not move.
|
||||
- Transient feedback should not shift the workspace. Durable failures, partial
|
||||
results, and blockers remain attached to the affected item or operation.
|
||||
|
||||
### Detail And Explanation
|
||||
|
||||
- Keep the selected object's identity and material status visible while its
|
||||
detail changes.
|
||||
- Every non-self-explanatory field uses the central `FieldLabel`; short field
|
||||
help sits with that label. A field without `FieldLabel` is an explicit
|
||||
documented omission whose register names the field, rationale, and accessible
|
||||
label source. Users may hide inline help markers with their persisted
|
||||
interface preference; the visible/accessibility label and validation remain.
|
||||
Longer "Why?", policy source,
|
||||
diagnostics, or provenance belongs in an expandable area, detail panel, or
|
||||
review step.
|
||||
- Empty space is not an error. An empty state states what is empty, why that can
|
||||
happen, and the permitted next action. Do not show creation actions to actors
|
||||
who cannot create.
|
||||
|
||||
## Visual Grammar
|
||||
|
||||
- Core owns the appearance contract and shared CSS tokens. Modules use core
|
||||
colors, spacing, radii, shadows, focus treatment, status colors, and disabled
|
||||
treatment; module CSS may specialize layout only.
|
||||
- Establish hierarchy through spacing, typography, grouping, and placement
|
||||
before adding borders or color.
|
||||
- Color never carries status or required action alone. Pair it with text and,
|
||||
where useful, an icon.
|
||||
- Icons support recognition but do not replace accessible names. Use the core
|
||||
icon-name mapping for navigation.
|
||||
- Keep list columns, tree indentation, headers, dialog dimensions, and action
|
||||
positions stable as content changes.
|
||||
- Density is a user preference, not a license to remove labels, focus targets,
|
||||
explanations, or consequences.
|
||||
- Respect system/light/dark themes and reduced-motion preferences through the
|
||||
core contract. Do not build module-local theme systems.
|
||||
|
||||
## Wording Grammar
|
||||
|
||||
Use the same noun for the same domain object in navigation, headings, fields,
|
||||
actions, states, API-facing explanations, and documentation. Prefer the most
|
||||
specific user-facing noun: "Recipients" rather than "Data", "Delivery job"
|
||||
rather than "Process", and "Mail profile" rather than "Configuration" when
|
||||
that is what the user is acting on.
|
||||
|
||||
Actions use a verb plus the object or consequence:
|
||||
|
||||
- Prefer `Save campaign`, `Review messages`, `Queue delivery`, `Retry failed
|
||||
deliveries`, or `Delete calendar`.
|
||||
- Avoid `Submit`, `OK`, `Continue`, or `Execute` when a more precise action is
|
||||
available.
|
||||
- Use `Continue` only when it advances a reversible guided flow without
|
||||
committing the final effect.
|
||||
- Do not say `Undo` when the system can only cancel future work, create a
|
||||
correction, supersede a record, or request retraction.
|
||||
|
||||
State text describes observed state, not optimism. Use stable shared terms where
|
||||
they fit: `Draft`, `Ready for review`, `Blocked`, `Queued`, `Running`,
|
||||
`Retry scheduled`, `Partially completed`, `Completed`, `Failed`, and
|
||||
`Cancelled`. Domain-specific states may refine these terms but should not give a
|
||||
shared term a contradictory meaning.
|
||||
|
||||
Blocked and failed actions use the structured language from DUE-005:
|
||||
|
||||
- what is unavailable or failed
|
||||
- why, in plain language
|
||||
- what must happen next
|
||||
- who can do it
|
||||
- where to go
|
||||
- optional technical details behind deliberate disclosure
|
||||
|
||||
Errors should identify the affected object and whether saved state or external
|
||||
effects may already exist. Never expose raw exception text as the only user
|
||||
message.
|
||||
|
||||
Use the central dialog, confirmation, alert, and attached-error components for
|
||||
feedback. `window.alert` and the global `alert` function are prohibited. A
|
||||
genuinely unavoidable exception requires explicit product-owner authorization
|
||||
and an entry in the Core alert exception register before implementation.
|
||||
|
||||
## State Contract
|
||||
|
||||
Every surface implements the states it can reach; it does not render a blank
|
||||
region while waiting or collapse distinct outcomes into a generic error.
|
||||
|
||||
| State | Required treatment |
|
||||
| --- | --- |
|
||||
| Loading | Keep the stable shell and context visible. Name what is loading; preserve usable prior data when safe. |
|
||||
| Empty | State the scope and reason, then show only permitted next actions. |
|
||||
| Validation problem | Attach the problem to the field/item and provide a navigable summary when problems span regions or steps. |
|
||||
| Permission denied | Name the unavailable action or object, the required actor/role where safe, and a valid exit. Do not leak protected data. |
|
||||
| Capability unavailable | Distinguish not installed, disabled, not configured, unhealthy, and not permitted when the actor may know. Give the responsible actor and target. |
|
||||
| Offline or unreachable | Preserve local context and unsaved input, show last-known/stale state, and offer a safe retry. Do not present network absence as an authentication failure. |
|
||||
| Stale or conflicting | Show which data changed, preserve both values where feasible, and offer reload, merge, or explicit overwrite according to policy. |
|
||||
| Partial result | Show completed and incomplete effects separately. Never label a partial operation successful without qualification. |
|
||||
| Asynchronous work | Show durable job identity, queued/running/retry/block/final state, last update, progress if meaningful, and leave/return behavior. |
|
||||
| Success | State the resulting object/effect and provide its evidence or destination. Use a transient toast only when the result is already visible and durable elsewhere. |
|
||||
| Destructive or corrective action | Preview scope, downstream effects, reversibility limit, evidence, and required confirmation or approval. |
|
||||
|
||||
Long-running or external work must expose retry and reconciliation as observable
|
||||
states. The UI must not imply that a request and its external effect were one
|
||||
atomic success when an outbox, worker, or remote system sits between them.
|
||||
|
||||
## Consequence And Provenance
|
||||
|
||||
Before an action affects records, rights, policy, retention, communications,
|
||||
money, external systems, or workflow state, its action surface must answer the
|
||||
decision-surface questions in the interface doctrine. At minimum show:
|
||||
|
||||
- affected object and scope
|
||||
- acting identity or system actor and relevant authority
|
||||
- immediate and possible downstream effects
|
||||
- whether the operation is reversible, cancellable, corrective, or final
|
||||
- blockers and their resolution path
|
||||
- audit/evidence that will be created
|
||||
- effective policy or configuration source when it changes the decision
|
||||
|
||||
After execution, users must be able to reach the command/job, observed effects,
|
||||
policy result, failures, retries, reconciliation outcome, actor, time, and source
|
||||
data that explain the result. Provenance may be quiet by default, but it must not
|
||||
be absent.
|
||||
|
||||
Privacy follows the same rule: lists, previews, logs, notifications, and
|
||||
diagnostics show only the personal or secret data needed for the actor's task.
|
||||
Redaction must be explicit enough that users do not mistake a redacted value for
|
||||
missing source data.
|
||||
|
||||
## Focused Views
|
||||
|
||||
A focused view is a declarative UI composition for a task. It selects the
|
||||
routes, local regions, navigation entries, and actions relevant to that task
|
||||
after installed-module, capability, permission, and policy filtering. It does
|
||||
not change backend authorization or domain state.
|
||||
|
||||
A view definition must be able to explain:
|
||||
|
||||
- its stable identifier, label, and task purpose
|
||||
- the current object/scope and default destination
|
||||
- included navigation and contributed regions/actions, with deterministic order
|
||||
- the visible escape to the containing module and full system
|
||||
- why the view is active and how the user may switch when switching is allowed
|
||||
- what happens to unsaved work when entering, leaving, or switching views
|
||||
|
||||
Focused views follow these invariants:
|
||||
|
||||
- Do not hide a blocker, material consequence, provenance, or required review
|
||||
merely to make the screen quieter.
|
||||
- Preserve the global tenant/actor context and provide an obvious exit.
|
||||
- Filter unavailable contributions without leaving broken separators, empty
|
||||
groups, or dead destinations.
|
||||
- A manual or automatic switch is navigation, not consent. Guard unsaved work
|
||||
and never execute a domain action as a side effect.
|
||||
- Display why a non-manual default was selected, for example a role or task
|
||||
default, without exposing protected policy details.
|
||||
- Treat an unknown or invalid view as a recoverable fallback to the normal
|
||||
module surface.
|
||||
|
||||
When more than one source proposes a focused view, use this precedence:
|
||||
|
||||
1. a manual view pinned for the current user session
|
||||
2. a current-task suggestion, including a future workflow-step suggestion
|
||||
3. the user's saved default
|
||||
4. the role or tenant default
|
||||
5. the normal full interface
|
||||
|
||||
Show the active source and an escape to the full interface. A task or workflow
|
||||
suggestion is never an authorization change and never locks the user into the
|
||||
composition; tenant policy may constrain which views are selectable, but it
|
||||
must not hide required evidence or remove that escape. Workflow implementation
|
||||
is explicitly postponed and is not a prerequisite for defining, manually
|
||||
selecting, testing, or piloting focused views. A future workflow module may
|
||||
request a view through a core contract; it must not own the view composition
|
||||
implementation.
|
||||
|
||||
## Accessibility And Responsive Contract
|
||||
|
||||
- Every action is reachable and operable by keyboard in a logical order.
|
||||
- Use semantic headings, landmarks, labels, tables/lists, and native controls
|
||||
before adding ARIA. Icon-only controls need stable accessible names.
|
||||
- Focus is visible. Dialogs trap focus, announce their name, and return focus to
|
||||
the control that opened them. Validation moves or links focus to the first
|
||||
relevant problem without losing the problem summary.
|
||||
- Loading, saved, failed, queued, progress, and externally updated states are
|
||||
announced without repeatedly interrupting the user.
|
||||
- Disabled primary actions need a focusable explanation; a pointer-only tooltip
|
||||
is insufficient.
|
||||
- Do not rely on color, hover, drag-and-drop, pointer precision, or animation as
|
||||
the only interaction. Provide keyboard and explicit-control equivalents.
|
||||
- At narrow widths and high zoom, preserve task order and action access. Collapse
|
||||
secondary panes into an explicit drawer/step and never move a destructive
|
||||
action into the primary position.
|
||||
- Honor reduced motion. Avoid motion that implies progress when the operation is
|
||||
merely waiting.
|
||||
- Truncation has an accessible full-value path. Personal or secret values remain
|
||||
redacted according to permission and policy in that path.
|
||||
|
||||
## Component Ownership
|
||||
|
||||
Core already exports shell, navigation, access-boundary, form, dialog, loading,
|
||||
status, policy/provenance, blocker, review, table, tree, message-display, and
|
||||
unsaved-change primitives. These centrally exported components are mandatory
|
||||
across GovOPlaN wherever their contract covers the interaction. In particular,
|
||||
use the core `Card` for logical sections, `DataGrid` for tabular collections and
|
||||
row actions, and `ToggleSwitch` (the standard Toggle control) for boolean
|
||||
settings. Styling a native element or a module-local component to imitate one
|
||||
of these controls is duplication, not reuse.
|
||||
|
||||
A route or domain composition assembled from central primitives is not a custom
|
||||
control. Any new reusable UI control, presentation primitive, or module-local
|
||||
substitute is a custom component and requires explicit product-owner
|
||||
authorization before implementation. Record the authorization in the owning
|
||||
decision or issue together with:
|
||||
|
||||
- the narrowly defined purpose and consumers
|
||||
- why no central component or composition satisfies the need
|
||||
- the exact scope in which the exception may be used
|
||||
- its accessibility, state, theme, and test contract
|
||||
- whether it should remain domain-specific or later become a core component
|
||||
|
||||
An authorized custom component serves only that specific purpose. It must not
|
||||
duplicate, fork, restyle into a substitute for, or silently broaden beyond a
|
||||
central component. Code review convenience, an existing local implementation,
|
||||
or a small visual difference is not authorization. When core gains the required
|
||||
contract, migrate the exception unless the product owner explicitly retains it.
|
||||
|
||||
Do not promote a component only because two screens look similar. Promote it to
|
||||
`@govoplan/core-webui` after a second consumer or a clear platform contract has
|
||||
proved shared behavior, accessibility, state, and extension needs. Modules own
|
||||
domain composition, wording, and policy semantics; core owns generic contracts
|
||||
and appearance.
|
||||
|
||||
### Scheduling Request Composition Reference
|
||||
|
||||
The Scheduling request surface is the first explicit reference composition for
|
||||
these rules:
|
||||
|
||||
- The persistent left panel contains `My scheduling requests` and `Scheduling
|
||||
requests for me` as two stacked lists. It preserves list context like mailbox
|
||||
folders but does not invent folders.
|
||||
- The left pane's `Scheduling requests` heading owns one short `Add` action. It
|
||||
opens a new request in the right pane without an extra menu or duplicate
|
||||
launcher.
|
||||
- The right main pane is the stable view/create/edit surface. Selecting a list
|
||||
item opens its details; Add opens the same editor composition used for edit.
|
||||
- `Basic information`, `Calendar integration`, `Candidate slots`, and
|
||||
`Participants` are logical sections rendered with the central `Card`.
|
||||
- Privacy and participation behavior is a separate settings `Card`; dependent
|
||||
number/password fields are disclosed by their central `ToggleSwitch`.
|
||||
- Candidate slots and participants are row collections rendered with the
|
||||
central `DataGrid`, including its stable action column.
|
||||
- Calendar integration is a boolean choice rendered with the central
|
||||
`ToggleSwitch`; dependent calendar controls are disclosed only when enabled.
|
||||
- Each participant is one structured row containing name, email address, and
|
||||
ordered row actions. An address-parsing text area is not the ordinary editor;
|
||||
parsing pasted address lists belongs only in an explicitly designed bulk
|
||||
import flow.
|
||||
- View mode shows participation statistics and only state-valid quick actions.
|
||||
Scheduling owns those current domain actions; a future Workflow module may
|
||||
coordinate them through stable action contracts but is not a runtime
|
||||
dependency of the surface.
|
||||
|
||||
Apply the underlying placement and component rules to equivalent collection and
|
||||
create/edit surfaces throughout the system; the Scheduling domain names are an
|
||||
example, not a module-local convention.
|
||||
|
||||
## Test Expectations
|
||||
|
||||
For every changed surface, select tests from each applicable layer:
|
||||
|
||||
- route and permission tests: module enabled/disabled permutations, route guard,
|
||||
contribution filtering, fallback, and direct-link behavior
|
||||
- behavior tests: primary task, validation, unsaved-change guard, confirmation,
|
||||
retry/reconcile, partial result, and leave/return behavior
|
||||
- accessibility tests: semantic names/roles, keyboard order, focus entry/return,
|
||||
live-state announcements, and non-color status meaning
|
||||
- state tests: loading, empty, denied, capability-missing, stale/conflict,
|
||||
offline, partial, success, and destructive/corrective outcomes as applicable
|
||||
- composition tests: absent optional module, duplicate/unknown contribution,
|
||||
deterministic ordering, and focused-view fallback
|
||||
- presentation checks: supported widths/zoom, light/dark/system theme, reduced
|
||||
motion, comfortable/compact density, and long translated text
|
||||
- i18n checks: user-facing strings owned by the rendering package and structural
|
||||
audits passing
|
||||
- visual regression: useful for geometry and hierarchy after behavior and
|
||||
accessibility assertions exist; never the only evidence
|
||||
|
||||
If the current harness cannot automate a required check, record the gap and the
|
||||
manual evidence in the owning issue. "Not tested" is an inventory state, not a
|
||||
reason to infer that a pattern is satisfied.
|
||||
|
||||
## Definition Of Done For A Surface
|
||||
|
||||
- The dominant task and archetype are recorded in the inventory.
|
||||
- Placement, action hierarchy, wording, and every reachable state follow this
|
||||
pattern language or an explicit ledger exception.
|
||||
- Permission, capability, privacy, and redaction behavior are verified.
|
||||
- Consequence, reversibility, authority, evidence, and provenance are present
|
||||
where applicable.
|
||||
- Keyboard, focus, announcement, responsive, theme, density, motion, and i18n
|
||||
behavior are covered in proportion to the surface.
|
||||
- Optional modules remain optional and no sibling-private UI import was added.
|
||||
- Every matching central component is reused. Any custom-component exception
|
||||
has recorded product-owner authorization, narrow scope, rationale, and tests,
|
||||
and does not duplicate a central component.
|
||||
- Behavioral/accessibility evidence is linked from the rollout matrix and issue.
|
||||
- Configured-system help can reach the applicable pattern or reference topic
|
||||
when [Docs #15](https://git.add-ideas.de/GovOPlaN/govoplan-docs/issues/15)
|
||||
supplies that experience.
|
||||
|
||||
## First Pilot: Campaign
|
||||
|
||||
[Campaign #74](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/74)
|
||||
is the first full-domain audit and migration. It should prove patterns before
|
||||
generic extraction:
|
||||
|
||||
- [#59](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/59) and
|
||||
[#73](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/73): stable,
|
||||
accessible preview and attachment-detail overlays
|
||||
- [#63](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/63): review
|
||||
stages, outcomes, blockers, and intervention vocabulary
|
||||
- [#62](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/62): explicit
|
||||
synchronous/asynchronous send mode and durable delivery progress
|
||||
- [#65](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/65): one
|
||||
coherent report filtering and count-affordance model
|
||||
- [#35](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/35): guided
|
||||
first-campaign entry
|
||||
|
||||
These slices do not depend on the Workflow runtime. Campaign's current
|
||||
domain-owned review/send state is enough to prove layout, wording, focused-view,
|
||||
progress, intervention, and evidence patterns.
|
||||
|
||||
## Revision Procedure
|
||||
|
||||
1. Record a changed product decision in the core UI/UX decision ledger.
|
||||
2. Update the relevant pattern here without copying the full owning doctrine.
|
||||
3. Update the surface inventory and rollout owner/issues.
|
||||
4. Change shared components only where the proven contract belongs to core.
|
||||
5. Migrate and test affected module surfaces.
|
||||
6. Publish configured-system pattern/reference help through the Docs module.
|
||||
@@ -0,0 +1,201 @@
|
||||
# Platform Control Plane And Self-Description
|
||||
|
||||
## Objective
|
||||
|
||||
GovOPlaN should be able to describe its installed structure without becoming a
|
||||
self-modifying application. The platform model is a declarative control plane:
|
||||
module manifests, UI contributions, schemas, policy provenance, runtime
|
||||
capabilities, and generated source evidence describe what can be configured.
|
||||
Ordinary administrators edit validated data through those contracts; they do
|
||||
not edit Python, TypeScript, routes, or database code from the product UI.
|
||||
|
||||
This distinction provides the requested overview while preserving reviewable
|
||||
releases, module boundaries, migrations, and security controls.
|
||||
|
||||
## Canonical Sources
|
||||
|
||||
| Concern | Canonical source |
|
||||
| --- | --- |
|
||||
| Installed modules and dependency graph | Runtime `ModuleManifest` registry |
|
||||
| Backend routes | Registered FastAPI application; Python AST is build-time evidence |
|
||||
| Frontend routes and navigation | `PlatformWebModule` contributions |
|
||||
| View-filterable regions | Versioned `viewSurfaces` declarations |
|
||||
| Admin sections and module settings | `admin.sections`, including `moduleId`, `kind`, scope group, permission guards, and surface ID |
|
||||
| User settings | `settings.sections` and core settings schemas |
|
||||
| Labels and translations | Generated translation catalogs plus source usage |
|
||||
| Fields and help coverage | Shared form components plus generated TypeScript AST inventory |
|
||||
| API use by the WebUI | Typed API clients plus generated static reference inventory |
|
||||
| Stable platform interface IDs | Typed manifest/WebUI declarations plus line-independent source anchors for low-level controls |
|
||||
| Effective configuration | Owning module data plus Policy provenance |
|
||||
|
||||
Runtime introspection is authoritative for an installed system. Static source
|
||||
inventory is authoritative evidence for a checkout or release candidate. The
|
||||
two should be compared in CI and by Ops, not conflated.
|
||||
|
||||
## Generated Inventory
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
cd /mnt/DATA/git/govoplan
|
||||
./.venv/bin/python tools/inventory/platform-interface-inventory.py
|
||||
```
|
||||
|
||||
The command writes:
|
||||
|
||||
- `audit-reports/platform-inventory/platform-interface-inventory.json`
|
||||
- `audit-reports/platform-inventory/platform-interface-inventory.md`
|
||||
|
||||
Use `--strict` for the combined translation, endpoint, and declaration audit.
|
||||
Use `--strict-declarations` for duplicate/stale/undeclared interface checks
|
||||
without making existing translation coverage a release blocker. Use
|
||||
`--strict-endpoints` in the endpoint-surface CI gate so unrelated translation
|
||||
catalog work cannot disable route classification enforcement. Both strict modes
|
||||
require every backend endpoint without a statically visible WebUI path to have
|
||||
an exact entry in
|
||||
`tools/inventory/endpoint-surface-declarations.json`. The registry is keyed by
|
||||
repository, HTTP method, and canonical version-independent path. It accepts:
|
||||
|
||||
- `ui_reachable`: a mounted router, generic action, or provider path hides the
|
||||
reference from static extraction;
|
||||
- `intentionally_headless`: a capability/API is deliberately consumed without
|
||||
its own UI;
|
||||
- `public_integration`: a documented public or interoperability endpoint;
|
||||
- `worker_internal`: a worker, scheduler, reconciliation, or monitoring path;
|
||||
- `compatibility`: a retained transition endpoint with a current replacement;
|
||||
- `missing_ui`: a real UI gap, which must include a Gitea tracking issue;
|
||||
- `removable`: a reviewed dead endpoint pending removal.
|
||||
|
||||
Strict mode also rejects declarations that no longer match source. When an
|
||||
endpoint is added, changed, or removed, update its declaration in the same
|
||||
change. Do not classify an endpoint from a string mismatch alone: first check
|
||||
mounted prefixes, dynamic action paths, public clients, worker use, and
|
||||
capability consumers.
|
||||
|
||||
It combines:
|
||||
|
||||
1. loaded module manifests
|
||||
2. TypeScript AST extraction of fields, label attributes, visible text,
|
||||
translations, frontend routes, navigation, capabilities, and API references
|
||||
3. Python AST extraction of FastAPI route decorators and router prefixes
|
||||
4. normalized runtime declarations from every loaded `ModuleManifest`
|
||||
|
||||
The declaration set covers routes, navigation, View surfaces, fields, actions,
|
||||
help references, translations, admin/settings sections, widgets, search
|
||||
objects, permissions, provided interfaces, and backend capabilities. Typed
|
||||
module contributions keep their declared IDs. Shared controls may declare
|
||||
`interfaceId` and `helpTopicId`; otherwise the extractor assigns a deterministic
|
||||
source anchor based on repository, file, component context, control type, and
|
||||
semantic label rather than a line number. The JSON records which identity
|
||||
source was used.
|
||||
|
||||
The JSON includes exact repository, file, and line evidence. A missing-help
|
||||
entry is a review candidate because dynamic parent components may supply help.
|
||||
A backend route without a static frontend reference is also a review candidate:
|
||||
public APIs, workers, callbacks, health checks, connectors, and dynamic URL
|
||||
assembly are valid explanations.
|
||||
|
||||
The module matrix enforces endpoint and interface declarations with
|
||||
`--strict-endpoints --strict-declarations`.
|
||||
Combined `--strict` additionally fails when used translation keys are absent
|
||||
from generated locale catalogs. Help-text findings remain review candidates
|
||||
rather than a release gate because dynamic parent components can supply help.
|
||||
|
||||
## Runtime Comparison
|
||||
|
||||
Core exposes a sanitized read-only catalog at
|
||||
`GET /api/v1/platform/interface-catalog`. Access requires
|
||||
`admin:module:read` or `system:settings:read`. Tenant module entitlements are
|
||||
applied before serialization, so the response describes only the effective
|
||||
installed combination. It contains IDs, paths, authorization metadata,
|
||||
versions, counts, and canonical digests; it excludes factories, callbacks,
|
||||
credentials, and mutable runtime state.
|
||||
|
||||
Capture and compare a running installation:
|
||||
|
||||
```bash
|
||||
curl --fail --silent \
|
||||
-H "Authorization: Bearer $GOVOPLAN_ACCESS_TOKEN" \
|
||||
"$GOVOPLAN_URL/api/v1/platform/interface-catalog" \
|
||||
> /tmp/govoplan-runtime-interface.json
|
||||
|
||||
./.venv/bin/python tools/inventory/platform-interface-inventory.py \
|
||||
--runtime-snapshot /tmp/govoplan-runtime-interface.json \
|
||||
--strict-declarations \
|
||||
--strict-endpoints
|
||||
```
|
||||
|
||||
The comparison accepts any installed subset. Every module present in the
|
||||
runtime response must have the same contract version, module version, and
|
||||
declaration digest as the static release inventory. Unknown, duplicate, or
|
||||
mismatched runtime modules fail strict declaration mode.
|
||||
|
||||
## Admin Information Architecture
|
||||
|
||||
The Admin host uses a tree because system, tenant, group, user, and module
|
||||
settings form a hierarchy rather than one flat list. Every contributed section
|
||||
can identify:
|
||||
|
||||
- its owning `moduleId`
|
||||
- whether it is `management` or `settings`
|
||||
- its system/tenant/group/user scope group
|
||||
- an optional future `parentId`
|
||||
- permission and View visibility requirements
|
||||
|
||||
Existing panels remain their own render owners. The tree only changes discovery
|
||||
and grouping. A later embedded-settings contract may add named slots inside an
|
||||
owning page; it must not allow one module to import another module's private
|
||||
component.
|
||||
|
||||
## Navigation And Workflow
|
||||
|
||||
The intended maximum visible navigation stack is:
|
||||
|
||||
1. global shell context
|
||||
2. one task/object navigation surface
|
||||
3. one workflow stage surface when a workflow is active
|
||||
|
||||
Workflow instance pages should reuse the Campaign stage language: clear stage
|
||||
state, optional/skipped/blocked semantics, partial progress, and a stable current
|
||||
step. Workflow definition pages remain graph editors. Views may activate a
|
||||
focused workflow view that suppresses unrelated shell and module surfaces while
|
||||
retaining an explicit way out.
|
||||
|
||||
Nested module submenus should not be added merely because a data hierarchy
|
||||
exists. Prefer a tree inside configuration/directory surfaces, tabs for sibling
|
||||
views, and the workflow stage rail for ordered work.
|
||||
|
||||
## Safe Meta-Configuration
|
||||
|
||||
The platform can eventually render many configuration editors from versioned
|
||||
JSON Schema and UI Schema supplied by modules. Generated editors remain bounded
|
||||
by:
|
||||
|
||||
- explicit typed schemas and migrations
|
||||
- module-owned validation and preview
|
||||
- Policy locks and provenance
|
||||
- permission and View filtering
|
||||
- preflight, consequence, and rollback information
|
||||
- auditable apply operations
|
||||
|
||||
Custom code, new routes, arbitrary SQL, and executable workflow nodes remain
|
||||
release artifacts. Modeling them as ordinary configuration would create an
|
||||
unreviewed code-execution and migration channel.
|
||||
|
||||
## Enforced Contract
|
||||
|
||||
1. Public WebUI routes and View surfaces must reconcile with runtime manifest
|
||||
metadata; stale runtime routes and source-only public surfaces fail CI.
|
||||
2. Duplicate stable IDs fail CI. Shared controls support explicit field/action
|
||||
and help-topic identities; fallback anchors remain visible review evidence.
|
||||
3. Every statically unreferenced backend endpoint has an exact reviewed
|
||||
consumer classification, and stale classifications fail CI.
|
||||
4. Runtime module combinations can be compared exactly with static release
|
||||
evidence through versioned per-module digests.
|
||||
5. Runtime introspection is authorized, tenant-filtered, and read-only. It is
|
||||
safe for Ops/Docs projection but is not a generic configuration or code
|
||||
mutation channel.
|
||||
|
||||
Generated JSON and Markdown remain build/audit artifacts. Do not hand-edit or
|
||||
use them as a backlog; change the owning manifest, typed WebUI contribution,
|
||||
translation/help declaration, or exact endpoint classification instead.
|
||||
@@ -0,0 +1,173 @@
|
||||
# Product Experience and Module Boundaries
|
||||
|
||||
## Problem
|
||||
|
||||
GovOPlaN's runtime modularity is a strength, but the implementation structure
|
||||
is exposed too directly in the product. Ordinary users encounter module names,
|
||||
one top-level route per module, one navigation item per repository, package and
|
||||
provider identifiers, and errors framed as missing modules. This makes the
|
||||
system look like a toolbox of adjacent applications instead of one operating
|
||||
environment for institutional work.
|
||||
|
||||
The correction is not a monolithic frontend and not hidden provenance. It is a
|
||||
separate product information architecture assembled from typed module
|
||||
contributions.
|
||||
|
||||
Implementation is tracked in
|
||||
[Core #283](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/283).
|
||||
The accepted configurable product-area and task-local tool design is defined
|
||||
in [Quick Access And Product Areas](QUICK_ACCESS_AND_PRODUCT_AREAS.md).
|
||||
|
||||
## Current Exposure Inventory
|
||||
|
||||
| Surface | Direct exposure | Appropriate audience | Product-facing alternative |
|
||||
| --- | --- | --- | --- |
|
||||
| Side rail | One icon and route for many installed modules | Administrators and power users | Work areas, services, inboxes, records, communication, data and assurance |
|
||||
| Route paths | Technical owners such as `/dataflow`, `/forms`, or `/postbox` | Deep links and diagnostics | Stable product aliases and journey routes that resolve to owner surfaces |
|
||||
| Dashboard | Installed module count and module-owned widget library | Operators | Outcome, obligation, work, exception, and service widgets |
|
||||
| Administration | Package names, database state, capabilities, providers | Module and system administrators | Guided product/package configuration with technical details on demand |
|
||||
| Errors | "Module/capability not installed" | Diagnostics | Explain the unavailable outcome, responsible administrator, and enabling path |
|
||||
| Documentation | Topics grouped primarily by module | Administrators | Task, role, service, and object documentation with module provenance secondary |
|
||||
| Permissions | Module-namespaced scopes | Access administrators | Human-readable responsibility bundles; exact scopes remain inspectable |
|
||||
| Search | Provider/module as a result facet | Advanced filtering | Object type, institution, time, purpose, case/service, and source authority |
|
||||
| Workflow | Steps can expose target route/module details | Workflow designers | User-facing action and expected result; technical binding in definition details |
|
||||
| Connector state | Provider IDs and source types | Integration owners | Named source, authority, freshness, health, last effect, and recovery state |
|
||||
|
||||
## Boundary Decision
|
||||
|
||||
Three layers remain distinct:
|
||||
|
||||
1. **Technical module layer:** package ownership, dependencies, capabilities,
|
||||
permissions, migrations, routes, and provider identifiers.
|
||||
2. **Product composition layer:** work areas, object types, journeys, commands,
|
||||
inboxes, configuration packages, and role-based defaults.
|
||||
3. **Presentation projection:** active view, tenant policy, current task,
|
||||
temporal context, language, accessibility preferences, and device layout.
|
||||
|
||||
Modules own implementation and contribute typed product metadata. Core
|
||||
assembles it. Views filters it. Policy constrains it. Access authorizes the
|
||||
underlying actions. No consumer imports another optional module's UI directly.
|
||||
|
||||
## Product Surface Contract
|
||||
|
||||
Each WebUI module should be able to announce:
|
||||
|
||||
- `product_areas`: stable areas to which a route, command, widget, or object
|
||||
belongs;
|
||||
- `object_types`: user-facing nouns, icons, search context, detail route, and
|
||||
owner provenance;
|
||||
- `work_item_sources`: open work, exceptions, deadlines, and responsible
|
||||
capacity;
|
||||
- `journey_actions`: launch, resume, review, correct, decide, publish, and
|
||||
reconcile commands;
|
||||
- `workspace_surfaces`: embeddable but owner-rendered list, detail, editor, and
|
||||
status surfaces;
|
||||
- `configuration_contributions`: guided settings with consequence and
|
||||
prerequisite metadata;
|
||||
- `help_contexts`: user/admin documentation for the product identity as well as
|
||||
the technical owner;
|
||||
- `technical_provenance`: module, interface version, capability, and provider
|
||||
identifiers shown only in details and evidence.
|
||||
|
||||
The contract references surfaces. It does not permit Core or a product package
|
||||
to import their implementation.
|
||||
|
||||
## Navigation Model
|
||||
|
||||
The default shell should prioritize:
|
||||
|
||||
1. global search and create/resume commands;
|
||||
2. personal and function-bound work;
|
||||
3. configured product areas;
|
||||
4. pinned user destinations;
|
||||
5. administration and technical module inspection when authorized.
|
||||
|
||||
The baseline product areas are Work, Services and Cases, Records and
|
||||
Documents, Communication, Meetings and Decisions, Data and Assurance, and
|
||||
People and Responsibility. They are configurable system/tenant defaults and
|
||||
Views projections, not hard-coded repository groups. Empty areas disappear;
|
||||
single-destination areas may link directly; familiar tools may remain pinned.
|
||||
|
||||
The complete permission-derived module rail remains available as **All
|
||||
available tools**. Its ability to scroll is useful and is not itself the
|
||||
product defect. The defect is requiring people to infer a task or outcome from
|
||||
repository topology.
|
||||
|
||||
Task-local Work, Calendar, Messages and Files tools may be contributed to the
|
||||
optional `govoplan-quick-access` rail. Messages composes Mail, Postbox and
|
||||
future governed chat presentation without merging their channel semantics or
|
||||
state.
|
||||
|
||||
A module route remains a valid deep link. A product area may combine links and
|
||||
owner-rendered surfaces from several modules. When a required contribution is
|
||||
absent, the area explains the missing outcome rather than rendering a broken
|
||||
placeholder.
|
||||
|
||||
Views remain the projection mechanism. They may select product areas, routes,
|
||||
sections, commands, widgets, and fields. A view must not grant a permission or
|
||||
change data semantics. Policy can force, allow, or prohibit a surface at system,
|
||||
tenant, group, or user scope.
|
||||
|
||||
## Error And Provenance Language
|
||||
|
||||
Normal errors answer:
|
||||
|
||||
- what the person was trying to achieve;
|
||||
- why it is unavailable or failed;
|
||||
- whether data was saved or an external effect may have occurred;
|
||||
- who can resolve it and where;
|
||||
- the correlation/evidence reference.
|
||||
|
||||
An expandable technical section may then identify the module, capability,
|
||||
provider, request, and version. This keeps the product intelligible without
|
||||
hiding operational truth.
|
||||
|
||||
## Migration
|
||||
|
||||
Core's product-area and Quick Access contracts, the optional Quick Access
|
||||
module, the first five providers and immutable View presentation revisions are
|
||||
implemented. The migration below now concerns broader classification and
|
||||
product-language adoption; it is not a prerequisite for safely enabling the
|
||||
first rail slice.
|
||||
|
||||
### Slice 1: inventory and aliases
|
||||
|
||||
- classify every route, navigation item, widget, setting, search object, and
|
||||
help context by product area and object type;
|
||||
- add product aliases without removing existing deep links;
|
||||
- flag raw module IDs in ordinary-user labels and errors.
|
||||
|
||||
### Slice 2: work-first shell
|
||||
|
||||
- provide a generic work/exception/deadline aggregation capability;
|
||||
- make work areas and configured packages the default navigation;
|
||||
- move the complete module catalogue to administration and an optional power-
|
||||
user surface.
|
||||
- implement the configurable Quick Access rail through Core-mediated
|
||||
contributions, system/tenant/user resolution and View/Policy ceilings.
|
||||
|
||||
### Slice 3: composite journeys
|
||||
|
||||
- let product packages define journey launch/resume actions and default views;
|
||||
- let Workflow Engine activate a view and focus an owner surface without
|
||||
controlling authorization;
|
||||
- expose provider provenance and technical bindings on demand.
|
||||
|
||||
### Slice 4: enforceability
|
||||
|
||||
- make product classification mandatory for user-visible manifest surfaces;
|
||||
- reject duplicate product identities and missing owner routes in CI;
|
||||
- add browser tests proving that reference users can complete a journey without
|
||||
knowing module names.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- An ordinary user can describe every primary navigation item as work or an
|
||||
institutional object, not as a package.
|
||||
- A product package can remove irrelevant navigation while retaining deep-link
|
||||
and help integrity.
|
||||
- Missing optional modules produce an actionable product explanation.
|
||||
- Administrators can still inspect exact module, capability, provider, schema,
|
||||
and evidence provenance.
|
||||
- Module permutation tests prove that no product surface assumes an optional
|
||||
owner is installed.
|
||||
@@ -0,0 +1,193 @@
|
||||
# Quick Access And Product Areas
|
||||
|
||||
## Purpose
|
||||
|
||||
GovOPlaN presents institutional work without requiring ordinary users to
|
||||
understand the installed package graph. Two complementary projections provide
|
||||
that experience:
|
||||
|
||||
- **product areas** group destinations, objects, work and actions by the
|
||||
outcome a person recognizes;
|
||||
- **Quick Access** keeps a small set of task-local tools available without
|
||||
leaving the current page, case, record or Workflow context.
|
||||
|
||||
Technical modules remain the implementation, release and provenance boundary.
|
||||
Product areas and Quick Access are presentation contracts over those owners;
|
||||
they do not copy domain state or bypass authorization.
|
||||
|
||||
Implementation is tracked by Core #283 and #285, GovOPlaN's product-experience
|
||||
umbrella, Views, Policy and `govoplan-quick-access`.
|
||||
|
||||
The repository and product name is `govoplan-quick-access`, with module id
|
||||
`quick_access`. `govoplan-qar` was rejected because the abbreviation hides the
|
||||
purpose in package catalogues, diagnostics, permissions and operations.
|
||||
|
||||
## Implementation Status
|
||||
|
||||
The first production-shaped slice is implemented:
|
||||
|
||||
- Core validates and publishes versioned `product_areas` and
|
||||
`quick_access_tools` manifest contracts;
|
||||
- `govoplan-quick-access` derives its live catalogue from installed modules,
|
||||
persists optimistic-concurrency-protected system, tenant and user profiles,
|
||||
and resolves blocked, forced, ordered and stale preferences;
|
||||
- the shell hosts the optional right rail and one composed drawer with keyboard
|
||||
dismissal, focus return, responsive mobile behavior and full-page fallbacks;
|
||||
- Tasks, Calendar, Mail, Postbox and Files contribute the first owner-rendered
|
||||
tools; Mail and Postbox remain separate sections inside Messages;
|
||||
- immutable View revisions now carry grouped/flat navigation, product-area
|
||||
order and optional labels. Scoped Views therefore configure product
|
||||
presentation for system, tenant, group, user and Workflow contexts;
|
||||
- the expanded left rail groups classified destinations while retaining
|
||||
Dashboard and every authorized unclassified destination under More tools.
|
||||
|
||||
The remaining rollout is classification rather than a missing boundary: other
|
||||
user-facing modules must announce their product areas and future bounded tools,
|
||||
reference journeys need browser accessibility evidence, and richer active-object
|
||||
context should be added only through a separately versioned launch-context
|
||||
contract. Until classification is complete, authorized unclassified routes
|
||||
remain visible rather than disappearing.
|
||||
|
||||
## Quick Access Boundary
|
||||
|
||||
Core owns a versioned contribution contract. Feature modules may register a
|
||||
tool when they have a useful bounded surface. They do not import Quick Access.
|
||||
`govoplan-quick-access` owns configuration, effective resolution, ordering,
|
||||
the right-side rail and its drawer. Views may narrow tools for the current
|
||||
task. Policy may constrain availability and customization. Access and each
|
||||
owner's backend remain authoritative.
|
||||
|
||||
The initial categories are:
|
||||
|
||||
| Category | Typical contributions |
|
||||
| --- | --- |
|
||||
| Work | Explicit Tasks, Workflow handoffs, approvals, deadlines and exceptions |
|
||||
| Calendar | Today/upcoming agenda, event creation and scheduling launch |
|
||||
| Messages | Mail, function-bound Postbox messages and future governed chat providers |
|
||||
| Files | Contextual/recent files, attachment selection and upload |
|
||||
|
||||
Messages is one shell category but not one data model. Mail, Postbox and future
|
||||
chat providers retain their channel semantics, custody, policy, audit and
|
||||
delivery behavior. The drawer identifies the channel where that distinction
|
||||
matters.
|
||||
|
||||
## Contribution Contract
|
||||
|
||||
A Quick Access contribution declares:
|
||||
|
||||
- a stable id, category and human label;
|
||||
- icon, order and optional badge/summary provider;
|
||||
- required permissions and optional dependencies;
|
||||
- accepted context references and produced return references;
|
||||
- an owner-rendered bounded WebUI surface and full-page fallback route;
|
||||
- View surface, help context and availability explanation;
|
||||
- whether the contribution supports preview, create, select or resume.
|
||||
|
||||
The shell passes only bounded references: tenant, acting context, temporal
|
||||
read context, active task/Workflow, current institutional object, selected
|
||||
resources and a safe return location. The owner reauthorizes every read and
|
||||
effect. Credentials, protected content and permission decisions are never
|
||||
embedded in launch context.
|
||||
|
||||
## Effective Configuration
|
||||
|
||||
The effective rail is resolved from:
|
||||
|
||||
1. installed and enabled modules and their registered contributions;
|
||||
2. system availability, forced entries and ordering defaults;
|
||||
3. tenant availability, forced entries and ordering defaults;
|
||||
4. group and user View/Policy ceilings where configured;
|
||||
5. the user's enabled categories, entries and ordering;
|
||||
6. the active View and optional Workflow-step narrowing overlay;
|
||||
7. current authorization and contribution availability.
|
||||
|
||||
Lower scopes may narrow or reorder allowed entries but cannot enable a tool
|
||||
blocked above them. A forced entry cannot be removed below its source. User
|
||||
configuration stores stable contribution ids; unavailable or retired ids are
|
||||
retained as explained stale preferences without rendering broken controls.
|
||||
|
||||
Configuration screens derive their available choices from the live registry.
|
||||
Installing or enabling a contributing module adds its permitted choices;
|
||||
disabling it removes the runtime tool while preserving harmless preferences.
|
||||
If Quick Access is absent, contributors behave exactly as before.
|
||||
|
||||
## Interaction Model
|
||||
|
||||
Desktop uses a narrow right-side rail with at most four initial category
|
||||
buttons and an overflow when an administrator or user adds more categories.
|
||||
Selecting a category opens one fixed, owner-neutral drawer. Contributions are
|
||||
shown inside that drawer as tabs, sections or commands according to the
|
||||
category contract. The default drawer overlays content so DataGrid and fixed
|
||||
workspace layouts do not resize unexpectedly; a later explicit pinned mode may
|
||||
reserve layout width on sufficiently wide screens.
|
||||
|
||||
The drawer preserves host-page state, has a deterministic focus return, closes
|
||||
with Escape, supports keyboard traversal, and provides an explicit full-page
|
||||
open action. Mobile and narrow layouts use the same category/configuration
|
||||
semantics in a bottom sheet or compact menu.
|
||||
|
||||
## Product Areas
|
||||
|
||||
Product areas are stable configurable identities, not repositories. The
|
||||
recommended baseline is:
|
||||
|
||||
- Work;
|
||||
- Services and Cases;
|
||||
- Records and Documents;
|
||||
- Communication;
|
||||
- Meetings and Decisions;
|
||||
- Data and Assurance;
|
||||
- People and Responsibility.
|
||||
|
||||
Modules contribute routes, objects, actions, widgets, work sources and help to
|
||||
one or more areas. Product packages and administrators may define sensible
|
||||
system and tenant defaults. Views select, order, rename or narrow allowed
|
||||
areas, and users may personalize them within Policy ceilings. An empty area is
|
||||
omitted. An area with one destination may open it directly. A multi-destination
|
||||
area provides a useful work/recent/action surface rather than another menu.
|
||||
|
||||
Familiar product nouns such as Calendar, Mail or Files may remain directly
|
||||
pinned. The objective is not to hide every module name; it is to prevent
|
||||
repository topology from determining a person's workflow.
|
||||
|
||||
## Full Access And Provenance
|
||||
|
||||
The existing permission-derived module rail remains available as **All
|
||||
available tools** for power users and deliberate escape from a focused View.
|
||||
It contains only currently authorized destinations. Technical module,
|
||||
capability, provider and package provenance remains visible in administration,
|
||||
diagnostics, evidence and expandable details.
|
||||
|
||||
Search, deep links and help distinguish three states:
|
||||
|
||||
- available in the active View;
|
||||
- authorized but outside the active View, with a temporary escape or View
|
||||
switch;
|
||||
- unavailable because of authorization, Policy, configuration or a missing
|
||||
capability, with an actionable explanation.
|
||||
|
||||
## Delivery Order
|
||||
|
||||
1. Define Core product-area and Quick Access contracts and validation.
|
||||
2. Implement `govoplan-quick-access` configuration, effective resolution and
|
||||
shell capability.
|
||||
3. Contribute Work, Calendar, Messages and Files bounded surfaces.
|
||||
4. Add configurable product-area defaults through Views and product packages.
|
||||
5. Migrate navigation, breadcrumbs, search, errors, documentation, dashboard
|
||||
and administration toward product terminology.
|
||||
6. Prove keyboard, focus, responsive, optional-module and reference-journey
|
||||
behavior before making it the ordinary-user default.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- A user can configure allowed Quick Access categories and ordering without
|
||||
gaining authority.
|
||||
- System and tenant administrators can make entries available, forced or
|
||||
unavailable with provenance.
|
||||
- Mail, Postbox and another future channel can share Messages presentation
|
||||
while retaining independent state and channel semantics.
|
||||
- A reference journey can use a bounded tool and return without losing host
|
||||
state or Workflow context.
|
||||
- Product areas remain useful under sparse and rich permission sets and under
|
||||
optional-module permutations.
|
||||
- All available tools and technical provenance remain deliberately reachable.
|
||||
@@ -0,0 +1,153 @@
|
||||
# GovOPlaN Views Architecture
|
||||
|
||||
## Purpose
|
||||
|
||||
GovOPlaN Views are governed presentation projections for a task,
|
||||
responsibility, or workflow step. A View can reduce the visible modules,
|
||||
navigation entries, routes, page sections, and commands to the interface
|
||||
needed for the current job.
|
||||
|
||||
Views also project configurable product areas and Quick Access contributions.
|
||||
They may select, order, rename or hide permitted presentation identities but
|
||||
do not move ownership or merge Mail, Postbox, Files, Calendar, Tasks or other
|
||||
domain state.
|
||||
|
||||
Views are optional. If `govoplan-views` is not installed or enabled, the normal
|
||||
permission-derived interface remains unchanged.
|
||||
|
||||
## Security Boundary
|
||||
|
||||
A View is not an authorization mechanism.
|
||||
|
||||
- Access, tenant isolation, resource guards, and backend permission checks
|
||||
remain authoritative.
|
||||
- A View may hide an interface surface that the actor is otherwise allowed to
|
||||
use.
|
||||
- A View can never expose a route, action, tenant, or resource that normal
|
||||
authorization denies.
|
||||
- An authorized deep link outside the current View should offer an explicit
|
||||
temporary escape or View switch. It must not be presented as a permission
|
||||
denial.
|
||||
|
||||
This boundary lets Views improve focus without creating a second, weaker RBAC
|
||||
system.
|
||||
|
||||
## Ownership
|
||||
|
||||
Core owns the versioned, module-neutral surface contract and WebUI runtime
|
||||
hooks. Modules declare stable surfaces and use shared hooks to respect the
|
||||
effective projection. Modules do not import `govoplan-views`.
|
||||
|
||||
`govoplan-views` owns:
|
||||
|
||||
- draft and immutable published View revisions
|
||||
- system, tenant, group, and user assignments
|
||||
- default, mandatory, and user-selectable Views
|
||||
- active per-user View state
|
||||
- effective projection resolution and provenance
|
||||
- the View editor, preview, validation, and stale-surface diagnostics
|
||||
|
||||
Policy optionally owns inherited ceilings and explainable decisions. Workflow
|
||||
optionally references a pinned View revision for an instance or step and may
|
||||
narrow it further.
|
||||
|
||||
## Surface Contract
|
||||
|
||||
Modules announce only useful, semantic surfaces:
|
||||
|
||||
- module
|
||||
- navigation item
|
||||
- route or workspace
|
||||
- section or panel
|
||||
- command or action
|
||||
|
||||
Each descriptor has a stable namespaced id, parent id, kind, label, default
|
||||
visibility, ordering, and dependency metadata where needed. Surface ids are
|
||||
public module contracts, not CSS selectors, component paths, or arbitrary DOM
|
||||
fragments.
|
||||
|
||||
The first release supports visible or hidden. Read-only states, layout
|
||||
replacement, visual emphasis, and arbitrary styling are separate concerns and
|
||||
are deferred.
|
||||
|
||||
## Effective Resolution
|
||||
|
||||
The effective interface is the intersection of:
|
||||
|
||||
1. installed and enabled modules
|
||||
2. actor permissions and resource access
|
||||
3. administrator and Policy ceilings
|
||||
4. an assigned or user-selected View
|
||||
5. an optional workflow instance or step overlay
|
||||
|
||||
Lower scopes and workflow overlays may narrow inherited visibility but cannot
|
||||
broaden it. Every inherited, locked, hidden, unavailable, or stale choice
|
||||
should carry provenance that the editor and runtime can explain.
|
||||
|
||||
Published View revisions are immutable. Active workflow instances pin the
|
||||
revision they use. Unknown or retired surface ids produce diagnostics rather
|
||||
than breaking startup. If no valid effective View can be resolved, the system
|
||||
uses the last valid projection or the normal authorized interface and reports
|
||||
the configuration problem to administrators.
|
||||
|
||||
## Workflow Behavior
|
||||
|
||||
A workflow definition may reference a View for the whole instance or a
|
||||
particular step. Starting, resuming, or advancing the workflow activates the
|
||||
appropriate projection. Users can intentionally leave focused mode and return
|
||||
from an open-work widget or notification without losing workflow state.
|
||||
|
||||
Module handoffs carry the workflow and View context through Core contracts.
|
||||
Workflow does not import the target module or the Views implementation.
|
||||
|
||||
## Delivery Order
|
||||
|
||||
1. Define the Core surface registry and runtime hooks.
|
||||
2. Initialize `govoplan-views` and persist versioned definitions.
|
||||
3. Add assignment, selection, resolution, provenance, and the editor.
|
||||
4. Add Policy inheritance and administrator ceilings.
|
||||
5. Add Workflow instance and step activation.
|
||||
6. Adopt semantic section/action descriptors module by module.
|
||||
|
||||
## Implementation Status
|
||||
|
||||
Implemented in the initial Views slice:
|
||||
|
||||
- Core contract version `1`, stable module/navigation/route identifiers, custom
|
||||
section/action descriptors, manifest validation, and platform API metadata
|
||||
- shell navigation, route-boundary, settings, administration, dashboard-widget,
|
||||
embedded-capability, and organization-action filtering
|
||||
- `govoplan-views` definitions, immutable revisions, system/tenant/group/user
|
||||
assignments, user selection, provenance, and stale-surface recovery
|
||||
- a system and tenant administration editor with unsaved-change protection,
|
||||
publish/archive controls, assignment management, and server-enforced lockout
|
||||
prevention
|
||||
- surface declarations for every currently installed module that contributes a
|
||||
WebUI, including finer-grained shared administration and settings surfaces
|
||||
- immutable presentation settings for grouped or flat navigation, product-area
|
||||
order and product-area labels; the shell resolves these settings through the
|
||||
same system, tenant, group, user and Workflow-aware View projection
|
||||
- live product-area identities from module manifests, with authorized
|
||||
unclassified destinations retained under More tools during incremental
|
||||
adoption
|
||||
|
||||
Still intentionally separate:
|
||||
|
||||
- Policy-owned inherited ceilings and policy decision provenance
|
||||
- workflow-instance and workflow-step activation of pinned View revisions
|
||||
- read-only and layout-replacement projections beyond the version `1`
|
||||
visible/hidden contract
|
||||
|
||||
Quick Access ordering and availability remain owned by
|
||||
`govoplan-quick-access`; Views only narrow its declared surfaces for the active
|
||||
task. Neither contract permits arbitrary layout or styling. See
|
||||
`docs/architecture/QUICK_ACCESS_AND_PRODUCT_AREAS.md` in the meta repository.
|
||||
|
||||
## Gitea Work Packages
|
||||
|
||||
- `govoplan#17`: task-focused Views user story
|
||||
- `govoplan#16`: initialize and implement `govoplan-views`
|
||||
- `govoplan-core#271`: versioned surface and runtime contracts
|
||||
- `govoplan-policy#9`: inheritance, ceilings, and provenance
|
||||
- `govoplan-workflow#7`: workflow instance and step activation
|
||||
- `govoplan-workflow#3`: focused workflow mode user story
|
||||
Reference in New Issue
Block a user