diff --git a/README.md b/README.md index 42a43f0..865a75a 100644 --- a/README.md +++ b/README.md @@ -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). diff --git a/docs/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md b/docs/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md index d59bfe2..a6e0fdb 100644 --- a/docs/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md +++ b/docs/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md @@ -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. diff --git a/docs/REFERENCE_JOURNEY_PROGRAM.md b/docs/REFERENCE_JOURNEY_PROGRAM.md new file mode 100644 index 0000000..165d974 --- /dev/null +++ b/docs/REFERENCE_JOURNEY_PROGRAM.md @@ -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.