From fab115d2a7a6755c551505b7deab8f5eda442dd0 Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Tue, 7 Jul 2026 21:17:31 +0200 Subject: [PATCH] Sync wiki from project files --- Repo-docs-CONFIGURATION-PACKAGES.md | 9 +- Repo-docs-GOVERNMENT-OPERATIONS-VISION.md | 224 ++++++++++++++++++++++ Repo-docs-GOVOPLAN-MODULE-ROADMAP.md | 10 +- 3 files changed, 241 insertions(+), 2 deletions(-) create mode 100644 Repo-docs-GOVERNMENT-OPERATIONS-VISION.md diff --git a/Repo-docs-CONFIGURATION-PACKAGES.md b/Repo-docs-CONFIGURATION-PACKAGES.md index ab999b7..75c2942 100644 --- a/Repo-docs-CONFIGURATION-PACKAGES.md +++ b/Repo-docs-CONFIGURATION-PACKAGES.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/CONFIGURATION_PACKAGES.md`. > Origin: `repository`. @@ -16,6 +16,13 @@ Example: an application-handling package could configure a public portal form, a case workflow, task creation, a mail template, payment processing, access roles, audit evidence, and the interface bindings between those modules. +The guiding reference scenario is the government-operations permit journey in +`docs/GOVERNMENT_OPERATIONS_VISION.md`: a person applies through the portal, +uploads files, receives workflow-driven messages and appointment proposals, has +a case opened, gets a permit generated from a template, and completes payment. +Configuration packages are the mechanism that should make such processes +reusable and safely importable. + This document is durable architecture context and should be mirrored to the Gitea wiki. Active implementation should be tracked in Gitea issues. diff --git a/Repo-docs-GOVERNMENT-OPERATIONS-VISION.md b/Repo-docs-GOVERNMENT-OPERATIONS-VISION.md new file mode 100644 index 0000000..f7d5c73 --- /dev/null +++ b/Repo-docs-GOVERNMENT-OPERATIONS-VISION.md @@ -0,0 +1,224 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-core/docs/GOVERNMENT_OPERATIONS_VISION.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# GovOPlaN Government Operations Vision + +This document is the durable product north star for GovOPlaN as a modular +platform for administrative operations. It should be mirrored to the Gitea wiki. +Active implementation belongs in Gitea issues and module-specific follow-ups. + +The goal is not to replace every existing system. GovOPlaN should connect +existing systems, provide better workflows where the current landscape is weak, +and make administrative processes configurable, auditable, and reusable. + +## Guiding Reference Journey + +A useful reference process is a permit application that crosses public portal, +back-office workflow, documents, appointments, templates, notifications, and +payments: + +1. A person applies for a permit through the public portal. +2. The applicant uploads required files and submits structured form data. +3. Submission creates a case, a workflow instance, and an internal task. +4. Completing the task creates a postbox message, a notification, and an email + notification with an appointment proposal. +5. The applicant accepts an appointment, which updates the calendar and the + workflow state. +6. During the appointment, the case is opened and the permit is generated from a + governed template. +7. The payment is processed and linked to the case. +8. The permit, payment evidence, communication history, and audit trail remain + available according to policy and retention rules. + +This journey should be possible to model as a configuration package once the +participating modules exist. The package should wire module-owned fragments +together without core knowing module internals. + +## Design Principles + +- Modules must stay independently installable, enableable, and disableable. +- Cross-module behavior should use core-mediated capabilities, commands, events, + DTOs, and UI contribution points rather than direct imports. +- Configuration packages should turn installed modules into concrete, reusable + administrative processes. +- Operators should be able to configure the platform through the UI. +- Every powerful configuration path needs preflight, preview, audit, rollback, + RBAC, and policy checks. +- Integration should be a first-class product path: connect to existing systems, + consume their data, and publish governed outputs back to them. +- GovOPlaN should scale from a small local installation to a larger deployment + with separately scalable web, API, worker, storage, and database components. + +## Capability Map + +| Capability | Likely owner | +| --- | --- | +| Public application entry point | `govoplan-portal` | +| Structured forms and validation | `govoplan-forms` | +| Uploaded files and managed storage | `govoplan-files` | +| Case record and lifecycle | `govoplan-cases` | +| Workflow transitions and automation | `govoplan-workflow` | +| Internal work queues and tasks | `govoplan-tasks` | +| Appointment proposals and booking | `govoplan-appointments`, `govoplan-calendar` | +| Postbox, email, and notifications | `govoplan-mail`, `govoplan-notifications` | +| Permit/document generation | `govoplan-templates`, `govoplan-dms` | +| Payment capture and accounting handoff | `govoplan-payments`, `govoplan-ledger` | +| Roles, permissions, tenants, policy, audit | `govoplan-access`, `govoplan-tenancy`, `govoplan-policy`, `govoplan-audit` | +| External software integration | `govoplan-connectors` | +| Recurring extraction and transformation | proposed `govoplan-datasources`, proposed `govoplan-dataflow` | +| Reports, BI, and management visibility | `govoplan-reporting` | + +## Integration Landscape + +The integration strategy should start with research and connector catalogues. +The product needs a structured view of common public-sector systems and +recurring integration patterns before deciding where native modules are worth +building. + +Research should cover: + +- citizen portals and service portals +- DMS/e-file systems and archive systems +- case-management and workflow platforms +- ERP, finance, accounting, payment, and cash-register systems +- identity providers, LDAP/Active Directory, SAML, OIDC, OpenDesk, and IAM tools +- groupware, mail, calendar, postbox, and notification systems +- document collaboration, chat, video conferencing, and project-management tools +- FIT-Connect, XTA/OSCI, XRechnung, XOE/V, ePayment, and other public-sector + protocol families +- file shares, Nextcloud, Seafile, WebDAV, SMB/NFS, and object storage +- reporting, BI, open-data, RSS/API publication, and data-exchange endpoints + +The output should be a ranked connector backlog with owners, protocols, +authentication models, data shapes, operational risks, and minimum viable +integration tests. + +## Recurring Data Extraction And Transformation + +A concrete recurring use case is monthly extraction and transformation of data +received from one or more sources, preparing files for several downstream +systems by applying transformation rules. + +This should become a datasource-plus-workflow-plus-dataflow capability: + +- register datasources for uploads, file locations, APIs, databases, and + external systems +- discover or declare schemas +- define transformation rules, mapping versions, validation rules, and output + formats +- schedule monthly runs and allow manual reruns +- produce previewable diffs and validation diagnostics before publication +- write output files to configured destinations +- keep provenance, lineage, input hashes, generated outputs, operator actions, + and audit evidence +- let workflows react to success, warning, failure, or manual approval + +`govoplan-datasources` and `govoplan-dataflow` are proposed module boundaries +for this area if the scope grows beyond connectors and reporting. + +## Full UI Configuration + +The long-term target is that operators configure the platform through the UI +instead of editing files for normal operation. + +UI-managed configuration should include: + +- module installation, enablement, lifecycle state, and health +- tenants, users, groups, roles, policies, and permissions +- connectors, credentials, secret references, and external service tests +- workflows, forms, templates, task queues, schedules, and notifications +- configuration package import/export and environment-specific data collection +- retention, audit, privacy, maintenance mode, and safety controls +- deployment-visible settings such as public URLs, mail senders, storage + profiles, queues, and worker capabilities + +Safety controls should include dry-run plans, field-level validation, policy +explanations, two-person approval for destructive changes, versioned +configuration history, rollback paths, audit events, and maintenance-mode +guards. + +## Scalability + +GovOPlaN should be manually scalable first and automatically scalable where the +deployment platform supports it. + +The architecture should support: + +- stateless web/API processes behind a reverse proxy or load balancer +- separate background workers for mail, workflow jobs, imports, exports, + transformations, notifications, and scheduled tasks +- PostgreSQL as the production database path +- object/file storage that can grow independently from the API process +- queue-backed job dispatch with retry, deduplication, and observability +- cache and lock services only where they are optional or operationally + documented +- health checks, readiness checks, metrics, and clear degraded-mode behavior + +The product needs realistic sizing profiles instead of guessed requirements. +Sizing should account for tenants, concurrent users, cases, files, storage +volume, upload/download rates, campaign volume, workflow jobs, transformation +runs, reporting load, and retention/audit growth. + +## Hardware Requirements + +Hardware guidance should be empirical and deployment-shaped. The first sizing +matrix should distinguish: + +- local development +- single-office pilot +- small production tenant +- medium municipal deployment +- larger shared deployment with separate workers and PostgreSQL + +Each profile should document CPU, memory, disk, database, storage, queue/cache, +backup, and monitoring requirements, plus the assumptions behind the numbers. +A later calculator can turn operator inputs into recommended profiles. + +## Collaboration + +Collaboration should be integration-first. GovOPlaN should connect with strong +existing tools and provide native behavior only where the administrative process +needs tighter governance than an external tool can provide. + +Target areas: + +- collaborative document editing and versioning through DMS integrations +- comments, internal notes, and task discussions attached to cases and workflow + items +- chat and messaging connectors +- video conferencing connectors with appointment/workflow handoff +- project-management connectors, with OpenProject as the first likely target +- presence, notifications, and activity streams where they improve operational + handoff + +Native modules are justified when GovOPlaN must own the domain semantics, +permissions, audit trail, retention behavior, or configuration package fragments. + +## Relationship To Configuration Packages + +The permit-to-payment journey should become a reference configuration package. +The package imports module-owned fragments, binds interfaces between modules, +asks the operator for deployment-specific data, and validates everything before +applying it. + +See `docs/CONFIGURATION_PACKAGES.md` for the concrete package model. + +## Tracking Issues + +The cross-cutting backlog starts with these core tracking issues. Split +module-specific child issues from them when implementation begins. + +| Topic | Tracking | +| --- | --- | +| Government operations backbone reference model | `add-ideas/govoplan-core#213` | +| Permit-to-payment configuration package | `add-ideas/govoplan-core#214` | +| Public-sector integration landscape catalogue | `add-ideas/govoplan-core#215` | +| Recurring datasource and data-transformation workflows | `add-ideas/govoplan-core#216` | +| Scalability profiles and autoscaling readiness | `add-ideas/govoplan-core#217` | +| Fully UI-managed configuration with safety controls | `add-ideas/govoplan-core#218` | +| Hardware sizing matrix and requirements calculator | `add-ideas/govoplan-core#219` | +| Collaboration suite integration strategy | `add-ideas/govoplan-core#220` | diff --git a/Repo-docs-GOVOPLAN-MODULE-ROADMAP.md b/Repo-docs-GOVOPLAN-MODULE-ROADMAP.md index fcba663..30e65f8 100644 --- a/Repo-docs-GOVOPLAN-MODULE-ROADMAP.md +++ b/Repo-docs-GOVOPLAN-MODULE-ROADMAP.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/GOVOPLAN_MODULE_ROADMAP.md`. > Origin: `repository`. @@ -13,15 +13,20 @@ This page maps current module and integration ideas to existing GovOPlaN reposit | Idea | Owner | Tracking | | --- | --- | --- | +| Government operations backbone reference model | `govoplan-core` | `add-ideas/govoplan-core#213` | +| Permit-to-payment configuration package | `govoplan-core` plus participating modules | `add-ideas/govoplan-core#214` | +| Fully UI-managed configuration with safety controls | `govoplan-admin`, `govoplan-core`, `govoplan-policy`, `govoplan-access`, `govoplan-audit` | `add-ideas/govoplan-core#218` | | Access as a module | `govoplan-access` | `add-ideas/govoplan-access#7` | | OpenProject API / project management connector | `govoplan-connectors` | `add-ideas/govoplan-connectors#1` | | Native project-management module decision | `govoplan-core` | `add-ideas/govoplan-core#196` | | Datasources for databases, CSV, files, APIs | proposed `govoplan-datasources` | `add-ideas/govoplan-core#197` | | Dataflow for pipelines, BI, publication | proposed `govoplan-dataflow` | `add-ideas/govoplan-core#198` | +| Monthly datasource and transformation workflows | proposed `govoplan-datasources`, proposed `govoplan-dataflow`, `govoplan-workflow`, `govoplan-reporting` | `add-ideas/govoplan-core#216` | | Templates for letters, emails, forms, reports | `govoplan-templates` | `add-ideas/govoplan-templates#1` | | Reporting and BI | `govoplan-reporting` | `add-ideas/govoplan-reporting#1` | | File connectors: Nextcloud, Seafile, SMB, NFS | `govoplan-files` | `add-ideas/govoplan-files#15` | | Public-sector software integration catalogue | `govoplan-connectors` | `add-ideas/govoplan-connectors#2` | +| Public-sector integration landscape catalogue | `govoplan-connectors` with core tracking | `add-ideas/govoplan-core#215` | | Adrema-style address and distribution-list management | `govoplan-addresses` | `add-ideas/govoplan-addresses#1` | | Consume sources and become a governed source | `govoplan-connectors` plus proposed `govoplan-dataflow` | `add-ideas/govoplan-connectors#3`, `add-ideas/govoplan-core#198` | | Terminfindung and meeting scheduling polls | `govoplan-scheduling` | local scaffold; remote creation tracked by `add-ideas/govoplan-core#199` | @@ -34,6 +39,9 @@ This page maps current module and integration ideas to existing GovOPlaN reposit | OpenDesk stack integration map | `govoplan-connectors` | `add-ideas/govoplan-connectors#5` | | Open-Xchange mail/groupware | `govoplan-mail` | `add-ideas/govoplan-mail#5` | | Open-Xchange calendar | `govoplan-calendar` | `add-ideas/govoplan-calendar#2` | +| Scalability profiles and autoscaling readiness | `govoplan-ops`, `govoplan-core` | `add-ideas/govoplan-core#217` | +| Hardware sizing matrix and requirements calculator | `govoplan-ops`, `govoplan-core` | `add-ideas/govoplan-core#219` | +| Collaboration suite integration strategy | `govoplan-connectors`, `govoplan-dms`, `govoplan-workflow`, `govoplan-tasks`, `govoplan-appointments`, `govoplan-calendar` | `add-ideas/govoplan-core#220` | ## Proposed Missing Modules