GovOPlaN/govoplan
1
0
Fork 0
Code Issues 10 Pull Requests Actions 3 Packages Projects Releases Wiki Activity

docs: select connected reference journey program
Some checks failed
Dependency Audit / dependency-audit (push) Failing after 15s
Details
Security Audit / security-audit (push) Failing after 13s
Details

Browse Source
This commit is contained in:
Albrecht Degering
2026-07-21 15:41:54 +02:00
parent 99e255cf81
commit a863767233
3 changed files with 581 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
README.md
View File

@@ -149,6 +149,9 @@ Frontend layout principles for module pages are documented in
The cross-product destination, stakeholder visions, configuration archetypes,
connected outcome stories, and capability horizons are documented in
the [Connected Governance Platform Roadmap](docs/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md).
The selected Campaign-to-Postbox-to-data-to-collaboration implementation path,
including stage gates and shared documentation expectations, is in the
[Reference Journey Program](docs/REFERENCE_JOURNEY_PROGRAM.md).
The administrator journey from Core-only bootstrap through online module
installation, scale-out, and reversible environment promotion is defined in
[System Administrator Lifecycle User Story](docs/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md).

235
docs/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md
View File

@@ -16,6 +16,7 @@ cross-product vision that sequence serves.
Read it together with:
- the [selected reference-journey program](REFERENCE_JOURNEY_PROGRAM.md)
- the [current capability and infrastructure fit assessment](CAPABILITY_AND_INFRASTRUCTURE_FIT.md)
- the [interface pattern language](INTERFACE_PATTERN_LANGUAGE.md)
- the [interface surface inventory](INTERFACE_SURFACE_INVENTORY.md)
@@ -93,6 +94,7 @@ composed.
| Horizon | Product outcome |
| --- | --- |
| Current baseline | One credible Campaign-centric pilot cluster and one emerging scheduling/calendar/poll cluster on a substantial modular/governance foundation |
| Selected reference program | Campaign demonstration -> function-bound Postbox -> data-backed templates/reports -> governed BI -> collaborative documents |
| 1. Trustworthy baseline | A pinned, installable, recoverable, target-tested release with a coherent interface and explainable composition |
| 2. Human-work spine | Intake becomes owned, reviewable work with shared context, evidence, communication, and explicit external effects |
| 3. Service packages | Complete public service, internal operations, learning, meeting, and communications outcomes can be imported and adapted |
@@ -105,6 +107,14 @@ The central progression is:
safe modules -> connected work -> reusable services -> institutional assurance -> ecosystem
```
The active implementation path is the
[Reference Journey Program](REFERENCE_JOURNEY_PROGRAM.md), selected on
2026-07-21. Its five stages do not replace these product horizons: they are the
ordered demonstrations through which the shared platform contracts and horizon
gates are to be proved. Connector safety, identity/function semantics,
provenance, external-effect handling, adaptive documentation, focused UI, and
release evidence form one continuous foundation lane across all five stages.
Each horizon retains the same design promise: configuration packages describe
the procedure that exists here; focused views describe what this actor needs
now; policy constrains what may happen; evidence explains what actually
@@ -336,16 +346,21 @@ outcome.
**Composition.** Campaign, files, mail, addresses/distribution lists, policy,
access, audit, docs, notifications, and ops; calendar or scheduling is optional.
Mail owns profiles, credentials, protocol policy, and provider execution.
Campaign stores only the selected Mail profile reference plus its own delivery
intent and evidence; SMTP/IMAP material is never part of Campaign JSON.
**Configuration choices.** Local lists versus CardDAV or another directory;
local files versus managed external providers; synchronous versus queued
delivery; single author versus reviewed send; visible recipient detail versus
minimized operational views; SMTP/IMAP or another future provider.
**Roadmap role.** This is the strongest current product slice and the proving
ground for shared UI patterns, durable external effects, audit evidence, and
operator recovery. It should become the first pinned, target-tested reference
configuration rather than expanding indefinitely into a marketing suite.
**Roadmap role.** This is the strongest current product slice and Stage 1 of the
selected reference-journey program. It is the proving ground for shared UI
patterns, adaptive multi-perspective documentation, durable external effects,
module-owned profiles and data, audit evidence, and operator recovery. It should
become the first pinned, target-tested reference configuration rather than
expanding indefinitely into a marketing suite.
### 2. Scheduling, meeting, and institutional decision office
@@ -847,6 +862,64 @@ can be tested.
8. Minutes, responses, decision, publication, corrections, and records remain
connected for participants and oversight under their respective access.
### Story I: from sender to current institutional responsibility
1. A sender selects a governed delivery target: a Postbox or a function in an
organizational unit, not the name or email address of its current holder.
2. Organizations, Identity, IDM, and Access resolve the target and current
acting context through their owned contracts.
3. Postbox accepts one durable message and attachment references and returns a
delivery receipt; Campaign or another sender retains only typed references.
4. An authorized function holder or delegate discovers and handles the message.
5. Vacancy, ambiguity, expiry, or unavailable dependencies create visible safe
states rather than an implicit personal fallback.
6. Reassignment changes future access without moving or rewriting the message;
delivery, access, and correction evidence remains connected.
### Story J: from specialist-system context to reproducible document
1. An authenticated user follows an opaque, short-lived launch reference from
HIS or another source system to a GovOPlaN report/document task.
2. GovOPlaN re-authorizes the actor and resolves a curated, versioned source
context server-side; URLs contain neither credentials nor trusted raw data.
3. The user sees source, freshness, parameters, template/report version, and
blockers before generation.
4. Templates renders or Reporting executes from a validated input snapshot;
Files stores the immutable output and checksum.
5. The result is linked or returned through an explicit idempotent contract.
6. Provenance explains exactly which source, data version, transformation,
definition, actor, and policy produced the artifact.
### Story K: from operational sources to trusted institutional indicator
1. A governed catalog declares source owner, purpose, classification, schema,
extraction mode, reporting-date semantics, freshness, and credentials.
2. An ingestion run stages a snapshot or watermark and records schema drift,
validation findings, quarantine, and replay evidence.
3. Versioned transformations map official keys, organizational hierarchies,
time dimensions, and measures into a documented analytical data product.
4. Reporting serves policy-aware aggregates and permitted drill-down with the
calculation and lineage visible.
5. Scheduled outputs, APIs, templates, or open-data handoffs use the same
product version rather than reimplementing the calculation.
6. Package promotion reproduces the accepted report in development, test, and
production; corrections create new evidence rather than rewriting history.
### Story L: from generated artifact to approved collaborative record
1. An uploaded file or generated template/report becomes a DMS document with a
stable identity and first version.
2. Authorized actors receive an editing session or controlled check-out under
current permission and document policy.
3. Concurrent or stale saves cannot silently overwrite accepted work; comments,
comparison, locks, and recovery make conflicts understandable.
4. Review and approval freeze an immutable rendition with actor, version,
content checksum, and decision evidence.
5. Postbox, Campaign, Cases, or another module links the document through a
typed reference rather than copying its lifecycle.
6. Records classifies and retains the accepted rendition while Files remains
the storage owner and an external editor remains only a connector.
## Roadmap horizons
Horizons are ordered by dependency and product confidence, not calendar dates.
@@ -854,6 +927,15 @@ Work may proceed in parallel when it does not bypass a gate. A horizon is
complete when its user and operator outcome is demonstrated in a pinned
composition, not when all named repositories contain scaffolding.
Reference-program stage numbers are delivery order, not alternative maturity
horizons. Campaign primarily proves Horizon 1; function-bound Postbox and the
manual responsibility spine prove Horizon 2; templates/report launches and the
first analytical product prove Horizons 2 and 3; governed BI adds assurance and
ecosystem capabilities across Horizons 3–5; collaborative documents combine
the evidence spine, service packages, and records assurance across Horizons
2–4. The detailed mapping and gates are in the
[Reference Journey Program](REFERENCE_JOURNEY_PROGRAM.md).
### Current baseline: modular pilot foundations
The current product has credible foundations in module discovery and
@@ -886,14 +968,17 @@ Priorities:
3. Complete database, files, configuration, secrets, and audit backup/restore
drills with measured recovery objectives.
4. Prove the providers required by the selected reference configurations,
beginning with SMTP/IMAP, CalDAV, and the relevant broker/worker and file or
directory adapters, including reconciliation behavior.
beginning with Campaign's Mail-owned SMTP/IMAP profile, CalDAV, and the
relevant broker/worker and file or directory adapters, including fail-closed
destination pinning and reconciliation behavior.
5. Add external monitoring, alerting, audit export/retention, deployment
hardening, and incident/runbook evidence.
6. Apply the interface pattern language first to Campaign, scheduling, and
admin/configuration. Existing central components are mandatory; any custom
control needs prior product-owner authorization and a narrow recorded scope.
Extend central contracts only after a repeated need is demonstrated.
Extend central contracts only after a repeated need is demonstrated. Make
Campaign, Mail, and Files the first complete adaptive, multi-perspective
documentation set.
7. Align executable WebUI contributions with manifest/configured-system
metadata and make focused views manually/default selectable without waiting
for Workflow.
@@ -902,9 +987,10 @@ Priorities:
evidence.
**Gate.** A clean release candidate can be installed and restored; the
Campaign reference journey and one external calendar operation survive
provider/worker failure without duplicate or unexplained effects; the UI and
operator evidence are reproducible.
Campaign reference journey uses only Mail-owned profiles and it and one
external calendar operation survive provider/worker failure without duplicate
or unexplained effects; the UI, adaptive documentation, and operator evidence
are reproducible.
### Horizon 2: shared human-work and evidence spine
@@ -914,10 +1000,11 @@ cross-module automation is enabled.
Priorities:
1. Deliver the smallest connected path from a forms/runtime input through a
case or domain record into assigned work. Add approval, template, postbox,
notification, search, and record-reference capabilities only as the selected
journey requires them.
1. Deliver the selected function-bound Postbox path from a Campaign delivery
target through Organizations, Identity, IDM, and Access into visible,
assigned responsibility. Extend from that proven path to forms/runtime,
cases, approval, notification, search, and record references only as a
selected journey requires them.
2. Stabilize actor/function/delegation, tenant/organization, permission, policy,
privacy, and audit contracts across those modules.
3. Establish generic external-reference, action/effect, command, outbox,
@@ -935,9 +1022,11 @@ workflow-driven stories is deliberately deferred until reprioritized. This
horizon should make manual work, views, contracts, and evidence strong enough
that Workflow later coordinates stable actions rather than inventing them.
**Gate.** One incoming submission can create or link a case, appear as assigned
work, be reviewed through a focused view, produce a governed communication and
document, and remain traceable with and without optional modules installed.
**Gate.** One Campaign message can reach a function-bound Postbox and follow
current assignment/delegation without personal mailbox ownership; one incoming
submission can create or link a case, appear as assigned work, be reviewed
through a focused view, produce a governed communication and document, and
remain traceable with and without optional modules installed.
### Horizon 3: reusable end-to-end service packages
@@ -948,9 +1037,12 @@ Priorities:
- Consolidate controlled communications as the first hardened reusable
package.
- Select one next package by explicit product decision from these unordered
candidates: permit-to-payment, report-to-resolution,
training-to-certificate, or meeting-to-decision.
- Deliver data-backed template/report generation with a safe HIS-style deep
launch as the next selected package proof.
- Grow that source contract into one bounded, governed university analytical
data product before opening a general-purpose BI/dataflow program.
- Follow with the collaborative document journey once generation, storage,
provenance, and DMS lifecycle boundaries are stable.
- Add further candidates only after the selected package proves the shared
spine rather than advancing all domain repositories horizontally.
- Add Workflow transition/action execution only where a stable package proves
@@ -1021,12 +1113,16 @@ boundary, and retain operational, security, and evidence guarantees.
| --- | --- | --- | --- |
| Module/runtime composition | Implemented foundation with contract checks | Pinned release and package compatibility proof | Safe platform and ecosystem runtime |
| Tenancy, identity, access, policy, audit | Useful local foundation | Actor/function/delegation, audit retention/export and target security proof | Institutional authority and accountability plane; federation later |
| Campaign/files/mail | Strongest connected slice; target provider proof remains | Reference package, UI acceptance, real delivery/recovery drill | Governed communications capability |
| Campaign/files/mail | Strongest connected slice; Mail-profile-only boundary and target provider proof remain | Reference package, adaptive docs, UI acceptance, real delivery/recovery drill | Governed communications capability and demonstration composition |
| Calendar/scheduling/poll | Integrated domain foundations; target calendar and broader product acceptance remain | Accept implemented picker, participant privacy/policy hooks, lifecycle, response editing and CalDAV recovery; decide management ownership | Shared time, participation, and decision primitives |
| Notifications | Inbox and dispatch/recovery foundation; external Mail handoff is not integrated | Mail provider proof, unified-inbox contribution and delivery-state UX | Cross-channel attention and delivery coordination |
| Addresses and directories | Implemented adapters exist but configuration/target proof varies | Directory source, privacy, conflict and lifecycle package | Reusable people/contact source capability |
| Docs/admin/ops/dashboard | Useful cross-product surfaces with incomplete rollout | Configured-system inventory, guided config, monitoring/recovery evidence | Explainability and operation of the configured product |
| Forms/cases/tasks/approvals/postbox/search/templates | Concepts and uneven first slices | One manual end-to-end work/evidence spine | Reusable administrative coordination layer |
| Organizations/identity/IDM/access/postbox | Normalized ownership concepts and uneven runtime slices | Function-bound delivery, reassignment/delegation, vacancy and access-evidence proof | Institutional responsibility and durable communication spine |
| Forms/cases/tasks/approvals/search | Concepts and uneven first slices | Extend the proven responsibility path into one manual end-to-end work/evidence journey | Reusable administrative coordination layer |
| Templates/reporting/data sources | Boundary concepts or scaffolds | One reproducible data-backed document/report and safe HIS-style launch | Governed document production, reports, dashboards, and analytical consumption |
| Analytical data products/dataflow | Selected direction; platform contracts not yet implemented | One bounded university source-to-indicator path with staging, quality, lineage and promotion proof | Transparent institutional BI and cross-process reporting |
| DMS/collaborative editing | Boundary concept and tag-only scaffold | One Files-backed version lifecycle, then one provider-neutral editing session | Collaborative documents, review, approval and records-ready renditions |
| Workflow/automation | Concept only; no discoverable Workflow runtime; program postponed | Stable action/effect providers and an explicitly reprioritized bounded journey | Configurable governed process coordination |
| Domain modules | Mostly boundary concepts or seeds | Only the modules required by a reference package | Reusable semantics above the shared spine |
| Connectors and protocols | Catalogue/strategy plus several module-specific adapters | Profile/runtime, source-of-truth, health and one real landscape | Coexistence with institutional IT |
@@ -1102,39 +1198,41 @@ provides all applicable evidence below.
## Near-term portfolio order
This order keeps the larger destination in view while honoring the deliberate
pause on workflow-driven user-story implementation.
This order is now selected. Detailed slices and gates are in the
[Reference Journey Program](REFERENCE_JOURNEY_PROGRAM.md). Workflow-driven
user-story implementation remains paused.
1. **Release and recovery baseline.** Turn the recently harmonized repositories
into a clean pinned candidate; close backup/restore, target-provider,
monitoring, security, and capability-assessment evidence gaps.
2. **Campaign reference acceptance.** Complete the campaign UI/state/audit
program as the reference for central components, consequence language,
durable delivery, report filtering, and operator intervention.
3. **Calendar/scheduling/poll acceptance.** Run product and target-provider
acceptance over the implemented calendar selection, durable CalDAV effects,
participant privacy, response editing, transition/audit semantics, and
shared scheduling UI. Decide and then prove the organizer/admin management
policy; organizer-only management with an administrator override is not yet
the implemented mutation model.
4. **Focused experience and configured-system metadata.** Align routes and
manifests; implement manual/user/role/task-suggested views, active-source
explanation, and the full-system escape independently of Workflow.
5. **Connector and infrastructure profile.** Select one real identity/groupware/
file landscape, implement profile/source-of-truth/health contracts, and
exercise degraded and recovery behavior.
6. **Manual human-work spine.** Build the smallest forms-runtime, case, task/
inbox, approval, template, postbox/notification, search, and evidence path
without requiring workflow automation.
7. **First service configuration package.** Package one bounded journey with
role defaults, focused views, connectors, policies, configured docs,
preflight, acceptance tests, and upgrade/recovery evidence.
8. **Resume Workflow only by explicit priority decision.** When resumed, start
with the already stable actions and one package; do not turn it into a
0. **Continuous safe foundation.** Keep the composition green and version
aligned; close connector destination pinning, response limits, throttling,
profile/secret ownership and audited deletion, release/recovery, central UI,
focused-view, provenance, and configured-documentation gaps only as far as
the active reference stage requires.
1. **Campaign demonstration composition.** Enforce Mail-profile-only transport,
finish Campaign/UI/state/audit and target delivery/recovery acceptance,
complete adaptive Campaign/Mail/Files documentation, and package runnable
examples as the first pinned reference product.
2. **Function-bound Postbox.** Implement Postbox and the
Organizations–Identity–IDM–Access responsibility path; add Campaign delivery
to a function in an organizational unit and prove reassignment, delegation,
vacancy, retention, and audit behavior.
3. **Templates, Reports, and deep launch.** Build one data-backed document and
one report through curated source contracts; open the task safely from a
mock and then target HIS-style producer; preserve reproducible input,
definition, output, and return-reference evidence.
4. **Governed university BI path.** Starting from that concrete source, add one
scheduled staging, quality, transformation, semantic-product, lineage, and
policy-aware reporting path. Package it for repeatable promotion between
development, test, and production before generalizing dataflow.
5. **Collaborative document lifecycle.** Add DMS versions, review/approval,
provider-neutral editing sessions, one collaborative editor, conflict and
recovery behavior, and Records handoff over Files-backed content.
6. **Maintain already integrated product slices.** Complete regression and
target acceptance for calendar/scheduling/poll and other shipped foundations
without displacing the selected reference path; implement new feature
programs only when they are required by a stage or explicitly reprioritized.
7. **Resume Workflow only by explicit priority decision.** When resumed, start
with stable actions from a demonstrated package; do not turn it into a
second domain layer.
9. **Advance records/compliance and later domain configurations** only when the
shared spine and a concrete regulated or institutional journey are ready to
consume them.
## Product decisions to make progressively
@@ -1145,8 +1243,6 @@ them; they do not block the product vision today.
reference release?
- Which real identity, groupware, file/DMS, and deployment stack should define
the first integration profile?
- Which service package should follow controlled communications: public
service, internal report-to-resolution, training, or institutional meetings?
- When should the postponed Workflow program resume, and which single package
will constrain its first implementation?
- Which objects and fields remain authoritative in GovOPlaN versus each target
@@ -1154,7 +1250,21 @@ them; they do not block the product vision today.
- Which default participant privacy profiles should ship for scheduling,
consultation, committee, and public participation?
- What assurance, signature, federation, and E2EE levels are required for the
first trusted postbox deployment?
first trusted postbox deployment?
- Which external IDM source and conflict, disable, delegation, and vacancy
policy should prove delivery to organizational responsibility?
- Which HIS or other specialist system should be the first deep-launch
producer, and which callback/reference behavior can it support?
- Which bounded university dataset, reporting date semantics, official keys,
accepted calculation, privacy profile, and drill-down level should define the
first analytical data product?
- After the first source-to-report proof, do repeated source/dataflow contracts
justify separate `govoplan-datasources` and `govoplan-dataflow` modules?
- Which collaborative editor should be the first target, and should its first
accepted experience emphasize concurrent editing, controlled check-out, or
both?
- Which archive/records target and signature or approval assurance level should
receive the first accepted collaborative rendition?
- Which sanctions/embargo data source or provider, matching policy, legal basis,
review roles, evidence period, and rescreen triggers should define the first
export-control package?
@@ -1180,6 +1290,12 @@ when it accumulates modules. Useful measures include:
package;
- successful restore and disaster-recovery drills within declared objectives;
- connector health, freshness, conflict, and manual-intervention backlog;
- percentage of generated artifacts and reported measures reproducible from
versioned source, transformation, definition, parameter, and output evidence;
- analytical freshness, validation/quarantine resolution, schema-drift, and
permitted drill-down outcomes for each published data product;
- collaborative save-conflict, recovery, review, approval, and accepted-version
integrity outcomes;
- privacy and records-policy conformance with documented exceptions;
- reuse of the same package across institutions without code forks; and
- reduction in special-case module coupling and deployment-local patches.
@@ -1196,8 +1312,11 @@ when it accumulates modules. Useful measures include:
- Describing corrective actions as if they erase already observed effects.
- Making raw JSON, deployment files, or direct database edits the normal
configuration experience.
- Building a broad BI/dataflow, native project-management, mobile, or embedded
AI program before reference journeys prove the shared need.
- Building an unbounded general-purpose dataflow platform before the selected
source-to-document and university source-to-indicator journeys prove the
contracts; BI itself is now an explicit reference-program stage.
- Building native project-management, mobile, or embedded AI programs before a
reference journey proves the shared need.
- Claiming production readiness from unit tests, local source checkouts, or
connector scaffolds alone.

401
docs/REFERENCE_JOURNEY_PROGRAM.md Normal file
View File

@@ -0,0 +1,401 @@
# GovOPlaN Reference Journey Program
## Status
This is the selected product-development sequence as of 2026-07-21. It turns
the long-term connected-platform roadmap into five demonstrable journeys while
the Workflow program remains deliberately deferred.
The stages are ordered, but they are not monolithic releases. Each stage is
delivered as small, reviewable, green increments and is complete only when its
user journey, failure behavior, documentation, and operator evidence work in a
pinned composition.
## Why this sequence
The sequence grows one connected product rather than advancing repositories in
isolation:
```text
Campaign reference
-> function-bound Postbox delivery
-> data-backed templates and reports
-> governed analytical data products
-> collaborative document lifecycle
```
Each stage reuses the preceding contracts:
- Campaign proves governed recipient selection, files, profiles, preview,
durable delivery, retry, reconciliation, audit, and role-specific UI.
- Postbox generalizes delivery from an email address to an institutional
responsibility that survives personnel changes.
- Templates and Reporting turn governed source data into reproducible outputs
and provide a safe launch boundary for specialist systems such as HIS.
- The BI path scales those source, transformation, quality, lineage, and report
contracts from one document to reusable analytical data products.
- DMS collaboration turns generated or uploaded artifacts into governed living
documents without confusing storage, editing, approval, or records
ownership.
## Continuous foundation lane
This lane is not a sixth product stage. It advances only as far as the next
journey needs and supplies contracts shared by all five stages.
1. **Governed integrations.** Connector profiles declare endpoint, authority,
source-of-truth mode, capabilities, health, limits, credential references,
and lifecycle. Network destinations are resolved and pinned at connection
time; private-network access is deployment-controlled and unpinned private
transports fail closed.
2. **External effects.** Requested action, durable command, observed effect,
unknown outcome, retry, reconciliation, compensation/correction, and manual
intervention remain distinct and auditable.
3. **Institutional identity.** Identity owns subjects, Organizations owns units
and functions, IDM owns identity-to-function assignments and upstream
synchronization, and Access owns permission and acting-context decisions.
4. **Stable composition.** Modules cooperate through versioned Core-mediated
capabilities and typed references. Optional sibling modules are never
imported as implementation dependencies.
5. **Evidence and provenance.** Every imported datum, generated artifact,
delivery, transformation, and later correction can identify its source,
version, actor or system trigger, policy, and relevant execution evidence.
6. **Focused experience.** Central components and the interface pattern
language are mandatory. Views present only what the current task and actor
need while preserving an explainable escape to the configured full system.
7. **Adaptive documentation.** The owning module contributes canonical subject
matter; GovOPlaN Docs composes it for the installed modules, enabled
configuration, role, route, and task.
8. **Release proof.** Version alignment, clean install/upgrade, module
permutations, backup/restore, degraded-provider behavior, security checks,
and target-environment acceptance gate product claims.
## Documentation contract for every reference stage
Documentation is one connected knowledge model rendered through different
perspectives, not separately maintained manuals that drift.
Every demonstrated journey provides:
- **Task guidance:** “I want to …” instructions using visible UI wording.
- **Process view:** actors, inputs, states, decisions, handoffs, exceptions,
completion, correction, and retention.
- **Concept view:** domain language and ownership boundaries.
- **Administrator view:** permissions, policies, profiles, configuration,
module requirements, migrations, and audit effects.
- **Operator view:** health, queues, retries, reconciliation, backup/restore,
incident handling, and target-provider checks.
- **Integration view:** capabilities, DTOs, APIs, events, idempotency,
compatibility, deep-link/launch contracts, and example payloads.
- **Security, privacy, and audit view:** threats, disclosure rules, secrets,
provenance, evidence, retention, and destructive actions.
- **Acceptance view:** runnable examples, expected results, failure injection,
and release gates.
The Docs module selects and links these views according to installed
capabilities and actor context. Feature repositories remain the source of
truth for their behavior; Docs owns indexing, conditions, safe disclosure, and
presentation. Generated API/contract reference may supplement, but never
replace, the maintained behavioral explanation.
## Stage 1: Campaign as the demonstration module
### Product promise
> As a communications team, we can compose a campaign from governed recipient
> data, managed files, reusable mail configuration, and policy; preview the
> exact effect; authorize delivery; and resolve every recipient to a known or
> explicitly uncertain outcome without exposing transport internals to normal
> readers.
Campaign is the first reference composition, not an all-purpose mail client or
contact database.
### Ownership and composition
- Campaign owns campaign intent, content, campaign-local recipient snapshots,
personalization, execution state, and delivery evidence.
- Mail owns reusable profiles, credentials, protocol adapters, profile policy,
send/append execution, and provider-facing diagnostics. Campaign persists
only a stable Mail profile reference, never SMTP/IMAP settings or secrets.
- Files owns stored objects, provider connectors, file policy, and provenance.
Campaign persists stable attachment references and frozen execution evidence.
- Addresses or another directory may supply recipients, but Campaign freezes
the execution-time recipient and source evidence needed to explain the send.
- Policy, Access, Audit, Docs, Notifications, Organizations, Identity, IDM, and
Postbox contribute only through declared capabilities when installed.
### Implementation slices
1. Enforce the Mail-profile-only boundary and reject inline transport material
on authoring, import, update, build, and delivery paths. Legacy records are
preserved but fail closed until explicitly migrated.
2. Finish the central-component UI pass and consistent task-focused author,
reviewer, operator, and reader surfaces. Normal readers receive business
state, not paths, backend keys, worker claims, or raw provider diagnostics.
3. Prove test, single-send, resend, batch, append-to-Sent, retry,
reconciliation, quarantine, and manual intervention semantics against a
target SMTP/IMAP environment.
4. Complete adaptive Campaign, Mail, and Files documentation under the shared
documentation contract, including runnable reference campaigns and failure
drills.
5. Package the composition with sample data, policies, roles, configured views,
preflight, health checks, and pinned compatible versions.
### Gate
A clean installation can run the maintained examples through target providers;
no Campaign payload contains transport credentials; worker/provider failures do
not cause blind duplicate delivery; each supported role sees an appropriate
surface and explanation; install, upgrade, restore, and release evidence are
repeatable.
## Stage 2: Postbox and delivery to institutional responsibility
### Product promise
> As a sender, I can deliver a message to a named function in an organizational
> unit without knowing which individual currently performs it. As the current
> function holder or authorized delegate, I can discover, read, and act on that
> message; when assignments change, access follows current responsibility while
> the delivery and access history remains explainable.
### Ownership and composition
- Postbox owns addressable in-platform postboxes, messages, bindings,
participants, attachment references, access-sensitive events, and retention
inputs.
- Organizations defines units and functions. Identity defines subjects. IDM
assigns identities to functions and reconciles upstream directories. Access
resolves roles, delegations, acting context, and permissions.
- Mail is an optional external channel bridge. A Postbox is not an SMTP/IMAP
account and is never owned by one login credential.
- Campaign consumes a generic delivery-target capability. It may target an
email recipient or a function-bound Postbox without importing either
module's internals.
### Implementation slices
1. Stabilize Postbox manifest, permissions, DTOs, migrations, directory,
binding administration, access decisions, message create/list/read, and
audit events.
2. Define a typed delivery target and receipt contract for a Postbox id or an
organization-unit/function address. Resolution never copies current holders
into permanent mailbox ownership.
3. Complete the Organizations–Identity–IDM–Access function-assignment and
delegation path, including provenance and compatibility migration from
legacy projections.
4. Add Campaign delivery to a function-bound Postbox, file attachment
references, optional external-mail bridge, and notification attention
signals through capabilities.
5. Document reassignment, delegation, vacancy, expired assignment, unavailable
optional module, retention, and future E2EE limitations honestly.
### Gate
A campaign message can be delivered once to a function-bound Postbox; an
authorized holder can act in an explicit context; a reassignment changes future
access without moving or rewriting the message; vacancy and ambiguous context
fail visibly; delivery, access, and later corrections remain auditable.
## Stage 3: Templates, reports, data sources, and deep launches
### Product promise
> As a staff member arriving from a specialist system such as HIS, I can open a
> GovOPlaN report or document task with a governed source context already
> selected, review the effective data and template version, generate the
> document, and return or link the immutable result without re-entering data.
### Ownership and composition
- Templates owns reusable definitions, versions, merge schemas, localization,
render profiles, preview, and rendering.
- Reporting owns report definitions, parameters, curated data selection,
execution history, dashboards, sharing, scheduling, publication, and export.
- Connectors own protocol-specific access. A governed data-source catalog owns
connection profiles, source contracts, freshness, and health if repeated
use proves that a separate module is warranted.
- Files stores generated bytes. DMS owns a generated artifact once it becomes a
governed living document. Records owns later retention/archive semantics.
### Safe launch and generation contract
1. The source program opens a stable GovOPlaN route with an opaque, short-lived,
single-purpose launch reference—not credentials, arbitrary SQL, or trusted
personal data in the URL.
2. GovOPlaN authenticates the actor, authorizes the requested report/template
and source object, resolves the launch context server-side, and shows source,
freshness, purpose, and any blockers.
3. A curated connector/read-model capability returns a versioned input snapshot
that satisfies the template or report schema.
4. Generation records template/report definition version, parameters, input
snapshot or reproducible source references, transformation version, output
checksum, actor, and policy.
5. The result is stored or handed back through an explicit callback/reference
contract. Retries are idempotent; expired or replayed launch references fail
safely.
### Implementation slices
1. Implement the first Templates manifest, version/schema DTOs, safe preview,
deterministic render, package fragments, and Files-backed output.
2. Implement the first Reporting manifest, parameter/source DTOs, one
module-owned read model, execution evidence, and downloadable export.
3. Define the shared data-source/profile and launch-context contracts with one
read-only target connector and a mock HIS-style launch producer.
4. Deliver one end-to-end reference document and one analytical report from the
same governed source contract.
5. Add role-specific UI/docs, source freshness and validation states, deep-link
integration examples, and target-system acceptance tests.
### Gate
A user can follow a signed or server-side launch reference from a target system
to a prefilled GovOPlaN task, verify the source and freshness, render an output,
and reproduce why that exact artifact was produced. The browser cannot inject
arbitrary queries or transport secrets, and authorization is re-evaluated in
GovOPlaN.
## Stage 4: Governed BI and reporting
### Product promise
> As an institutional analyst, I can combine approved operational sources into
> versioned, quality-checked analytical data products, define transparent
> measures and reports, drill from aggregates where policy permits, and explain
> the source, transformation, effective organizational hierarchy, and reporting
> date behind every result.
### Lessons taken from SuperX
SuperX is useful inspiration because it combines many university sources in a
modular data warehouse, loads and transforms them on a schedule, keeps
historical or reporting-date views, supplies prepared subject modules, and
serves different aggregation levels through a common reporting surface. Its
official overview also emphasizes a lower operational-data layer, validation
logs, configurable load routines, organizational hierarchies, and transparent
report calculations. See the
[SuperX project overview](https://www.superx-projekt.de/__index.htm),
[administration and module architecture](https://www.superx-projekt.de/doku/kern_modul/admin/__index.htm),
and [cross-institution indicator module](https://www.superx-projekt.de/doku/kenn_modul/benutzer/__index.htm).
GovOPlaN should adopt the principles, not clone the implementation. Its distinct
value is connecting analytical results to governed work, responsibility,
evidence, policy, and correction across independently installable modules.
### Architecture layers
1. **Source catalog:** governed profiles, owners, purpose, schema/version,
classification, credentials, health, extraction mode, and source-of-truth
declaration.
2. **Ingestion and staging:** immutable run evidence, source snapshots or
watermarks, schema-drift detection, quarantine, replay, and personal-data
minimization.
3. **Transformation and quality:** versioned transformations, dependencies,
tests, validation findings, correction policy, and lineage. Silent repair of
source facts is not acceptable.
4. **Semantic products:** documented dimensions, measures, official key
mappings, organizational hierarchies, time/stichtag semantics, ownership,
access policy, and version.
5. **Consumption:** Reporting definitions, dashboards, drill-down, scheduled
outputs, APIs, open-data handoffs, and template generation.
6. **Operations:** scheduling, backfill, freshness objectives, observability,
cost/resource limits, retention, backup/restore, promotion between systems,
and reproducible release recipes.
### Implementation slices
1. Select one bounded, read-only university dataset and one decision-relevant
report; define its legal/policy basis, source owner, official keys, time
semantics, and acceptance calculation.
2. Generalize the Stage 3 source profile into catalog, ingestion-run, staged
dataset, validation, transformation, lineage, and data-product contracts.
3. Implement one scheduled incremental load with quarantine/replay and a fully
transparent transformation into an aggregate product.
4. Serve the product through Reporting with policy-aware aggregate and
drill-down behavior; export reproducible evidence and calculation metadata.
5. Package mappings, transformations, validations, reports, documentation, and
tests so they can be promoted from development to test to production.
### Gate
One university data product can be rebuilt from a declared source snapshot or
watermark, passes explicit quality tests, explains every measure and mapping,
enforces disclosure policy, survives schema/freshness failures visibly, and
produces the same accepted report across promoted environments.
## Stage 5: Collaborative document editing
### Product promise
> As an authorized group, we can turn an uploaded or generated artifact into a
> shared document, edit it concurrently or through controlled check-out,
> comment, review, approve, compare, and recover versions, then freeze the
> accepted rendition as evidence or a record without losing who changed what.
### Ownership and composition
- Files owns bytes, checksums, storage providers, upload/download, and low-level
file permissions.
- DMS owns document identity, versions, renditions, editing sessions, locks,
comments, reviews, approvals, signatures, external DMS references, and
document-level evidence.
- A collaboration connector owns provider-specific Collabora, OnlyOffice,
Nextcloud/OpenDesk, or another office-suite protocol. DMS owns the session
lifecycle and authorization even when editing occurs externally.
- Templates may create the first version. Cases, Campaign, Postbox, Reporting,
and Workflow may reference documents. Records owns classification, legal
hold, archive handoff, and disposal after the document enters that lifecycle.
### Implementation slices
1. Implement DMS document/version/reference DTOs and one Files-backed version
path, including optimistic concurrency, checksums, locks, and audit.
2. Add comments, review requests, approval state, immutable accepted
renditions, comparison, and recovery of prior versions.
3. Define a provider-neutral editing-session capability with short-lived
grants, callback authentication, save idempotency, health, and reconciliation.
4. Integrate one external collaborative editor, including loss of provider,
concurrent save, stale callback, permission revocation, and restore tests.
5. Connect generated reports/templates, Postbox/Campaign sharing, focused
document views, configured docs, and Records handoff.
### Gate
Multiple authorized actors can edit a document without silent lost updates;
every accepted version has stable content and provenance; provider callbacks
cannot bypass current authorization; degraded or ambiguous saves are visible
and reconcilable; the approved rendition can enter records without making Files
or the external editor the document-lifecycle owner.
## Program-wide acceptance and pause rules
- Do not start a broad generic platform abstraction until two concrete stages
demonstrate the repeated contract.
- Do not make Workflow a dependency of these stages. Manual transitions,
explicit actions, and focused views should become stable providers that a
later transition engine can coordinate.
- Do not treat a remote system as trusted merely because it supplied a deep
link, callback, webhook, file, identity, or data row.
- Do not claim a stage complete from local unit tests. Use pinned composition,
target integration, failure drills, adaptive docs, and operator evidence.
- A later stage may prototype contracts while the preceding gate is being
proven, but it may not redefine an owning module's boundary by convenience.
## Decisions intentionally deferred
The sequence itself is selected. These bounded choices remain for the stage
that first needs them:
- first target SMTP/IMAP, file/directory, identity, and deployment profile;
- first external IDM source and identity conflict/disable policy;
- first trusted Postbox assurance/E2EE profile and external-mail bridge;
- first HIS or other launch producer and callback/reference contract;
- first university dataset, report, reporting date semantics, and permitted
drill-down level;
- whether repeated data-source and dataflow contracts justify separate
`govoplan-datasources` and `govoplan-dataflow` modules after the Stage 3 proof;
- first collaborative editor/provider and whether the first UX is concurrent
editing, controlled check-out, or both; and
- first Records/archive target and approval/signature assurance level.