288 lines
13 KiB
Markdown
288 lines
13 KiB
Markdown
# 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.
|