Sync wiki from project files
@@ -4,13 +4,17 @@
|
||||
|
||||
This page is generated from repository and product-directory project files.
|
||||
|
||||
- [Product govoplan-govoplan-concept-dev](Product govoplan-govoplan-concept-dev) - `/mnt/DATA/Nextcloud/ADD ideas UG/Products/govoplan/govoplan_concept_dev.md`
|
||||
- [Product govoplan-split-concept-action-plan](Product govoplan-split-concept-action-plan) - `/mnt/DATA/Nextcloud/ADD ideas UG/Products/govoplan/split-concept-action-plan.md`
|
||||
- [Repo-README](Repo-README) - `/mnt/DATA/git/govoplan-core/README.md`
|
||||
- [Repo-docs-ACCESS-RBAC-MODEL](Repo-docs-ACCESS-RBAC-MODEL) - `/mnt/DATA/git/govoplan-core/docs/ACCESS_RBAC_MODEL.md`
|
||||
- [Repo-docs-ACTION-EFFECT-AUTOMATION-LAYER](Repo-docs-ACTION-EFFECT-AUTOMATION-LAYER) - `/mnt/DATA/git/govoplan-core/docs/ACTION_EFFECT_AUTOMATION_LAYER.md`
|
||||
- [Repo-docs-AUTOMATION-CONTRACTS](Repo-docs-AUTOMATION-CONTRACTS) - `/mnt/DATA/git/govoplan-core/docs/AUTOMATION_CONTRACTS.md`
|
||||
- [Repo-docs-CODEX-WORKFLOW](Repo-docs-CODEX-WORKFLOW) - `/mnt/DATA/git/govoplan-core/docs/CODEX_WORKFLOW.md`
|
||||
- [Repo-docs-COMPATIBILITY-INVENTORY](Repo-docs-COMPATIBILITY-INVENTORY) - `/mnt/DATA/git/govoplan-core/docs/COMPATIBILITY_INVENTORY.md`
|
||||
- [Repo-docs-COMPATIBILITY-POLICY](Repo-docs-COMPATIBILITY-POLICY) - `/mnt/DATA/git/govoplan-core/docs/COMPATIBILITY_POLICY.md`
|
||||
- [Repo-docs-CONFIGURATION-PACKAGES](Repo-docs-CONFIGURATION-PACKAGES) - `/mnt/DATA/git/govoplan-core/docs/CONFIGURATION_PACKAGES.md`
|
||||
- [Repo-docs-DATAGRID-SIZING-CONTRACT](Repo-docs-DATAGRID-SIZING-CONTRACT) - `/mnt/DATA/git/govoplan-core/docs/DATAGRID_SIZING_CONTRACT.md`
|
||||
- [Repo-docs-DEPENDENCY-AUDITS](Repo-docs-DEPENDENCY-AUDITS) - `/mnt/DATA/git/govoplan-core/docs/DEPENDENCY_AUDITS.md`
|
||||
- [Repo-docs-DEPLOYMENT-OPERATOR-GUIDE](Repo-docs-DEPLOYMENT-OPERATOR-GUIDE) - `/mnt/DATA/git/govoplan-core/docs/DEPLOYMENT_OPERATOR_GUIDE.md`
|
||||
- [Repo-docs-DOCUMENTATION-MAP](Repo-docs-DOCUMENTATION-MAP) - `/mnt/DATA/git/govoplan-core/docs/DOCUMENTATION_MAP.md`
|
||||
@@ -28,6 +32,8 @@ This page is generated from repository and product-directory project files.
|
||||
- [Repo-docs-REMOTE-WEBUI-BUNDLES](Repo-docs-REMOTE-WEBUI-BUNDLES) - `/mnt/DATA/git/govoplan-core/docs/REMOTE_WEBUI_BUNDLES.md`
|
||||
- [Repo-docs-SECURITY-AUDIT](Repo-docs-SECURITY-AUDIT) - `/mnt/DATA/git/govoplan-core/docs/SECURITY_AUDIT.md`
|
||||
- [Repo-docs-SELF-HOSTED-INSTALLABILITY](Repo-docs-SELF-HOSTED-INSTALLABILITY) - `/mnt/DATA/git/govoplan-core/docs/SELF_HOSTED_INSTALLABILITY.md`
|
||||
- [Repo-docs-THEMING](Repo-docs-THEMING) - `/mnt/DATA/git/govoplan-core/docs/THEMING.md`
|
||||
- [Repo-docs-THROTTLING](Repo-docs-THROTTLING) - `/mnt/DATA/git/govoplan-core/docs/THROTTLING.md`
|
||||
- [Repo-docs-UI-UX-DECISION-LEDGER](Repo-docs-UI-UX-DECISION-LEDGER) - `/mnt/DATA/git/govoplan-core/docs/UI_UX_DECISION_LEDGER.md`
|
||||
- [Repo-docs-WEBUI-BUNDLE-BUDGETS](Repo-docs-WEBUI-BUNDLE-BUDGETS) - `/mnt/DATA/git/govoplan-core/docs/WEBUI_BUNDLE_BUDGETS.md`
|
||||
- [Repo-docs-audits-2026-07-09-dependency-audit](Repo-docs-audits-2026-07-09-dependency-audit) - `/mnt/DATA/git/govoplan-core/docs/audits/2026-07-09-dependency-audit.md`
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
+23
-1
@@ -1,4 +1,4 @@
|
||||
<!-- codex-wiki-sync:594f3007a25620d2f21ad852 -->
|
||||
<!-- codex-wiki-sync:1311c05df40139316e1e93fb -->
|
||||
|
||||
> Mirrored from `/mnt/DATA/git/govoplan-core/README.md`.
|
||||
> Origin: `repository`.
|
||||
@@ -23,6 +23,9 @@ Core owns:
|
||||
- kernel APIs for platform metadata, module lifecycle, health, and development diagnostics
|
||||
- `@govoplan/core-webui`, including login, CSRF/API helpers, shell layout, generic UI components, IconRail, DataGrid, access boundaries, and module route/nav contracts
|
||||
|
||||
The shared DataGrid sizing and resize invariants are specified in
|
||||
[`docs/DATAGRID_SIZING_CONTRACT.md`](docs/DATAGRID_SIZING_CONTRACT.md).
|
||||
|
||||
Platform and feature modules own their backend routers, models, migrations,
|
||||
permissions, frontend packages, nav items, and route contributions. Access,
|
||||
tenancy, policy, audit, and admin behavior live in their owning platform
|
||||
@@ -74,6 +77,21 @@ ENABLED_MODULES=access,campaigns /mnt/DATA/git/govoplan/.venv/bin/python -m govo
|
||||
|
||||
The runner loads the same `GovoplanServerConfig` as `govoplan_core.server.app:app`, builds the platform registry, and passes core plus enabled module source roots to uvicorn as reload directories. After reinstalling the editable package, the same command is also available as `govoplan-devserver`.
|
||||
|
||||
For focused backend work, keep the complete module graph active while watching
|
||||
only the module being edited. Core/config sources and explicit `--reload-dir`
|
||||
paths remain watched:
|
||||
|
||||
```bash
|
||||
/mnt/DATA/git/govoplan/.venv/bin/python -m govoplan_core.devserver \
|
||||
--reload-module calendar \
|
||||
--reload-module campaign
|
||||
```
|
||||
|
||||
Use `--reload-core-only` when no optional module source tree should trigger a
|
||||
restart. Omitting both options preserves the broad default and watches every
|
||||
enabled module. Startup, migration, and compatibility checks still run against
|
||||
the complete enabled graph whenever the backend restarts.
|
||||
|
||||
The default development database is PostgreSQL at `postgresql+psycopg://govoplan_dev@127.0.0.1:5432/govoplan_dev`. Store the password in `~/.pgpass`. To force the disposable SQLite fallback, run with `GOVOPLAN_DEV_DATABASE_BACKEND=sqlite`; that database lives below `runtime/`.
|
||||
|
||||
Local devserver runs do not require Redis. `CELERY_ENABLED` defaults to `false`, so campaign queue actions update database state without publishing Celery tasks. Use the synchronous send flow for local send tests, or set `CELERY_ENABLED=true` only when a Redis broker and worker are running.
|
||||
@@ -143,6 +161,10 @@ PATH=/home/zemion/.nvm/versions/node/v22.22.3/bin:$PATH /home/zemion/.nvm/versio
|
||||
|
||||
The local host links sibling module WebUI packages through local file dependencies and Vite filesystem allowances. Release builds should use `webui/package.release.json`, which points WebUI module packages at tagged git refs. See [RELEASE_DEPENDENCIES.md](docs/RELEASE_DEPENDENCIES.md).
|
||||
|
||||
Production builds lazy-load enabled module descriptors and enforce initial and
|
||||
asynchronous JavaScript budgets. See
|
||||
[WEBUI_BUNDLE_BUDGETS.md](docs/WEBUI_BUNDLE_BUDGETS.md).
|
||||
|
||||
## Module contract
|
||||
|
||||
Backend modules register through the `govoplan.modules` entry point and return a `ModuleManifest`. A manifest can contribute:
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- codex-wiki-sync:49ef87125712e15c51268e33 -->
|
||||
<!-- codex-wiki-sync:cb35e75b65354a4e7c849b7d -->
|
||||
|
||||
> Mirrored from `/mnt/DATA/git/govoplan-core/docs/ACTION_EFFECT_AUTOMATION_LAYER.md`.
|
||||
> Origin: `repository`.
|
||||
@@ -12,7 +12,7 @@ only linear screen flows. Workflows, schedules, imports, connectors, policies,
|
||||
and external events all need to request governed actions without bypassing the
|
||||
same safety rules that apply to human users.
|
||||
|
||||
The first implementation should live in `govoplan-workflow` and core contracts.
|
||||
The first implementation lives in `govoplan-workflow-engine` and Core contracts.
|
||||
Create a separate `govoplan-automation` module only if action planning,
|
||||
schedulers, rule execution, or cross-module automation become too broad for
|
||||
workflow ownership.
|
||||
@@ -36,6 +36,10 @@ of module capabilities.
|
||||
## Action Definition
|
||||
|
||||
An `ActionDefinition` describes something a human or system actor can request.
|
||||
The versioned runtime DTOs and provider protocol live in
|
||||
`govoplan_core.core.automation`; domain modules implement the protocol and
|
||||
Workflow resolves providers through module capabilities rather than importing
|
||||
their implementations.
|
||||
|
||||
Recommended fields:
|
||||
|
||||
@@ -102,6 +106,22 @@ The runner must never advance workflow state past a required side effect unless
|
||||
the action definition explicitly allows asynchronous completion and the pending
|
||||
state is visible.
|
||||
|
||||
For external and asynchronous effects, providers must preserve the distinction
|
||||
between:
|
||||
|
||||
1. requested intent;
|
||||
2. approved intent;
|
||||
3. dispatched command;
|
||||
4. possibly executed but unconfirmed outcome;
|
||||
5. confirmed observed effect;
|
||||
6. reconciled, corrected, or compensated outcome.
|
||||
|
||||
An API timeout after dispatch is not a failed effect and must not be retried as
|
||||
a fresh command. The actor context should retain the real identity/account,
|
||||
represented function or party, delegation or power, and mandate/jurisdiction
|
||||
references when applicable. Domain modules remain responsible for deciding
|
||||
which of those references are required for their action.
|
||||
|
||||
## Failure States
|
||||
|
||||
Automation should use explicit failure states:
|
||||
@@ -117,10 +137,15 @@ Automation should use explicit failure states:
|
||||
|
||||
These states should be visible in workflow, task, and admin diagnostics.
|
||||
|
||||
The contract names these states explicitly as `ActionExecutionState`, alongside
|
||||
`pending`, `running`, and `completed`. A provider returns observed effects even
|
||||
for partial failures; the runner, not the provider, owns durable attempts,
|
||||
recovery decisions, and workflow advancement.
|
||||
|
||||
## Boundary
|
||||
|
||||
Core may own stable DTOs, registry contracts, and generic audit/event hooks.
|
||||
`govoplan-workflow` should own the first runner because workflow is the first
|
||||
`govoplan-workflow-engine` owns the first runner because workflow is the first
|
||||
module that coordinates cross-module process actions.
|
||||
|
||||
Domain modules own their own action providers. For example, templates own
|
||||
|
||||
+11
-1
@@ -1,4 +1,4 @@
|
||||
<!-- codex-wiki-sync:49ff782570525583964b18b8 -->
|
||||
<!-- codex-wiki-sync:29e7dcb0b77921f8e3beee69 -->
|
||||
|
||||
> Mirrored from `/mnt/DATA/git/govoplan-core/docs/CODEX_WORKFLOW.md`.
|
||||
> Origin: `repository`.
|
||||
@@ -56,6 +56,15 @@ The broad writable root reduces approval churn. The explicit project trust entri
|
||||
|
||||
Each active repository has an `AGENTS.md` file. These files define ownership, module boundaries, and focused commands for Codex. Keep durable project conventions there instead of repeating them in every prompt.
|
||||
|
||||
Documentation is part of the completion criteria for every behavior change. The
|
||||
owning module must update its manifest-driven `DocumentationTopic` contributions
|
||||
for affected user and administrator workflows, settings, permissions,
|
||||
limitations, and operational consequences. Feature documentation remains in the
|
||||
feature module; the optional `govoplan-docs` module projects those contributions
|
||||
without importing feature internals. Every module manifest must retain a static
|
||||
user and administrator baseline even when runtime providers add configured-state
|
||||
details.
|
||||
|
||||
Use `~/.codex/config.toml` for personal defaults, auth/runtime settings, writable roots, and trust decisions. Avoid checking in absolute-path writable roots or model preferences unless they are intentionally team-wide.
|
||||
|
||||
Use Gitea issues as the canonical backlog and state log. See `docs/GITEA_ISSUES.md` for label setup, TODO import, and Codex issue update commands. Durable docs should describe stable behavior; changing work state belongs on the issue.
|
||||
@@ -88,5 +97,6 @@ PATH=/mnt/DATA/git/govoplan-core/webui/node_modules/.bin:/home/zemion/.nvm/versi
|
||||
- Avoid broad recursive scans and full builds unless the change warrants them.
|
||||
- Keep generated build/test folders ignored.
|
||||
- Keep optional module behavior behind core registry/capability/module metadata boundaries.
|
||||
- Run `tools/checks/check-manifest-shapes.py` after module behavior or manifest changes so user/admin documentation coverage remains complete.
|
||||
- Create or update Gitea issues for TODOs, follow-ups, blockers, and feature requests instead of keeping local backlog files.
|
||||
- Do not start persistent dev servers unless the user asks.
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
<!-- codex-wiki-sync:7044620091f59357c2d54606 -->
|
||||
|
||||
> Mirrored from `/mnt/DATA/git/govoplan-core/docs/COMPATIBILITY_INVENTORY.md`.
|
||||
> Origin: `repository`.
|
||||
> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
|
||||
|
||||
---
|
||||
# GovOPlaN Compatibility Inventory
|
||||
|
||||
This inventory classifies compatibility paths covered by
|
||||
`COMPATIBILITY_POLICY.md`. It is intentionally limited to behavior that changes
|
||||
accepted data, imports, permissions, or migration state. Operational fallbacks
|
||||
such as Redis degradation and language fallback are not compatibility paths.
|
||||
|
||||
## Database Bridges
|
||||
|
||||
| Path | Purpose | Retention | Removal |
|
||||
| --- | --- | --- | --- |
|
||||
| `govoplan_core.db.migrations.reconcile_legacy_create_all_schema` | Reconciles databases created before Alembic ownership was recorded. | At least one major release after runtime aliases are removed. | Review after `1.0`; keep release-baseline tests. |
|
||||
| Migration table/column aliases in `govoplan_core.db.migrations` | Detect and reconcile pre-split table ownership and migration tracks. | All tagged `0.1.x` upgrade origins plus one major release cycle. | Remove only after the corresponding baseline leaves support. |
|
||||
| Access and module migration backfills for legacy permission names | Converts persisted role assignments without dropping authority. | Same as the database upgrade origin that contains the old role. | Keep migrations immutable; remove only runtime expansion at `0.2`. |
|
||||
|
||||
## Portable-Schema Readers
|
||||
|
||||
| Path | Purpose | Retention | Removal |
|
||||
| --- | --- | --- | --- |
|
||||
| `govoplan_core.mail.config.normalize_split_transport_credentials` | Reads pre-split SMTP/IMAP credentials and emits the split representation. | Current and previous two configuration schema versions. | Version-gate once Mail writes an explicit current schema version; reject inputs older than the two-version window. |
|
||||
| `ImapServerConfig.discard_legacy_enabled` | Reads the former nested IMAP `enabled` field without writing it. | Current and previous two configuration schema versions. | Remove with the oldest accepted Mail configuration schema. |
|
||||
| `govoplan_core.core.configuration_packages` readers | Reads explicitly versioned configuration-package manifests. | Current and previous two schema versions. | Retire individual readers as their version leaves the window. |
|
||||
|
||||
## Runtime And API Aliases
|
||||
|
||||
| Path | Purpose | Retention | Removal |
|
||||
| --- | --- | --- | --- |
|
||||
| `govoplan_core.security.scope_aliases.LEGACY_SCOPE_ALIASES` | Expands pre-granular permission names. | Tagged `0.1.x` runtime/API window. | Remove at `0.2` after role backfills and migration notes are verified. |
|
||||
| `govoplan_core.security.module_permissions.LEGACY_TO_MODULE_SCOPES` | Maps pre-module-split scopes to canonical owning-module scopes. | Tagged `0.1.x` runtime/API window. | Remove at `0.2`; keep database migration evidence for one major cycle. |
|
||||
| `govoplan_core.privacy.retention` | Stable import facade delegating policy-owned behavior through a capability. | Tagged `0.1.x` import window. | Remove at `0.2` after all in-tree callers use the policy contract and release notes name the replacement. |
|
||||
| Legacy tenant aliases in API response schemas | Preserves active-tenant response fields used by `0.1.x` clients. | Tagged `0.1.x` API window. | Remove at `0.2` with response-schema migration notes. |
|
||||
| Optional fields in Poll response references | Accepts providers built against the earlier Poll contract. | Tagged `0.1.x` runtime contract window. | Remove or require a new interface version at `0.2`. |
|
||||
| Legacy single-tenant summary providers | Allows modules without the batch provider introduced in `0.1.x`. | Tagged `0.1.x` module contract window. | Remove at `0.2` after manifests advertise the batch provider contract. |
|
||||
|
||||
## Removed Paths
|
||||
|
||||
| Path | Reason | Removed |
|
||||
| --- | --- | --- |
|
||||
| `govoplan_core.core.module_installer._run_restart_command_legacy` | Private wrapper had no callers and never represented a persisted or published contract. | Current development line |
|
||||
| Retired `govoplan_core.api.admin` and pre-split core model imports | In-tree callers and module packages use their owning modules; regression tests prohibit reintroduction. | Before `0.1.10` |
|
||||
|
||||
Every new compatibility path must be added here with its classification,
|
||||
diagnostic, test owner, and planned removal release.
|
||||
@@ -0,0 +1,76 @@
|
||||
<!-- codex-wiki-sync:4889302f93db4a801173f79b -->
|
||||
|
||||
> Mirrored from `/mnt/DATA/git/govoplan-core/docs/COMPATIBILITY_POLICY.md`.
|
||||
> Origin: `repository`.
|
||||
> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
|
||||
|
||||
---
|
||||
# GovOPlaN Compatibility Policy
|
||||
|
||||
This document defines the compatibility window that release tooling, module
|
||||
owners, migration authors, import/export providers, and API maintainers must
|
||||
preserve. It is the source of truth for deciding whether compatibility code can
|
||||
be removed.
|
||||
|
||||
## Database Upgrades
|
||||
|
||||
- A released installation from every tagged `0.1.x` version is a supported
|
||||
database upgrade origin.
|
||||
- The recorded public release-baseline ledger starts at `v0.1.7`; earlier
|
||||
`0.1.x` tags predate production installations. If an earlier tagged database
|
||||
is encountered, the release must provide or document a compatibility bridge
|
||||
instead of silently treating the database as a fresh installation.
|
||||
- Released migration revision IDs and recorded release heads are immutable.
|
||||
- Each release must prove an upgrade from every still-supported recorded
|
||||
baseline, as well as a fresh installation, before its tag is published.
|
||||
- Migration-only reconciliation needed by an old database remains available for
|
||||
at least one subsequent major release cycle after the corresponding runtime
|
||||
compatibility path is removed.
|
||||
|
||||
The release-baseline format and commands are documented in
|
||||
`RELEASE_DEPENDENCIES.md`.
|
||||
|
||||
## Configuration And Export Schemas
|
||||
|
||||
- Writers emit only the current schema version.
|
||||
- Readers accept the current schema version and the previous two schema
|
||||
versions.
|
||||
- Older input is rejected with a diagnostic that identifies its version and the
|
||||
required staged upgrade or conversion path.
|
||||
- A module-owned configuration provider must version its input and output
|
||||
schema explicitly. It must not infer an old schema from missing fields once a
|
||||
versioned schema has shipped.
|
||||
- Round-trip and upgrade tests must cover all three readable versions before a
|
||||
schema change is released.
|
||||
|
||||
This window applies to configuration packages, module-owned exports, and other
|
||||
portable GovOPlaN configuration artifacts. Domain interchange standards with
|
||||
their own compatibility rules remain governed by the owning module.
|
||||
|
||||
## Runtime And API Aliases
|
||||
|
||||
- Compatibility aliases must emit an explicit deprecation diagnostic and point
|
||||
to the supported replacement.
|
||||
- New callers must use the canonical contract. In-tree callers may not add new
|
||||
uses of a deprecated alias.
|
||||
- Runtime imports, request fields, response fields, routes, and scope aliases
|
||||
carried for the `0.1.x` split line are retired at `0.2`, with migration notes.
|
||||
- An alias may be removed earlier only when it never shipped in a tag or when a
|
||||
security fix requires removal. The release notes must state the exception.
|
||||
- Database reconciliation code is not a runtime/API alias and follows the
|
||||
longer database window above.
|
||||
|
||||
## Removal Checklist
|
||||
|
||||
Compatibility code can be removed only when all of the following are true:
|
||||
|
||||
1. The path is inventoried as a database bridge, portable-schema reader, or
|
||||
runtime/API alias.
|
||||
2. Its minimum retention window has elapsed.
|
||||
3. In-tree callers and published module manifests use the replacement.
|
||||
4. Upgrade, import, or API regression tests cover the retained window.
|
||||
5. Diagnostics and migration notes identify any staged action operators must
|
||||
take.
|
||||
|
||||
If one condition is not met, version-gate the compatibility path and record its
|
||||
planned removal release instead of deleting it.
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- codex-wiki-sync:b4026b0cfd982d87eee98476 -->
|
||||
<!-- codex-wiki-sync:fc3555f220cea437775e2609 -->
|
||||
|
||||
> Mirrored from `/mnt/DATA/git/govoplan-core/docs/CONFIGURATION_PACKAGES.md`.
|
||||
> Origin: `repository`.
|
||||
@@ -55,6 +55,23 @@ interface = how configured parts connect
|
||||
data = what the operator must provide for this deployment
|
||||
```
|
||||
|
||||
## Package Classes
|
||||
|
||||
The same signed package mechanism supports several explicitly named classes:
|
||||
|
||||
| Class | Purpose |
|
||||
| --- | --- |
|
||||
| `reference` | Prove a bounded journey, degraded states, recovery, and target-environment acceptance. |
|
||||
| `product` | Provide a reusable operating capability such as governed communication, service-to-decision, procurement/contracts, or governed BI. |
|
||||
| `sector` | Specialize terminology, forms, rules, process baselines, controls, reports, and integrations for an institutional sector without forking modules. |
|
||||
| `deployment_profile` | Declare a supported infrastructure topology, operational assumptions, health gates, and recovery evidence. |
|
||||
| `integration_profile` | Declare external systems, provider bindings, source-authority modes, maturity, required health, and reconciliation behavior. |
|
||||
|
||||
Package class is metadata and validation context, not additional authority. A
|
||||
sector package does not become a module and cannot write another module's
|
||||
tables. Packages may extend other packages only through versioned fragments and
|
||||
must preserve provenance and parent constraints.
|
||||
|
||||
## Package Model
|
||||
|
||||
A configuration package should be a signed, portable manifest plus module-owned
|
||||
@@ -75,6 +92,14 @@ Required package metadata:
|
||||
- preflight checks and post-import health checks
|
||||
- migration or transformation rules for older package versions
|
||||
- provenance, export source metadata, and signature metadata
|
||||
- package class and optional parent package/version constraints
|
||||
- source-authority bindings and provider-operation expectations for every
|
||||
external integration used by the package
|
||||
|
||||
Portable configuration schemas follow `COMPATIBILITY_POLICY.md`: providers
|
||||
write only their current schema version and read that version plus the previous
|
||||
two versions. Older input must produce a version-specific staged-upgrade
|
||||
diagnostic.
|
||||
|
||||
Configuration fragments are interpreted only by the module that owns them. For
|
||||
example, workflow imports workflow definitions; forms imports form schemas;
|
||||
|
||||
@@ -0,0 +1,74 @@
|
||||
<!-- codex-wiki-sync:19ba0a5ad3b4f1f26d3549bf -->
|
||||
|
||||
> Mirrored from `/mnt/DATA/git/govoplan-core/docs/DATAGRID_SIZING_CONTRACT.md`.
|
||||
> Origin: `repository`.
|
||||
> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
|
||||
|
||||
---
|
||||
# DataGrid Sizing Contract
|
||||
|
||||
`DataGrid` turns every declared track into a deterministic pixel layout after
|
||||
its container has a measurable width. The same contract is used on initial
|
||||
layout, container resize, persisted-layout restore, and pointer resize.
|
||||
|
||||
## Column Declarations
|
||||
|
||||
- `width: number` or `Npx` is the preferred pixel width.
|
||||
- `width: N%` is a preferred share of the measured container.
|
||||
- `width: Nfr` shares residual width by fraction weight.
|
||||
- `width: minmax(Npx, preferred)` combines a hard lower bound with any
|
||||
supported preferred width.
|
||||
- An omitted width and the legacy `fill` flag are one-fraction flexible tracks.
|
||||
- `minWidth` is a hard floor. Header sort, filter, and resize controls may raise
|
||||
the effective accessible floor.
|
||||
- `maxWidth` bounds direct user growth and free/constrained compensation. In a
|
||||
cover layout it is a preferred maximum: passive tracks may exceed it when
|
||||
that is necessary to keep the table flush with its container.
|
||||
|
||||
## Layout Modes
|
||||
|
||||
| `initialFit` | `resizeBehavior` | Initial layout | Pointer resize |
|
||||
| --- | --- | --- | --- |
|
||||
| `container` | `cover` | Real columns fill the container. Hard-minimum excess scrolls horizontally. | Growth may create horizontal overflow. Shrink first consumes overflow, then grows resizable columns to the right; it stops before underflow. |
|
||||
| `content` | `cover` | After measurement, the same cover invariant applies. | Same as cover above. |
|
||||
| `container` | `constrained` | Real columns fill the container. | Peer compensation respects every hard min/max and stops the active resize when capacity is exhausted. |
|
||||
| `content` | `free` | Declared content widths are retained. | Only the active column changes, so underflow or horizontal overflow is allowed. |
|
||||
| `container` | `free` | The initial layout fills the container. | Later user resizing is free. A right-sticky column promotes this mode to cover so its edge remains stable. |
|
||||
|
||||
Sticky columns do not absorb ordinary cover residuals and are not resize
|
||||
compensation targets. A last resizable column may grow into overflow. It may
|
||||
shrink only by the current overflow, because shrinking farther would require a
|
||||
blank filler track. Dragging farther past that stop does not bank width changes:
|
||||
the column remains stopped until the pointer crosses the same boundary again.
|
||||
|
||||
## Persistence
|
||||
|
||||
Only the pixel layout resulting from an explicit user resize is persisted.
|
||||
Persisted widths are keyed by a signature containing column IDs, declared
|
||||
widths and bounds, resize affordances, sticky placement, initial fit, and resize
|
||||
behavior. A changed signature discards the old override and recomputes the
|
||||
declared layout.
|
||||
|
||||
Container reconciliation is suspended while a pointer drag is active. On
|
||||
release, the already-rendered pixel layout becomes the persisted preference.
|
||||
Reconciliation may grow it to prevent underflow, but never shrinks intentional
|
||||
user overflow, so there is no drag-end snap.
|
||||
|
||||
## Regression Matrix
|
||||
|
||||
`webui/tests/data-grid-sizing.test.ts` covers:
|
||||
|
||||
- pixel, percentage, fraction, `minmax`, omitted, and legacy-fill tracks;
|
||||
- preferred max exhaustion without a synthetic filler column;
|
||||
- hard-minimum horizontal overflow;
|
||||
- fixed-only cover grids;
|
||||
- persisted overrides under growth and viewport pressure;
|
||||
- stale layout signatures;
|
||||
- first and middle-column right-side compensation;
|
||||
- last-resizable-column overflow, underflow stop, and reverse-pointer boundary;
|
||||
- free, cover, and constrained resizing;
|
||||
- cover-expanded tracks that already exceed preferred maxima; and
|
||||
- preservation of the pointer layout across the commit fit.
|
||||
|
||||
`webui/tests/data-grid-actions.test.tsx` also verifies the rendered fixed-cover
|
||||
shape and guards against reintroducing a synthetic buffer cell.
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- codex-wiki-sync:78a91e9d8d433572c8dfc9e8 -->
|
||||
<!-- codex-wiki-sync:6d9c69d4008b7843efa050fd -->
|
||||
|
||||
> Mirrored from `/mnt/DATA/git/govoplan-core/docs/DEPLOYMENT_OPERATOR_GUIDE.md`.
|
||||
> Origin: `repository`.
|
||||
@@ -164,13 +164,15 @@ release evidence.
|
||||
| --- | --- | --- |
|
||||
| `REDIS_URL` | `redis://redis:6379/0` | Celery broker/result backend when async workers are enabled. |
|
||||
| `CELERY_ENABLED` | `false` | Local/dev can send synchronously. Production campaign delivery should run workers and set this to `true`. |
|
||||
| `CELERY_QUEUES` | `send_email,append_sent,notifications,calendar,default` | Queue list expected by worker/process manager definitions. The Calendar queue drains durable external-calendar operations. |
|
||||
| `CELERY_QUEUES` | `send_email,append_sent,notifications,mail,calendar,dataflow,workflow,postbox,events,idm,default` | Queue list expected by worker/process manager definitions. Keep this aligned with every enabled module task route; Ops reports missing worker queue consumers. |
|
||||
| `PLATFORM_EVENT_OUTBOX_MAX_ATTEMPTS` | `8` | Failed durable consumer deliveries are quarantined after this many attempts. |
|
||||
| `PLATFORM_EVENT_OUTBOX_TERMINAL_RETENTION_DAYS` | `90` | Successful event envelopes older than this are removed by the daily retention task. Quarantined evidence is retained. |
|
||||
|
||||
Worker command:
|
||||
|
||||
```bash
|
||||
python -m celery -A govoplan_core.celery_app:celery worker \
|
||||
--queues send_email,append_sent,notifications,calendar,default \
|
||||
--queues send_email,append_sent,notifications,mail,calendar,dataflow,workflow,postbox,events,idm,default \
|
||||
--loglevel INFO
|
||||
```
|
||||
|
||||
@@ -194,6 +196,11 @@ python -m celery -A govoplan_core.celery_app:celery beat --loglevel INFO
|
||||
| `FILE_STORAGE_S3_ACCESS_KEY_ID` | empty | Secret; inject through deployment environment. |
|
||||
| `FILE_STORAGE_S3_SECRET_ACCESS_KEY` | empty | Secret; inject through deployment environment. |
|
||||
| `FILE_STORAGE_S3_BUCKET` | `files` | Managed-file object bucket. |
|
||||
| `FILE_STORAGE_S3_DEPLOYMENT_MANAGED` | `false` | Reserved for the installer-owned `http://garage:3900` service. It does not authorize arbitrary internal or external S3 endpoints. |
|
||||
| `FILE_ARCHIVE_MAX_ENTRIES` | `10000` | Maximum declared entries accepted during archive preview and confirmation. |
|
||||
| `FILE_ARCHIVE_MAX_EXPANDED_BYTES` | `2147483648` | Maximum actual expanded bytes across selected archive content. |
|
||||
| `FILE_ARCHIVE_MAX_EXPANSION_RATIO` | `100` | Maximum expanded-to-compressed archive ratio. |
|
||||
| `FILE_ARCHIVE_PREVIEW_TTL_SECONDS` | `1800` | Lifetime of the sealed actor/archive/destination-bound preview token. |
|
||||
|
||||
Legacy `S3_*` settings remain for older storage paths but new deployments should
|
||||
prefer `FILE_STORAGE_*`.
|
||||
@@ -343,7 +350,7 @@ the checked in `.env.example`. It runs:
|
||||
- explicit `ENABLED_MODULES`
|
||||
- explicit migrations and `--with-dev-data` bootstrap
|
||||
- API via the module-aware devserver
|
||||
- a Celery worker for `send_email,append_sent,notifications,calendar,default`
|
||||
- a Celery worker for `send_email,append_sent,notifications,mail,calendar,dataflow,workflow,postbox,events,idm,default`
|
||||
- WebUI through the Vite dev server
|
||||
- durable local files under `runtime/production-like/files`
|
||||
|
||||
@@ -462,7 +469,9 @@ Run the rollback drill before relying on installer automation in a new
|
||||
environment:
|
||||
|
||||
```bash
|
||||
/mnt/DATA/git/govoplan/tools/checks/module-installer-rollback-drill.py --format json
|
||||
/mnt/DATA/git/govoplan/tools/checks/module-installer-rollback-drill.py \
|
||||
--format json \
|
||||
--evidence-path runtime/module-installer/restore-drill-evidence.json
|
||||
```
|
||||
|
||||
The drill uses temporary SQLite databases and simulated package commands. It
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- codex-wiki-sync:306bfae7e452130258317a3b -->
|
||||
<!-- codex-wiki-sync:62abc93ccd2229a03bac5f4a -->
|
||||
|
||||
> Mirrored from `/mnt/DATA/git/govoplan-core/docs/DOCUMENTATION_MAP.md`.
|
||||
> Origin: `repository`.
|
||||
@@ -16,11 +16,13 @@ operator, and roadmap pages.
|
||||
| Topic | Canonical document | Notes |
|
||||
| --- | --- | --- |
|
||||
| Module architecture and kernel contracts | `MODULE_ARCHITECTURE.md` | Stable module contracts, API efficiency contracts, durable boundary decisions, lifecycle, and WebUI contribution rules. |
|
||||
| Compatibility policy | `COMPATIBILITY_POLICY.md` | Supported database upgrade origins, portable-schema read/write windows, runtime/API alias retirement, and compatibility-code removal criteria. |
|
||||
| RBAC and resource access | `ACCESS_RBAC_MODEL.md` | Current permission, role, API-key, and resource-access model. |
|
||||
| Governance hierarchy | `GOVERNANCE_MODEL.md` | System, tenant, user/group, campaign policy inheritance and admin UI structure. |
|
||||
| Policy decision DTOs and provenance | `POLICY_CONTRACTS.md` | Shared explain/provenance shape; module-specific policy docs should link here. |
|
||||
| Events and audit trace context | `EVENTS_AND_AUDIT.md` | Event dispatch semantics and audit payload conventions. |
|
||||
| Action/effect automation layer | `ACTION_EFFECT_AUTOMATION_LAYER.md` | Action/effect contracts, consequence preview, runner semantics, and module boundary for automation. |
|
||||
| External references and integration maturity | `EXTERNAL_REFERENCES_AND_INTEGRATION_MATURITY.md` | Stable external identity and cumulative connector maturity; configured source authority is defined by the meta target architecture. |
|
||||
| Postbox E2EE target architecture | `POSTBOX_E2EE_ARCHITECTURE.md` | Strategic encrypted postbox/mailbox model, key ownership, role mailbox semantics, and retraction limits. |
|
||||
|
||||
## Release And Operations
|
||||
@@ -32,12 +34,14 @@ operator, and roadmap pages.
|
||||
| Release dependencies and catalogs | `RELEASE_DEPENDENCIES.md` | Release package refs, migration baselines, release lockfiles, catalog trust/licensing, catalog publishing, and release checklist. |
|
||||
| Dependency vulnerability audits | `DEPENDENCY_AUDITS.md` | Local and CI audit commands plus dated audit result notes. |
|
||||
| Remote WebUI bundle design | `REMOTE_WEBUI_BUNDLES.md` | Experimental controlled-deployment design; normal releases still use package builds. |
|
||||
| WebUI loading and bundle budgets | `WEBUI_BUNDLE_BUDGETS.md` | Installed-module lazy boundaries, enforced initial/async budgets, and baseline measurements. |
|
||||
|
||||
## Product And Module Planning
|
||||
|
||||
| Topic | Canonical document | Notes |
|
||||
| --- | --- | --- |
|
||||
| Product roadmap and module routing | `GOVOPLAN_MASTER_ROADMAP.md` | Product-level sequencing, implementation gates, issue routing, and missing-module decisions. |
|
||||
| Institutional governance target | `govoplan/docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md` | Cross-product semantic layers, source-authority modes, candidate Mandates/Services/Parties/Decisions boundaries, and migration sequence. |
|
||||
| UI/UX decisions | `UI_UX_DECISION_LEDGER.md` | Binding guided-UI decisions, open decisions, impact index, and review checklist. |
|
||||
| Interface ethics and design doctrine | `INTERFACE_ETHICS_AND_DESIGN_DOCTRINE.md` | Product-level doctrine for context, decision, consequence, contestability, responsibility, and traceability. |
|
||||
| Public-sector integration posture | `PUBLIC_SECTOR_INTEGRATION_STRATEGY.md` | Strategy index; executable target inventory lives in `govoplan-connectors`. |
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- codex-wiki-sync:ddf6e1ff409f918c09d663b8 -->
|
||||
<!-- codex-wiki-sync:55fe4a1951ed40ed8fb5c618 -->
|
||||
|
||||
> Mirrored from `/mnt/DATA/git/govoplan-core/docs/EXTERNAL_REFERENCES_AND_INTEGRATION_MATURITY.md`.
|
||||
> Origin: `repository`.
|
||||
@@ -42,6 +42,26 @@ Connectors must declare and document the maturity they actually implement.
|
||||
handling, deletion semantics, and observable failures. A link-only connector
|
||||
must not imply that GovOPlaN holds an authoritative copy.
|
||||
|
||||
## Source Authority Is A Separate Dimension
|
||||
|
||||
Integration maturity states what an adapter is capable of doing. It does not
|
||||
decide which system owns truth for a configured object or field group. A
|
||||
binding separately selects one of the source-authority modes defined by the
|
||||
[institutional governance target architecture](../../govoplan/docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md):
|
||||
|
||||
- `native_authoritative`
|
||||
- `external_authoritative`
|
||||
- `external_mirror`
|
||||
- `governed_sync`
|
||||
- `governance_overlay`
|
||||
- `linked_reference`
|
||||
|
||||
A connector can therefore support `synchronize` while a tenant deliberately
|
||||
uses it only as an external mirror. Conversely, a native GovOPlaN object may
|
||||
retain link-only references to several external systems. Authority may be
|
||||
narrowed by tenant, organization, service, object type, object, field group, or
|
||||
process step and must be visible in provenance and configuration preflight.
|
||||
|
||||
## Domain Ownership
|
||||
|
||||
- Domain modules own native GovOPlaN objects and their authorization.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- codex-wiki-sync:dd6a1740f0b457d83b5b69c5 -->
|
||||
<!-- codex-wiki-sync:95c799e8e7cde5b3f81ddc45 -->
|
||||
|
||||
> Mirrored from `/mnt/DATA/git/govoplan-core/docs/GOVOPLAN_MASTER_ROADMAP.md`.
|
||||
> Origin: `repository`.
|
||||
@@ -23,6 +23,9 @@ service and operating configurations, connected outcome stories, and
|
||||
capability horizons. The selected five-stage delivery sequence and its gates
|
||||
are in the meta repository's
|
||||
[Reference Journey Program](https://git.add-ideas.de/GovOPlaN/govoplan/src/branch/main/docs/REFERENCE_JOURNEY_PROGRAM.md).
|
||||
The semantic target, source-authority modes, and reconciliation with the
|
||||
implemented platform are in the meta repository's
|
||||
[Institutional Governance Target Architecture](https://git.add-ideas.de/GovOPlaN/govoplan/src/branch/main/docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md).
|
||||
Those product documents are canonical; this Core roadmap remains their
|
||||
technical sequencing and module-routing companion.
|
||||
|
||||
@@ -71,8 +74,9 @@ verify or reverse those effects.
|
||||
`INTERFACE_ETHICS_AND_DESIGN_DOCTRINE.md`.
|
||||
- Automation must use governed action/effect contracts, not hidden side
|
||||
effects. The first automation layer is defined in
|
||||
`ACTION_EFFECT_AUTOMATION_LAYER.md` and should start in `govoplan-workflow`
|
||||
unless a separate automation module becomes justified.
|
||||
`ACTION_EFFECT_AUTOMATION_LAYER.md`; its first runner lives in
|
||||
`govoplan-workflow-engine`. Create a separate automation module only if the
|
||||
scheduler/action runtime outgrows workflow coordination.
|
||||
- Encrypted postboxes are a strategic target. Early postbox, access, and
|
||||
identity-trust contracts should stay compatible with the E2EE architecture in
|
||||
`POSTBOX_E2EE_ARCHITECTURE.md`.
|
||||
@@ -151,8 +155,9 @@ pattern exists.
|
||||
| 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` |
|
||||
| Action/effect catalogue and automation runner | first `govoplan-workflow`; possible future `govoplan-automation` if it outgrows workflow |
|
||||
| Workflow runtime, transitions, and automation | `govoplan-workflow-engine` |
|
||||
| Workflow definition editing | optional `govoplan-workflow` |
|
||||
| Action/effect catalogue and automation runner | first `govoplan-workflow-engine`; possible future `govoplan-automation` only if it outgrows workflow |
|
||||
| Internal work queues and tasks | `govoplan-tasks` |
|
||||
| Appointment proposals and booking | `govoplan-appointments`, `govoplan-calendar` |
|
||||
| Postbox, email, and notifications | `govoplan-postbox`, `govoplan-mail`, `govoplan-notifications` |
|
||||
@@ -160,13 +165,18 @@ pattern exists.
|
||||
| Organizational structures, units, and functions | `govoplan-organizations` |
|
||||
| Identity-to-function assignments and directory synchronization | `govoplan-idm` |
|
||||
| Identity trust, device keys, and encrypted postbox key contracts | `govoplan-identity-trust`, `govoplan-access`, `govoplan-postbox` |
|
||||
| Service directory/catalog | `govoplan-portal` |
|
||||
| Service directory presentation | `govoplan-portal` |
|
||||
| Versioned institutional service definition | shared service contract first; candidate `govoplan-services` after reuse proof |
|
||||
| Mandate, jurisdiction, and institutional authority | shared mandate contract first; candidate `govoplan-mandates` after reuse proof |
|
||||
| Procedure-local parties and representation | shared party contract first; candidate `govoplan-parties` after reuse proof |
|
||||
| Formal institutional decisions | shared decision contract first; candidate `govoplan-decisions` after reuse proof |
|
||||
| Permit/document generation | `govoplan-templates`, `govoplan-dms` |
|
||||
| Payment capture and accounting handoff | `govoplan-payments`, `govoplan-ledger` |
|
||||
| Authentication projection, roles, permissions, acting context | `govoplan-access` |
|
||||
| Tenants, policy, and audit | `govoplan-tenancy`, `govoplan-policy`, `govoplan-audit` |
|
||||
| External software integration | `govoplan-connectors` |
|
||||
| Recurring extraction and transformation | possible future `govoplan-datasources`, possible future `govoplan-dataflow` |
|
||||
| Governed data/register catalogue | `govoplan-datasources` |
|
||||
| Recurring extraction and transformation | `govoplan-dataflow` over Datasources and Connectors contracts |
|
||||
| Reports, BI, and management visibility | `govoplan-reporting` |
|
||||
|
||||
## Configuration And Safety Target
|
||||
@@ -211,8 +221,9 @@ an editor applies a high-impact configuration change.
|
||||
|
||||
## Reference Journeys
|
||||
|
||||
The active sequence is selected. Workflow remains deliberately deferred and is
|
||||
not a dependency of these journeys.
|
||||
The active sequence is selected. Workflow Engine and its optional editor are
|
||||
now available foundations, but a reference journey does not depend on Workflow
|
||||
unless its package explicitly composes and proves it.
|
||||
|
||||
### Journey 1: Campaign Demonstration Composition
|
||||
|
||||
@@ -263,9 +274,11 @@ The result must preserve official-key mappings, organizational and reporting
|
||||
date semantics, quality findings, quarantine/replay, transparent calculation,
|
||||
and reproducible promotion between development, test, and production.
|
||||
|
||||
Reporting consumes the product. Create `govoplan-datasources` or
|
||||
`govoplan-dataflow` only after the concrete path proves repeated ownership that
|
||||
does not belong to connectors, Reporting, or the producing domain module.
|
||||
Reporting consumes the product. Datasources owns the governed source and
|
||||
materialization lifecycle; Dataflow owns typed transformation/run lineage;
|
||||
Connectors owns external transport. The concrete path must now prove those
|
||||
implemented boundaries and expose any missing contracts instead of recreating
|
||||
them inside Reporting or a producing domain module.
|
||||
|
||||
### Journey 5: Collaborative Document Lifecycle
|
||||
|
||||
@@ -343,8 +356,9 @@ Create or refine in this order:
|
||||
access.
|
||||
4. `govoplan-cases`: case record, status, assignments, deadlines, and case
|
||||
evidence.
|
||||
5. `govoplan-workflow`: state machine, transitions, commands, and module
|
||||
handoff.
|
||||
5. `govoplan-workflow-engine`: state machine, transitions, commands, module
|
||||
handoff, and resumable execution; optional `govoplan-workflow` supplies the
|
||||
editor.
|
||||
6. `govoplan-tasks`: work queues, assignments, due dates, and follow-ups.
|
||||
7. `govoplan-templates`: permit/decision document generation.
|
||||
8. `govoplan-postbox`, `govoplan-mail`, `govoplan-notifications`: applicant and
|
||||
@@ -533,31 +547,34 @@ Refine:
|
||||
dashboard data.
|
||||
- `govoplan-search`: permissioned cross-module discovery.
|
||||
|
||||
Create only when justified:
|
||||
Refine the existing owners:
|
||||
|
||||
- `govoplan-datasources`: source catalog, connection profiles, schema discovery,
|
||||
freshness, provenance.
|
||||
- `govoplan-dataflow`: transformations, validation, lineage, scheduled runs,
|
||||
publication outputs.
|
||||
- `govoplan-projects`: only if OpenProject connectors and existing cases/tasks
|
||||
cannot cover the required semantics.
|
||||
- `govoplan-datasources`: governed data/register catalog, live/cached/static
|
||||
sources, staging, immutable materializations, freshness, quality, legal and
|
||||
organizational context, and provenance. Connector profiles and credentials
|
||||
remain in Connectors.
|
||||
- `govoplan-dataflow`: typed transformations, validation, lineage, manual,
|
||||
scheduled and event-triggered runs, reusable definitions, and publication
|
||||
outputs.
|
||||
- `govoplan-projects`: native projects, portfolios, milestones, goals,
|
||||
dependencies, capacity, outcomes, and external OpenProject references;
|
||||
Connectors owns OpenProject transport and synchronization.
|
||||
|
||||
Reference journey: monthly data extraction, transformation, validation, approval,
|
||||
publication, and reporting.
|
||||
|
||||
Recurring extraction/transformation should start as a configuration package
|
||||
across connectors, files, workflow, reporting, and templates. The package should
|
||||
register sources, declare schemas, define mapping/validation versions, schedule
|
||||
runs, produce previewable diffs, write governed outputs, and preserve lineage,
|
||||
hashes, operator actions, and audit evidence. Create `govoplan-datasources` or
|
||||
`govoplan-dataflow` only after this work exposes repeated contracts that do not
|
||||
belong to existing modules.
|
||||
Recurring extraction/transformation should be delivered as a configuration
|
||||
package across Connectors, Datasources, Dataflow, Workflow Engine, Reporting,
|
||||
Files, and Templates. The package should register sources, declare schemas,
|
||||
define mapping/validation versions, schedule runs, produce previewable diffs,
|
||||
write governed outputs, and preserve lineage, hashes, operator actions, and
|
||||
audit evidence.
|
||||
|
||||
Exit criteria:
|
||||
|
||||
- connector catalog exists before building many adapters
|
||||
- dataflow is created only after recurring transformation becomes product
|
||||
behavior
|
||||
- datasource and dataflow ownership remains provider-neutral and is proved by
|
||||
the recurring transformation package
|
||||
- reporting consumes governed sources with provenance
|
||||
|
||||
## Implementation Gates
|
||||
@@ -598,23 +615,25 @@ in the capability waves:
|
||||
4. Implement one data-backed Templates/Reporting path and safe HIS-style deep
|
||||
launch.
|
||||
5. Extend that concrete source into one governed university analytical data
|
||||
product before generalizing data-source or dataflow ownership.
|
||||
product and use it to harden the existing Datasources/Dataflow ownership,
|
||||
quality, lineage, and promotion contracts.
|
||||
6. Implement Files-backed DMS versions and one provider-neutral collaborative
|
||||
editing lifecycle, then connect Records handoff.
|
||||
7. Maintain already integrated Calendar/Scheduling/Poll and other foundations;
|
||||
activate another capability cluster only when the current journey needs it
|
||||
or the product roadmap explicitly reprioritizes it.
|
||||
8. Resume Workflow only by explicit product decision and constrain it with
|
||||
stable actions from one demonstrated package.
|
||||
8. Extend Workflow Engine and the optional editor only through stable actions
|
||||
and one demonstrated package at a time.
|
||||
|
||||
## Deliberate Deferrals
|
||||
|
||||
Defer these until a reference journey proves the need:
|
||||
|
||||
- full ERP replacement
|
||||
- native project management beyond connector support
|
||||
- an unbounded general-purpose dataflow platform; the bounded governed BI
|
||||
reference journey is selected
|
||||
- unsupported breadth in native project management before the Projects/OpenProject
|
||||
boundary is proved in a reference journey
|
||||
- unbounded Dataflow operators or execution engines without golden-flow,
|
||||
quality, lineage, resource-limit, and recovery evidence
|
||||
- every possible public-sector protocol adapter
|
||||
- rich LMS behavior beyond training administration
|
||||
- full qualified digital signing/trust services beyond the identity-trust and
|
||||
@@ -637,16 +656,16 @@ repositories or to explicit missing-module decisions.
|
||||
| Fully UI-managed configuration with safety controls | `govoplan-admin`, `govoplan-core`, `govoplan-policy`, `govoplan-access`, `govoplan-audit` | `GovOPlaN/govoplan-core#218` |
|
||||
| Access as a module | `govoplan-access` | `GovOPlaN/govoplan-access#7` |
|
||||
| Interface ethics and decision-consequence doctrine | `govoplan-core` plus all UI-owning modules | `GovOPlaN/govoplan-core#227` |
|
||||
| Action/effect automation layer | first `govoplan-workflow`; possible future `govoplan-automation` | `GovOPlaN/govoplan-workflow#1` |
|
||||
| Action/effect automation layer | `govoplan-workflow-engine`; possible future `govoplan-automation` only after boundary proof | `GovOPlaN/govoplan-workflow#1` |
|
||||
| E2EE role/function postbox architecture | `govoplan-postbox`, `govoplan-identity-trust`, `govoplan-access`, `govoplan-policy`, `govoplan-audit` | `GovOPlaN/govoplan-postbox#15`, `GovOPlaN/govoplan-identity-trust#1` |
|
||||
| Identity, account, function, role, right semantic model | `govoplan-access` | `GovOPlaN/govoplan-access#9` |
|
||||
| Role-based service directory/catalog | `govoplan-portal` | `GovOPlaN/govoplan-portal#1` |
|
||||
| Role-based service directory presentation | `govoplan-portal`; reusable service definition is a shared contract and candidate `govoplan-services` | `GovOPlaN/govoplan-portal#1` |
|
||||
| Unified inbox across tasks, postbox, notifications, and portal | `govoplan-core` coordination plus owning modules | `GovOPlaN/govoplan-tasks#1`, `GovOPlaN/govoplan-notifications#1` |
|
||||
| OpenProject API / project management connector | `govoplan-connectors` | `GovOPlaN/govoplan-connectors#1` |
|
||||
| Native project-management module decision | connector-first through `govoplan-connectors`; no native project module yet | `GovOPlaN/govoplan-core#196`, `GovOPlaN/govoplan-connectors#1` |
|
||||
| Datasources for databases, CSV, files, APIs | no repository yet; start with connectors/files/reporting and create `govoplan-datasources` only after the first package proves shared source-catalog ownership | `GovOPlaN/govoplan-core#197` |
|
||||
| Dataflow for pipelines, BI, publication | no repository yet; start with workflow/reporting/connectors and create `govoplan-dataflow` only after repeated pipeline/lineage contracts emerge | `GovOPlaN/govoplan-core#198` |
|
||||
| Monthly datasource and transformation workflows | first as configuration package across connectors, files, workflow, reporting, and templates | `GovOPlaN/govoplan-core#216` |
|
||||
| Native project-management module | `govoplan-projects`; OpenProject transport remains connector-owned | `GovOPlaN/govoplan-projects#1`, `GovOPlaN/govoplan-connectors#12` |
|
||||
| Datasources for databases, CSV, files, APIs | `govoplan-datasources`, with external protocol and credential ownership in Connectors | `GovOPlaN/govoplan-datasources#1` |
|
||||
| Dataflow for pipelines, BI, publication | `govoplan-dataflow` over Datasources and module-owned providers | `GovOPlaN/govoplan-dataflow#1` |
|
||||
| Monthly datasource and transformation workflows | configuration package across Connectors, Datasources, Dataflow, Workflow Engine, Reporting, Files, and Templates | `GovOPlaN/govoplan#8`, `GovOPlaN/govoplan-dataflow#17` |
|
||||
| Templates for letters, emails, forms, reports | `govoplan-templates`, separate from reporting | `GovOPlaN/govoplan-core#190`, `GovOPlaN/govoplan-templates#1` |
|
||||
| Reporting and BI | `govoplan-reporting`, separate from templates | `GovOPlaN/govoplan-core#190`, `GovOPlaN/govoplan-reporting#1` |
|
||||
| File connectors: Nextcloud, Seafile, SMB, NFS | `govoplan-files` | `GovOPlaN/govoplan-files#15` |
|
||||
@@ -656,7 +675,7 @@ repositories or to explicit missing-module decisions.
|
||||
| Workflow module concept | `govoplan-workflow` | `GovOPlaN/govoplan-core#175` |
|
||||
| Connectors module concept | `govoplan-connectors` | `GovOPlaN/govoplan-core#176` |
|
||||
| Adrema-style address and distribution-list management | `govoplan-addresses` | `GovOPlaN/govoplan-addresses#1` |
|
||||
| Consume sources and become a governed source | `govoplan-connectors` plus possible future `govoplan-dataflow` | `GovOPlaN/govoplan-connectors#3`, `GovOPlaN/govoplan-core#198` |
|
||||
| Consume sources and become a governed source | Connectors acquires, Datasources governs/materializes, Dataflow transforms/publishes | `GovOPlaN/govoplan-connectors#3`, `GovOPlaN/govoplan-datasources#3` |
|
||||
| Governed connector configuration, dry-run, and simulation runtime | `govoplan-connectors` | `GovOPlaN/govoplan-connectors#6` |
|
||||
| Terminfindung and meeting scheduling polls | `govoplan-scheduling`; calendar primitives remain in calendar | `GovOPlaN/govoplan-core#193`, `GovOPlaN/govoplan-scheduling#1` |
|
||||
| Terminplaner and calendar primitives | `govoplan-calendar` | `GovOPlaN/govoplan-core#193`, `GovOPlaN/govoplan-calendar#1` |
|
||||
@@ -678,27 +697,23 @@ repositories or to explicit missing-module decisions.
|
||||
Boundary rationale lives in `MODULE_ARCHITECTURE.md`. Current decisions:
|
||||
|
||||
- templates and reporting are separate modules
|
||||
- RSS/source consume-publish starts in connectors; datasources/dataflow are not
|
||||
repositories yet
|
||||
- RSS/source consume-publish starts in Connectors; governed source identity and
|
||||
snapshots belong to Datasources and transformations belong to Dataflow
|
||||
- calendar, scheduling, and appointments are three separate modules
|
||||
- forms definitions and forms runtime are separate responsibilities
|
||||
- OpenDesk is an integration profile across modules, not a monolithic module
|
||||
- OpenProject is connector-first; no native projects module yet
|
||||
- OpenProject transport is connector-owned; native portfolio/project semantics
|
||||
belong to Projects
|
||||
- public-sector integration strategy stays in core; executable catalogue work
|
||||
lives in connectors
|
||||
- encrypted postbox and identity-trust are strategic contracts, not mail-module
|
||||
behavior
|
||||
- automation starts as workflow-owned action/effect execution and may split into
|
||||
a dedicated module only after the runner becomes broader than workflow
|
||||
|
||||
The following modules are intentionally not created yet:
|
||||
|
||||
- `govoplan-datasources`
|
||||
- `govoplan-dataflow`
|
||||
- `govoplan-projects`
|
||||
|
||||
Create a repository only after a concrete implementation package proves that
|
||||
existing connector, files, reporting, workflow, or task ownership is too narrow.
|
||||
- automation starts in Workflow Engine and may split into a dedicated module
|
||||
only after the runner becomes broader than workflow
|
||||
- Mandates, Services, Parties, and Decisions begin as shared semantic contracts;
|
||||
create repositories only after independent persistence, lifecycle, security,
|
||||
and multiple-consumer evidence passes the repository threshold in the
|
||||
institutional governance target architecture
|
||||
|
||||
Core keeps the strategy index in
|
||||
`PUBLIC_SECTOR_INTEGRATION_STRATEGY.md`: integration postures, default
|
||||
|
||||
+159
-4
@@ -1,4 +1,4 @@
|
||||
<!-- codex-wiki-sync:74bae5cf7f92168e54351205 -->
|
||||
<!-- codex-wiki-sync:bc439eb7b748adf80c59b3e8 -->
|
||||
|
||||
> Mirrored from `/mnt/DATA/git/govoplan-core/docs/MODULE_ARCHITECTURE.md`.
|
||||
> Origin: `repository`.
|
||||
@@ -20,6 +20,10 @@ Policy decision, source provenance, and explain-response contracts are tracked
|
||||
in [`POLICY_CONTRACTS.md`](POLICY_CONTRACTS.md).
|
||||
The experimental remote WebUI bundle loading design is tracked in
|
||||
[`REMOTE_WEBUI_BUNDLES.md`](REMOTE_WEBUI_BUNDLES.md).
|
||||
The cross-product semantic layers, source-authority modes, and candidate
|
||||
Mandates, Services, Parties, and Decisions boundaries are canonical in the
|
||||
meta repository's
|
||||
[`INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md`](../../govoplan/docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md).
|
||||
|
||||
## Layer Model
|
||||
|
||||
@@ -31,6 +35,36 @@ The experimental remote WebUI bundle loading design is tracked in
|
||||
| Business modules | Public-sector workflows | campaigns, cases, forms, approvals, appointments |
|
||||
| Connector modules | External system integration | FIT-Connect, XÖV/XTA, DMS/eAkte, ERP, IDM |
|
||||
|
||||
This table is the technical composition model. The product portfolio uses a
|
||||
more detailed institutional layer model, but it does not change dependency
|
||||
direction: Core provides contracts and composition; modules own semantics;
|
||||
packages compose modules.
|
||||
|
||||
## Institutional Semantic Boundaries
|
||||
|
||||
Cross-module references must keep these answers distinct:
|
||||
|
||||
- Organizations owns where structures, units, and functions exist.
|
||||
- Identity owns who a subject is; Access owns accounts, roles, permissions,
|
||||
and authorization decisions; IDM owns effective function assignments.
|
||||
- A Mandates capability will answer why a unit or function is competent for a
|
||||
task, jurisdiction, subject, or period. It must not become another RBAC
|
||||
system.
|
||||
- A Services capability will own versioned institutional service definitions;
|
||||
Portal presents and starts them.
|
||||
- A Parties capability will own procedure-local participant roles,
|
||||
representation, and delivery authority; it must reference rather than copy
|
||||
Identity, Organizations, and Addresses subjects.
|
||||
- A Decisions capability will own formal institutional outcomes and their
|
||||
authority, facts, rules, reasoning, effects, correction, and review.
|
||||
Approvals owns review gates, Committee owns deliberation/votes, and Workflow
|
||||
Engine owns coordination.
|
||||
|
||||
Start each missing concept as a versioned DTO/provider contract used by a
|
||||
bounded journey. A repository is justified only when the concept gains
|
||||
independent persistence, lifecycle, security/operations behavior, release
|
||||
reason, and reuse. Core must not store these domain objects.
|
||||
|
||||
## Kernel Responsibilities
|
||||
|
||||
The kernel target owns:
|
||||
@@ -81,6 +115,10 @@ The compatibility/deprecation plan for the current split line is:
|
||||
- reject new cross-module imports that bypass manifests, capabilities, events,
|
||||
or public module APIs
|
||||
|
||||
The retention windows and removal checklist for database bridges,
|
||||
configuration/export schemas, and runtime/API aliases are defined in
|
||||
`COMPATIBILITY_POLICY.md`.
|
||||
|
||||
## Stable Kernel Contracts
|
||||
|
||||
The following contracts are the baseline API that modules can rely on:
|
||||
@@ -94,20 +132,55 @@ The following contracts are the baseline API that modules can rely on:
|
||||
- capability factory contract
|
||||
- access DTO/protocol contracts in `govoplan_core.core.access`
|
||||
- resource ACL provider contract
|
||||
- tenant summary provider contract
|
||||
- bounded reference-option search provider contract
|
||||
- single-tenant and optional batched tenant summary provider contracts
|
||||
- tenant delete-veto provider contract
|
||||
- WebUI module contribution contract
|
||||
- navigation metadata contract
|
||||
- command/event envelope contract
|
||||
- policy decision and source provenance contract in `govoplan_core.core.policy`
|
||||
- external object reference and integration-maturity contract in
|
||||
`govoplan_core.core.external_references`
|
||||
- action/effect preview and execution contract in
|
||||
`govoplan_core.core.automation`
|
||||
- workflow definition contribution and runtime-worker contracts
|
||||
|
||||
Changes to these contracts must be versioned or accompanied by compatibility shims.
|
||||
|
||||
Tenant list pages prefer `tenant_summary_batch_providers`. A batch provider
|
||||
receives the unique tenant IDs on the current page and returns count mappings
|
||||
keyed by tenant ID. Missing tenant keys mean that the provider has no counts for
|
||||
that tenant; provider errors remain visible. Modules that expose only the
|
||||
single-tenant contract remain compatible through a per-tenant fallback.
|
||||
Destructive tenant lifecycle planning deliberately continues to use the
|
||||
single-tenant path so it invokes every registered provider for the target
|
||||
tenant, independent of ordinary list-page projections.
|
||||
|
||||
This list is the Milestone A kernel-contract freeze baseline. New module work
|
||||
may extend the kernel by adding explicit contracts, but existing contracts must
|
||||
remain source-compatible through the 0.1.x split line unless a migration shim
|
||||
and deprecation note are provided.
|
||||
|
||||
### Architecture Metadata Target
|
||||
|
||||
`ModuleManifest` currently describes executable composition. It does not yet
|
||||
declare the complete product-portfolio meaning of a module. A backward-
|
||||
compatible manifest extension should add validated architecture metadata for:
|
||||
|
||||
- module kind and institutional architecture layer;
|
||||
- evidence-backed maturity claim (`concept`, `scaffold`, `vertical_slice`,
|
||||
`reference_ready`, `supported`, or `lts`);
|
||||
- owned and explicitly non-owned concepts;
|
||||
- supported source-authority modes;
|
||||
- reference packages, tested providers, and known limits;
|
||||
- migration, upgrade, recovery, security, operations, and documentation
|
||||
evidence references.
|
||||
|
||||
Core should validate shape and project it through platform metadata. The meta
|
||||
repository and release tooling should verify evidence and cross-repository
|
||||
consistency. Docs and Ops may display the result. A module cannot make itself
|
||||
supported solely by changing its maturity string.
|
||||
|
||||
Known access-related capability names are defined in
|
||||
`govoplan_core.core.access`, including:
|
||||
|
||||
@@ -141,6 +214,16 @@ Other stable runtime capabilities currently include:
|
||||
- `calendar.outbox` and `calendar.scheduling`
|
||||
- `poll.scheduling`
|
||||
- `notifications.dispatch`
|
||||
- `workflow.definitionContributions` and `workflow.runtimeWorker`
|
||||
|
||||
Modules contribute reusable process baselines through
|
||||
`ModuleManifest.workflow_definitions`. Each contribution pins its origin module
|
||||
and version, stable key, schema and content hash, native graph/BPMN content,
|
||||
governance ceilings, execution mode, and required capabilities/interfaces.
|
||||
`govoplan-workflow-engine` reconciles these declarations idempotently. A module
|
||||
upgrade appends a baseline revision without replacing the active revision or
|
||||
mutating a local override; the optional `govoplan-workflow` package supplies
|
||||
the comparison, derivation, and reset UI.
|
||||
|
||||
### Named Interface Contracts
|
||||
|
||||
@@ -163,6 +246,24 @@ intended for SemVer major-version lines. Missing optional interfaces are
|
||||
allowed, but an installed provider with an incompatible version blocks
|
||||
activation because the integration would otherwise bind to an unsafe API.
|
||||
|
||||
### Source Authority And Provider Operations
|
||||
|
||||
Integration maturity and configured authority are independent. The existing
|
||||
external-reference maturity ladder describes whether an adapter can discover,
|
||||
link, search, read, publish, synchronize, migrate, or replace. A binding must
|
||||
also state whether GovOPlaN is native authoritative, the external system is
|
||||
authoritative, GovOPlaN keeps a mirror, both sides use governed sync, GovOPlaN
|
||||
adds only a governance overlay, or the object is link-only.
|
||||
|
||||
A future provider declaration should compose existing contracts rather than
|
||||
replace them. It will describe owned object/field groups, authority modes,
|
||||
operations, revisions, freshness, health, limits, idempotency, conflicts,
|
||||
outcome-unknown handling, evidence, correction/compensation, reconciliation,
|
||||
outage behavior, classification, purpose, retention, and secret requirements.
|
||||
Core owns the typed declaration and validation. Connectors and domain modules
|
||||
own the actual protocol and domain behavior; configuration packages select the
|
||||
effective mode; Docs and Ops explain the result.
|
||||
|
||||
Current named interfaces, generated from the source manifests by the workspace
|
||||
contract checks, are:
|
||||
|
||||
@@ -270,6 +371,23 @@ unsafe methods.
|
||||
This avoids retransmitting unchanged snapshots. It does not identify which row
|
||||
changed inside a collection.
|
||||
|
||||
### Mutation Preconditions
|
||||
|
||||
Weak response ETags are cache validators only. Mutable aggregates expose a
|
||||
separate positive, monotonic revision and an opaque strong ETag generated by
|
||||
`govoplan_core.core.concurrency.strong_resource_etag`. HTTP mutations send that
|
||||
strong ETag in `If-Match`; capability and worker calls carry the equivalent
|
||||
typed `expected_revision`.
|
||||
|
||||
Core's compare-and-set primitive advances the revision in the same transaction
|
||||
as the domain mutation. A missing HTTP precondition is `428 Precondition
|
||||
Required`, a stale HTTP precondition is `412 Precondition Failed`, and a
|
||||
domain/reconciliation conflict is `409 Conflict`. Conflict responses contain
|
||||
bounded resource and revision metadata rather than the complete current
|
||||
object. Modules may opt into the conservative three-way merge helper, but must
|
||||
declare protected workflow, delivery, ownership, lock, evidence, signature,
|
||||
and cryptographic paths that can never be merged automatically.
|
||||
|
||||
### Delta Collections
|
||||
|
||||
Collection endpoints that can expose row-level changes should use the shared
|
||||
@@ -340,6 +458,31 @@ full snapshot with `full: true`. A first-use `seq:0` watermark remains valid
|
||||
until such a floor exists, even if unrelated collections have advanced the
|
||||
global sequence.
|
||||
|
||||
### Bounded Reference Selectors
|
||||
|
||||
Cross-module selectors use the module-neutral contract in
|
||||
`govoplan_core.core.references`; consumers must not load an optional module's
|
||||
complete directory and filter it in memory.
|
||||
|
||||
- Providers receive a normalized `ReferenceSearchRequest` with `kind`,
|
||||
`tenant_id`, `query`, `selected_values`, `limit`, optional opaque `cursor`,
|
||||
and policy context.
|
||||
- Providers apply visibility and text filtering before materializing rows and
|
||||
return `ReferenceSearchPage(options, next_cursor, has_more)`.
|
||||
- A page contains at most the requested bounded search results. Already-selected
|
||||
references are retained in addition to that bound so historical values remain
|
||||
readable and removable even when they are inactive, deleted, or outside the
|
||||
current search page.
|
||||
- API consumers expose `next_cursor` and `has_more`. The current searchable
|
||||
selector requests the first bounded page for each query; later load-more UI
|
||||
can use the same cursor without changing the provider contract.
|
||||
- `access.reference_options` supplies SQL-backed account, membership, and group
|
||||
searches. When it is absent, Core degrades to the legacy Access directory or
|
||||
to principal-only/unavailable references without importing Access.
|
||||
- The shared WebUI `apiReferenceOptionProvider` resolves selected values in
|
||||
chunks of at most 200, preventing a large existing selection from turning
|
||||
into an unbounded request.
|
||||
|
||||
### Cursor/Keyset Pages
|
||||
|
||||
Offset pagination remains supported for compatibility and for first page loads,
|
||||
@@ -592,11 +735,18 @@ Uninstall remains non-destructive unless the operator explicitly requests
|
||||
|
||||
## WebUI Contract
|
||||
|
||||
A WebUI module exports a `PlatformWebModule` from its package. The object contributes local/fallback metadata and route render functions.
|
||||
A WebUI module exports a `PlatformWebModule` from its package. The object
|
||||
contributes local/fallback metadata and route render functions. The package
|
||||
must ship `src/module.ts` with the default contribution export: Core's Vite
|
||||
host imports that descriptor directly after the backend reports the module as
|
||||
enabled. This keeps package-root re-exports from pulling page implementations
|
||||
into the initial shell.
|
||||
|
||||
Example:
|
||||
|
||||
```ts
|
||||
const FilesPage = lazy(() => import("./features/files/FilesPage"));
|
||||
|
||||
export const filesModule: PlatformWebModule = {
|
||||
id: "files",
|
||||
label: "Files",
|
||||
@@ -611,6 +761,11 @@ export const filesModule: PlatformWebModule = {
|
||||
};
|
||||
```
|
||||
|
||||
Route pages and substantial panels must use stable lazy imports. Core supplies
|
||||
the shared loading and retryable error state around route rendering. The
|
||||
initial static import closure and largest asynchronous chunk are enforced by
|
||||
the budgets documented in [WEBUI_BUNDLE_BUDGETS.md](WEBUI_BUNDLE_BUDGETS.md).
|
||||
|
||||
WebUI modules receive only the core route context:
|
||||
|
||||
- `settings`
|
||||
@@ -828,7 +983,7 @@ First slice:
|
||||
- `govoplan-files` owns file-backed governed locations and uploaded/stored file
|
||||
evidence.
|
||||
- `govoplan-reporting` owns report/data views and scheduled outputs.
|
||||
- `govoplan-workflow` owns process state, approvals, scheduling of process
|
||||
- `govoplan-workflow-engine` owns process state, approvals, scheduling of process
|
||||
steps, and human review.
|
||||
|
||||
Future `govoplan-datasources` is justified when GovOPlaN needs a broad source
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- codex-wiki-sync:f18dd0dc3773c1243b81db62 -->
|
||||
<!-- codex-wiki-sync:b1a4a97e73c58ed652f42a29 -->
|
||||
|
||||
> Mirrored from `/mnt/DATA/git/govoplan-core/docs/RELEASE_DEPENDENCIES.md`.
|
||||
> Origin: `repository`.
|
||||
@@ -158,7 +158,8 @@ Current tag-only module repositories:
|
||||
- `govoplan-search`
|
||||
- `govoplan-tasks`
|
||||
- `govoplan-templates`
|
||||
- `govoplan-workflow`
|
||||
- `govoplan-workflow-engine` (headless definitions, migrations, and execution)
|
||||
- `govoplan-workflow` (optional authoring and inspection WebUI)
|
||||
- `govoplan-xoev`
|
||||
- `govoplan-xrechnung`
|
||||
- `govoplan-xta-osci`
|
||||
@@ -810,6 +811,12 @@ collecting release evidence.
|
||||
|
||||
## Migration Baselines
|
||||
|
||||
Release migration support follows `COMPATIBILITY_POLICY.md`: every tagged
|
||||
`0.1.x` installation is a supported upgrade origin, released revision IDs are
|
||||
immutable, and migration-only reconciliation remains available for at least one
|
||||
subsequent major release cycle after the matching runtime compatibility path is
|
||||
removed.
|
||||
|
||||
Development migrations may be small and numerous while a feature is moving.
|
||||
GovOPlaN keeps those detailed migrations on an explicit development track and
|
||||
publishes reviewed release shortcuts on the release track. Before a stable
|
||||
|
||||
@@ -0,0 +1,34 @@
|
||||
<!-- codex-wiki-sync:6c626d494d58f542943bea81 -->
|
||||
|
||||
> Mirrored from `/mnt/DATA/git/govoplan-core/docs/THEMING.md`.
|
||||
> Origin: `repository`.
|
||||
> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
|
||||
|
||||
---
|
||||
# WebUI Theme Contract
|
||||
|
||||
GovOPlaN supports `system`, `light`, and `dark` as persisted user preferences.
|
||||
`system` follows `prefers-color-scheme` live; it is not resolved permanently at
|
||||
save time. Core applies the resolved mode through `data-theme` on the document
|
||||
root and exposes the selected preference through `data-theme-preference`.
|
||||
|
||||
## Ownership
|
||||
|
||||
- Core owns semantic CSS tokens, native `color-scheme`, preference persistence,
|
||||
the Settings selector, and the shared shell.
|
||||
- Modules consume semantic tokens such as `--surface`, `--text`, `--line`, and
|
||||
the status token families. They may define domain aliases whose values resolve
|
||||
to shared tokens.
|
||||
- User preference selects the mode. Tenant and system policy may provide a
|
||||
future default, but must not silently replace an explicit user choice.
|
||||
- Tenant branding is a separate policy surface and must preserve contrast and
|
||||
status semantics in both modes.
|
||||
|
||||
Do not introduce fixed foreground/background colors in a module merely to make
|
||||
one mode look correct. Add or reuse a semantic Core token, then define both
|
||||
light and dark values. Bitmap content and externally authored HTML are exempt,
|
||||
but their surrounding controls must still use the shared tokens.
|
||||
|
||||
`npm run test:theme-contract` verifies the root behavior and representative
|
||||
Campaign, Calendar, Files, and Mail token consumption. The check runs before a
|
||||
production WebUI build.
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- codex-wiki-sync:9dee4e0edaaed5cd67a09546 -->
|
||||
<!-- codex-wiki-sync:fbf3b6d8ee7099df271bbc0e -->
|
||||
|
||||
> Mirrored from `/mnt/DATA/git/govoplan-core/docs/UI_UX_DECISION_LEDGER.md`.
|
||||
> Origin: `repository`.
|
||||
@@ -252,6 +252,25 @@ instead of reproducing their behavior.
|
||||
- Feedback and confirmation use `Dialog`, `ConfirmDialog`, or
|
||||
`DismissibleAlert`. They never fall back to `window.alert`.
|
||||
|
||||
### DUE-012: Rich HTML Editing Contract
|
||||
|
||||
Decision: modules that edit persisted HTML use the central
|
||||
`WysiwygEditor` exported from `@govoplan/core-webui/wysiwyg`.
|
||||
|
||||
- The dedicated subpath is intentional: the editor and its engine remain a
|
||||
shared Core contract without adding their code to module combinations that
|
||||
never consume rich-text editing.
|
||||
- Consumers provide controlled HTML and domain-specific token labels. The
|
||||
editor owns visual/source switching, formatting, links, images, safe URL
|
||||
handling, and atomic inline token rendering; it does not own template
|
||||
semantics or persistence.
|
||||
- Existing HTML outside the supported visual subset opens in source mode.
|
||||
Rendering the value must not rewrite it, and users receive an explicit
|
||||
warning before choosing the visual surface.
|
||||
- Domain placeholders remain their original serialized text. Atomic token
|
||||
presentation is an editing aid only, so backend renderers and existing
|
||||
templates do not need a new storage format.
|
||||
|
||||
#### FieldLabel Omission Register
|
||||
|
||||
Every Core field surface that intentionally does not render `FieldLabel` is
|
||||
|
||||
@@ -0,0 +1,78 @@
|
||||
<!-- codex-wiki-sync:d73ba78cdc3e5de8b4600846 -->
|
||||
|
||||
> Mirrored from `/mnt/DATA/git/govoplan-core/docs/WEBUI_BUNDLE_BUDGETS.md`.
|
||||
> Origin: `repository`.
|
||||
> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
|
||||
|
||||
---
|
||||
# WebUI Loading And Bundle Budgets
|
||||
|
||||
The Core WebUI host owns the loading boundary for installed module packages.
|
||||
Vite discovers configured packages at build time, but emits an asynchronous
|
||||
loader for each package's `src/module.ts` contribution descriptor. At runtime,
|
||||
Core imports only descriptors whose backend manifests are enabled and identify
|
||||
the matching `frontend.package_name`.
|
||||
|
||||
The direct descriptor entry is intentional. A package root may re-export pages
|
||||
for consumers; importing that barrel as module wiring can cause those pages to
|
||||
be evaluated before navigation. Route pages and substantial panels should use
|
||||
`React.lazy`, and Core wraps routes in the shared loading/error boundary.
|
||||
|
||||
## Enforced Budgets
|
||||
|
||||
`webui/bundle-budget.json` contains the production limits:
|
||||
|
||||
| Measurement | Raw limit | Gzip limit |
|
||||
| --- | ---: | ---: |
|
||||
| Initial JavaScript static import closure | 512 KiB | 160 KiB |
|
||||
| Largest individual asynchronous JavaScript chunk | 384 KiB | 110 KiB |
|
||||
|
||||
`npm run build` writes a Vite manifest, measures the entry and its recursive
|
||||
static imports, writes `dist/bundle-metrics.json`, and fails when either budget
|
||||
is exceeded. `npm run test:module-permutations` applies the same gate to every
|
||||
permutation and records the collected results in
|
||||
`dist/module-permutation-bundle-metrics.json`. In CI, each result is also added
|
||||
to the step summary.
|
||||
|
||||
Budgets are limits, not targets. A change that approaches a limit should add a
|
||||
new lazy boundary or remove unnecessary entry code instead of raising the
|
||||
limit without measurement and review.
|
||||
|
||||
## 2026-07-30 Baseline
|
||||
|
||||
Measurements use the same full-product source tree and Node 22 runtime. The
|
||||
post-change build additionally includes the Search module in the default and
|
||||
full-product sets.
|
||||
|
||||
| Initial-load measurement | Before | After | Reduction |
|
||||
| --- | ---: | ---: | ---: |
|
||||
| JavaScript assets in initial static closure | 1 | 1 | 0% |
|
||||
| Raw JavaScript | 1,387,043 B | 453,769 B | 67.3% |
|
||||
| Gzip level 9 | 364,767 B | 141,725 B | 61.1% |
|
||||
| Brotli quality 11 | 254,797 B | 106,701 B | 58.1% |
|
||||
| Parse proxy median | 18.776 ms | 7.750 ms | 58.7% |
|
||||
| Parse proxy p95 | 21.980 ms | 8.739 ms | 60.2% |
|
||||
|
||||
The parse proxy constructs a fresh `node:vm` `SourceTextModule` from the entry
|
||||
source 30 times with a randomized source marker. It is useful for a controlled
|
||||
before/after comparison, but is not enforced in CI because absolute timings
|
||||
vary across runners. Transfer budgets use deterministic raw and gzip byte
|
||||
counts.
|
||||
|
||||
The first budgeted full-product build reported:
|
||||
|
||||
- initial JavaScript: 453,769 B raw / 141,725 B gzip;
|
||||
- largest async chunk: `CampaignWorkspace`, 353,724 B raw / 98,142 B gzip.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
cd /mnt/DATA/git/govoplan-core/webui
|
||||
npm run build
|
||||
npm run check:bundle-budget
|
||||
npm run test:module-permutations
|
||||
```
|
||||
|
||||
The build gate also catches accidental eager imports: a page pulled into the
|
||||
entry closure consumes the initial budget, while an oversized page or module
|
||||
descriptor consumes the asynchronous chunk budget.
|
||||
Reference in New Issue
Block a user