add-ideas/govoplan-core
1
0
Fork 0
Code Issues 45 Pull Requests Actions Packages Projects Releases Wiki Activity

Release v0.1.6

Browse Source
This commit is contained in:
Albrecht Degering
2026-07-07 16:00:38 +02:00
parent a2053518d1
commit 150b720f12
149 changed files with 14311 additions and 8005 deletions
Download Patch File Download Diff File Expand all files Collapse all files

287
docs/CONFIGURATION_PACKAGES.md Normal file
View File

@@ -0,0 +1,287 @@
# GovOPlaN Configuration Packages
Configuration packages are reusable, versioned preconfigurations for a working
GovOPlaN capability. They sit above modules: a module installs code,
migrations, routes, permissions, and capabilities; a configuration package wires
installed modules into a concrete operational setup.
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.
This document is durable architecture context and should be mirrored to the
Gitea wiki. Active implementation should be tracked in Gitea issues.
## Goals
- Import a preconfiguration from a trusted catalog or uploaded package.
- Detect which modules, module versions, and capabilities are required.
- Detect which configuration fragments must be created, updated, or bound.
- Explain import problems and offer actionable resolution paths.
- Ask the operator only for data needed to make the package work.
- Export an existing working configuration as a reusable package.
- Support signed catalogs so approved configurations can be shared, adapted,
re-exported, and provided to other installations.
## Vocabulary
| Term | Meaning |
| --- | --- |
| Module | Installable product code with manifest, migrations, routes, permissions, WebUI, events, and capabilities. |
| Configuration | Module-owned settings and resources that make behavior concrete: workflows, forms, templates, roles, policies, connector profiles, routing rules, and defaults. |
| Interface | A typed contract between modules: capabilities, commands, events, DTOs, data bindings, and UI extension points. |
| Data | Operator- or tenant-provided values needed for a working setup: legal text, sender addresses, account mappings, payment provider credentials, templates, defaults, and optionally reference data. |
The system should communicate these four layers explicitly:
```text
module = what can exist
configuration = what should exist here
interface = how configured parts connect
data = what the operator must provide for this deployment
```
## Package Model
A configuration package should be a signed, portable manifest plus module-owned
configuration fragments. The package is not a database dump. It should be
declarative, idempotent, tenant-aware, and explicit about secrets and external
systems.
Required package metadata:
- stable package id, name, version, description, publisher, and license
- supported GovOPlaN core/module compatibility bounds
- required modules with version constraints
- optional modules with conditional behavior
- required capabilities, commands, event subscriptions, and UI extension points
- configuration fragments grouped by owning module
- interface bindings between fragments
- data requirements to collect from the operator
- preflight checks and post-import health checks
- migration or transformation rules for older package versions
- provenance, export source metadata, and signature metadata
Configuration fragments are interpreted only by the module that owns them. For
example, workflow imports workflow definitions; forms imports form schemas;
mail imports mail templates and delivery defaults; payments imports payment
profiles; access imports groups, roles, and permission assignments.
## Module Provider Contract
Each module that wants to participate should expose a configuration-package
provider capability. The core orchestrator should not understand module internals
or write module-owned tables directly.
Baseline provider responsibilities:
- publish JSON Schema or equivalent typed schemas for importable/exportable
fragments
- publish data requirements that can be rendered by a generic wizard
- validate fragments without applying them
- report missing dependencies, missing permissions, conflicts, and unsafe
changes
- produce a dry-run plan with create, update, bind, skip, and blocked actions
- apply fragments idempotently inside module-owned boundaries
- export selected module-owned configuration into portable fragments
- redact secrets and mark secret placeholders during export
- provide post-apply health checks and operator-facing diagnostics
Provider operations should be versioned. The first stable contract can be small:
```text
describe() -> schemas, supported fragment types, exported scopes
preflight(package_fragment, context) -> diagnostics, required_data, plan
apply(package_fragment, supplied_data, context) -> result, created_refs
export(selection, context) -> fragment, data_placeholders, warnings
health(import_result, context) -> diagnostics
```
## Import Flow
1. Select a package from a trusted catalog or upload a package file.
2. Verify signature, channel, publisher trust, package compatibility, and schema.
3. Resolve required modules against installed modules and the module package
catalog.
4. Produce a dependency plan for modules that must be installed or upgraded.
5. Ask the operator for required data using a focused wizard.
6. Run dry-run preflight across all participating module providers.
7. Show problems grouped by severity, owner module, and resolution.
8. Apply module/package changes in a dependency-safe order.
9. Run post-import health checks and show the final working status.
10. Store import provenance, package version, supplied non-secret metadata, and
audit events.
The wizard should display everything necessary and nothing unnecessary. Generic
sections should cover package trust, dependency plan, required data, conflicts,
review, and result. Module-specific fields should appear only when the selected
package and installed modules require them.
## Problem Model
Import diagnostics should be structured and actionable, not free-text logs.
Every problem should include severity, owner, affected object, explanation, and
at least one suggested resolution when the system can infer it.
Common diagnostic types:
- missing module or incompatible module version
- missing capability or disabled optional integration
- missing operator-supplied data
- missing permission or insufficient administrator scope
- unresolved interface binding between modules
- conflicting existing configuration
- external service not reachable or credential test failed
- policy or tenant-governance violation
- unsafe overwrite, downgrade, or destructive change
- schema validation failure
- post-import health-check failure
Resolution actions can include install module, upgrade module, enable
integration, provide value, choose existing object, rename imported object,
skip optional fragment, replace existing configuration, or cancel import.
## Export Flow
Export should be possible from a working tenant or system configuration, but it
must be intentional about data boundaries.
1. Select export scope: system, tenant, module set, workflow, form, case type,
portal flow, or another domain object.
2. Ask participating modules to export owned fragments and data placeholders.
3. Classify exported material as configuration, reference data, sample data,
secrets, or deployment-local data.
4. Redact secrets by default and replace them with data requirements.
5. Let the operator choose whether to include reference/sample data.
6. Validate the assembled package by running the same preflight path against a
clean target context where possible.
7. Sign the package or produce an unsigned development package.
8. Optionally publish the package metadata to a configuration catalog.
Exported packages should record provenance: source GovOPlaN version, module
versions, exporter identity, timestamp, selected scope, redactions, and
validation status.
## Catalogs And Trust
Configuration catalogs should follow the existing module package catalog model:
a file-backed or remotely fetched JSON catalog with Ed25519 signatures, channel
gating, trusted key ids, and operator-controlled trust policy.
Catalog entries should include:
- package id, version, name, description, publisher, tags, and channel
- package artifact URL or repository ref
- signature metadata for the package artifact
- required modules and version ranges for quick compatibility display
- package category such as workflow, portal, case type, governance, connector,
report, or tenant baseline
- maturity flags such as official, verified, example, local, deprecated
The catalog verifies that a package is approved to view and import. The package
itself must still be signed and validated before use.
## Example Package
Application handling through a public portal:
Required modules:
- `portal` for the public user-facing entry point
- `forms` for the application form and validation
- `cases` for the case record and case type
- `workflow` for status transitions and automation
- `tasks` for internal task creation
- `templates` for mail/template rendering
- `mail` for delivery profile and outbound message sending
- `payments` for provider configuration and payment capture
- `access` for roles, groups, and permissions
- `audit` for import, case, mail, and payment evidence
Required configuration:
- portal route and access policy
- form schema, validation rules, confirmation texts, and attachments
- case type, fields, lifecycle states, and retention classification
- workflow steps, transitions, assignees, and completion triggers
- task template and queue/group assignment
- mail template and delivery rule
- payment product, amount rules, provider profile, and webhook binding
- access roles/groups for clerks, reviewers, supervisors, and operators
- audit event categories and evidence retention defaults
Required operator data:
- tenant or organizational unit
- service name and public contact details
- portal URL/path and legal imprint/privacy text
- mail sender profile and reply-to mailbox
- payment provider credentials or test-mode selection
- responsible groups or users for task assignment
- escalation contacts and deadlines
- template wording and localized text overrides
Potential problems:
- `payments` is missing or the provider capability is unavailable
- mail transport test fails for the selected sender profile
- imported role names conflict with existing tenant roles
- workflow references a task queue that does not exist
- public portal base URL is not configured
- required privacy/legal text is empty
- webhook endpoint cannot be validated from the payment provider
## Ownership
Core should own:
- package and catalog signature validation
- dependency resolution against installed modules and module catalogs
- orchestration of provider preflight/apply/export operations
- generic import/export APIs and audit envelope
- generic wizard shell and problem display components
Modules should own:
- schemas and semantics for their own fragments
- module-specific validation, apply, export, and health checks
- module-specific UI capabilities only when generic generated controls are not
sufficient
- redaction and classification of module-owned secrets or sensitive data
Access should own configuration fragments for users, groups, roles,
permissions, API keys, and principal mappings. It should not own workflow, mail,
payment, form, or portal semantics.
Admin should expose the operator-facing catalog, import, export, and history
screens through admin route contributions. The UI should keep the conceptual
layers visible: modules, configuration, interfaces, and data.
## Implementation Slices
1. Define package manifest and diagnostic schemas.
2. Add core configuration-package provider capability contracts.
3. Implement catalog validation and package signature verification.
4. Add dry-run orchestration against mock providers.
5. Add admin catalog/import wizard screens using provider data requirements.
6. Implement export/import providers for access-owned roles/groups first.
7. Add providers in workflow/forms/templates/mail/payments/portal/cases/tasks as
those modules mature.
8. Add round-trip tests: export a known setup, import into a clean tenant,
verify health checks.
9. Add documentation and field-level help for package authors and operators.
## Acceptance Criteria For Tracking Issue
- A Gitea tracking issue exists in `govoplan-core` for the cross-cutting
feature.
- The issue links module-specific follow-ups when implementation begins.
- The first implementation exposes typed contracts rather than direct
cross-module imports.
- A signed example catalog and unsigned development fixture exist.
- A dry-run import can identify required modules, missing data, and conflicts
before applying changes.
- An export can produce a package with secrets redacted into data requirements.
- Admin UI shows a focused wizard and actionable diagnostic list.
- Tests cover package validation, signature failure, dependency resolution,
provider preflight, export redaction, and import idempotency.