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

chore: sync GovOPlaN module split state

Browse Source
This commit is contained in:
Albrecht Degering
2026-07-10 12:51:21 +02:00
parent 670f0d9b6f
commit 5413ddfc32
22 changed files with 2732 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docs/DOCS_BACKLOG.md
View File

@@ -1,27 +0,0 @@
# Docs Backlog
## P1 Immediate
- [ ] Define the `docs` backend manifest, permissions, module metadata, and route contribution.
- [ ] Define documentation source DTOs for manifests, routes, capabilities, policies, configuration packages, and wiki-backed sources.
- [ ] Implement configured, available, and evidence classification for documentation entries.
- [ ] Add API routes for current-context documentation lookup and source inspection.
- [ ] Create focused tests for role-aware and configuration-aware documentation filtering.
## P2 Module Integration
- [ ] Define module manifest fields for documentation contributions.
- [ ] Define capability metadata fields that the docs module can render without importing provider internals.
- [ ] Integrate release catalog and configuration package descriptions as documentation sources.
- [ ] Link repository docs and synced wiki pages as durable evidence sources.
## P2 WebUI
- [ ] Build the documentation browser route contribution and navigation metadata.
- [ ] Build configured-system, available-feature, and evidence views.
- [ ] Build route-aware help entry points from the shared WebUI shell.
## P3 Governance
- [ ] Document ownership rules for runtime docs, repository docs, Gitea wiki pages, and active Gitea issues.
- [ ] Document privacy and permission boundaries for role-aware documentation.

293
docs/DOCUMENTATION_EXPERIENCE_CONCEPT.md Normal file
View File

@@ -0,0 +1,293 @@
# Documentation Experience Concept
GovOPlaN Docs should support three ways of understanding the configured
platform:
- outcome-oriented workflow guidance
- structure-oriented reference documentation
- shared design-pattern explanations
These are different reading modes over the same configured-system knowledge.
They should link to each other, respect user and admin perspectives, and keep
the current installation as the primary source of truth.
## Goals
The docs experience should answer these questions first:
- What can I do in this system?
- Which steps do I take to finish this task?
- What does this screen or field mean?
- Why does the interface behave this way?
- For admins: which API, permission, policy, or configuration source backs this
screen?
It should not start from a full product manual. The current tenant, installed
modules, enabled routes, permissions, and configuration decide what is shown as
the default path.
Tracking issue: `add-ideas/govoplan-docs#15`.
## Editorial Pillars
### Workflow Guidance
Workflow docs are written from the reader's intent:
- "I want to create an API key."
- "I want to add a user to a group."
- "I want to configure a reusable mail sender."
- "I want to understand why an option is disabled."
Each workflow topic should have:
- outcome
- audience, usually user or admin
- prerequisites and blockers
- steps using visible interface labels
- expected result
- verification or review step when relevant
- related structure topics
- related design patterns
User workflow topics avoid API paths, internal module ids, raw permission names,
and server configuration unless the user must act on them. They should explain
who can help when a feature is not available.
Admin workflow topics can include technical context: API endpoints, required
permissions, policy sources, configuration keys, migration or audit effects, and
operator escalation paths.
### Structure Reference
Structure docs describe what is visible on a screen and how it maps to platform
contracts.
For users, structure reference is a field glossary:
- screen section
- visible label
- short plain-language meaning
- allowed values or validation
- where the value appears later
- common mistakes or limits
For admins, structure reference adds technical columns:
- route and module
- API method and path
- request or response field
- configuration key or policy field
- permission or scope
- provenance or inheritance rule
- audit/event implication
- safety or approval requirement
Structure docs should be linked from workflow steps and from inline field help.
They should also link back to the workflows where the field is commonly used.
### Design Patterns
Pattern docs explain repeated platform behavior once, then link to examples.
They are not implementation tutorials; they explain what a reader should expect
when they see a familiar affordance.
Initial pattern topics should include:
- field help marker next to labels
- disabled action and blocker explanation
- advanced options panel
- guided wizard and review step
- policy provenance and effective value rows
- status badges and problem lists
- in-app help menu and route-specific help context
- evidence, available, and configured documentation layers
The field help marker is the immediate example. In the app, `FieldLabel` can
render `InlineHelp` beside form labels, and `helpForFieldLabel` currently maps
known labels to short help text. The docs layer should treat this as a pattern:
brief local explanation beside the field, with a link to the fuller structure or
workflow topic when more detail is needed.
## Audience Model
The docs source model may be shared, but presentation must be audience-specific.
### User View
User docs should be calm, task-focused, and plain-language:
- start from "I want to..."
- use current interface labels
- explain limits and unavailable options without exposing internals
- show who can change configuration or permissions
- link to short field explanations and general patterns
User docs should not require knowledge of APIs, scopes, module ids, deployment
configuration, or policy source chains.
### Admin View
Admin docs should still be workflow-centered, but they may be technical:
- start from tenant, module, access, policy, and operator tasks
- expose API endpoints, DTO fields, permissions, module ids, capabilities, and
configuration keys
- show route and field mappings
- explain provenance, inheritance, audit, and approval behavior
- include evidence for installed-but-disabled and optional capabilities
Admin docs are the right place to map an interface field to the API field and
explain operational consequences.
## Presentation Shape
The docs module should remain part of the platform because it needs the current
configuration, registry, permissions, modules, routes, and policy state. The
presentation should still feel like a documentation interface, not like another
business module.
The recommended shape is:
- keep the `docs` backend module and configured-system API
- expose a full-page Help Center route served by the same server
- use lighter documentation chrome instead of normal module-workspace density
- keep route-aware entry points from the app shell, help menu, field help, and
admin screens
- allow direct links such as `/docs?type=user&topic=...` or
`/docs?type=admin&route=...`
- label the content as documentation for "this system" rather than as a generic
marketing or product manual
This preserves third-person reference behavior while keeping the runtime
benefits of a docs module. The server can still filter and explain content based
on the actual installation.
## Navigation Model
The Help Center should have primary modes:
- Workflows
- Reference
- Patterns
- This system
`This system` is the configured/available/evidence view that already exists in
the first docs module slice. It should remain useful for admins and diagnostics,
but normal users should mostly enter through Workflows or contextual help.
Each topic should support stable anchors and related-topic links:
- workflow topics link to fields and patterns
- field/reference topics link to workflows and API details when the reader is an
admin
- pattern topics link to examples and the components that implement them
- unavailable topics link to the blocker and the actor who can resolve it
## Source Contract Direction
The current `DocumentationTopic` contract can carry the first version through
`metadata`, `documentation_types`, `conditions`, `links`, `related_modules`, and
`unlocks`. As the docs experience matures, typed source DTOs should be added for
clarity.
Recommended topic kinds:
- `workflow`
- `reference`
- `pattern`
- `system`
Recommended workflow metadata:
- `outcome`
- `steps`
- `prerequisites`
- `result`
- `verification`
- `related_field_ids`
- `related_pattern_ids`
Recommended reference metadata:
- `route`
- `screen`
- `section`
- `fields`
- `api`
- `permissions`
- `configuration_keys`
- `policy_sources`
Recommended field metadata:
- `field_id`
- `label`
- `user_description`
- `admin_description`
- `api_field`
- `api_path`
- `configuration_key`
- `permission_scope`
- `validation`
- `provenance`
- `audit_event`
Recommended pattern metadata:
- `pattern_id`
- `purpose`
- `when_used`
- `user_explanation`
- `admin_explanation`
- `component_refs`
- `related_topics`
Feature modules should contribute this data through manifests, runtime providers,
route metadata, generated docs, or typed DTOs. The docs module renders and
links the material; it should not import feature-module internals.
## Authoring Rules
Workflow topics:
- use visible UI labels
- keep each step actionable
- mention blockers where the user would encounter them
- link to field/reference topics instead of repeating field tables
Reference topics:
- keep user columns short
- put API, permission, and configuration mapping in the admin view
- identify generated or runtime-derived values
- avoid exposing secrets or raw policy payloads
Pattern topics:
- explain the pattern once
- link to current examples
- distinguish user meaning from admin/operator meaning
- stay stable even when individual screens change
## Implementation Path
1. Keep the existing context API and add topic kind metadata.
2. Add docs-topic grouping for workflows, reference, patterns, and system
diagnostics.
3. Add backend DTOs for field/reference metadata after the metadata shape is
proven with one or two modules.
4. Rework the WebUI into a Help Center route with audience mode, search,
contextual anchors, and the four navigation modes.
5. Connect in-app help entry points to docs topics: help menu, route context,
inline field help, disabled-action blockers, and admin reference tables.
6. Seed access-module content first because users, groups, roles, sessions, and
API keys have clear user/admin splits and concrete API mappings.
7. Add pattern topics for existing core UI behavior, starting with field help,
blockers, advanced panels, wizards, and policy provenance.
8. Add tests for classification, audience filtering, topic linking, and route or
field anchor generation.
The first shippable milestone should be small: one workflow, one structure
reference, and one design-pattern topic for access administration, all filtered
by the current docs context and visible in the Help Center.

115
docs/DOCUMENTATION_LAYER_CONCEPT.md
View File

@@ -6,6 +6,11 @@ GovOPlaN Docs provides a documentation layer that starts with the configured sys
Only after that should the documentation provide evidence about what else might be possible: installed-but-disabled features, optional modules, extension points, product capabilities, or examples from other configurations.
The editorial experience is defined in
`docs/DOCUMENTATION_EXPERIENCE_CONCEPT.md`: workflow guidance, structure
reference, and shared design-pattern explanations are separate reading modes
over this configured-system model.
## Problem
Traditional product documentation describes the full system. That creates avoidable complexity in configurable public-sector platforms because most users only need a slice of the system:
@@ -71,6 +76,7 @@ Evidence should be discoverable, but it should not be the primary reading path f
The docs module should consume documentation sources through explicit contracts:
- module manifest documentation metadata
- module manifest runtime documentation providers
- route metadata and page-level help references
- capability metadata
- configuration-package descriptions
@@ -80,6 +86,113 @@ The docs module should consume documentation sources through explicit contracts:
Feature modules should contribute documentation metadata without the docs module importing their internals.
### Module-Owned Documentation
Documentation is distributed over the modules that own the behavior. A module can
register durable topics directly in its `ModuleManifest.documentation` tuple.
Use this for stable explanations such as the module purpose, common workflows,
policy hierarchy, route meaning, and links to public docs or repository docs.
When the text depends on active configuration, a module registers a provider in
`ModuleManifest.documentation_providers`. The provider receives a
`DocumentationContext` with the active registry, principal, settings, and a
database session when available. The module can then describe the effective
state without the docs module importing feature internals.
For example, `govoplan-mail` contributes static documentation for reusable mail
profiles and a runtime tenant policy topic. If the effective tenant mail policy
limits sending to approved profile ids and disables user, group, and
campaign-local profiles, the runtime docs state that users can choose approved
profiles but cannot bring arbitrary SMTP or IMAP servers at lower scopes. If the
policy allows lower scopes, the same topic explains which scopes may define
profiles and whether credential inheritance is locked.
Runtime providers must avoid leaking secrets. They should summarize posture,
counts, source provenance, and enabling conditions rather than exposing
credentials, hostnames, profile ids, or raw policy payloads unless the route is
explicitly intended for that level of detail.
### Conditions And Unlocks
Documentation topics can declare conditions:
- required modules
- one-of module alternatives
- modules that must be absent
- required capabilities
- required scopes or one-of scope alternatives
- configuration keys that influence the topic
The docs API classifies satisfied topics into their requested layer. Unsatisfied
topics remain visible as available or evidence documentation when safe, with a
reason such as a missing module, capability, or scope.
Topics can also declare related modules and unlock notes. This lets a module
state that additional behavior becomes available when another module is
installed. Runtime docs should link to the configured local behavior first and
then to public module documentation for broader examples.
### Admin And User Documentation
GovOPlaN has two documentation presentations over the same source model.
Admin documentation is allowed to be technical. It can expose installed module
ids, route contributions, API paths, permissions, capability names, server
configuration keys, policy source chains, migration notes, and operator
evidence. This is the right place to explain exactly why a setting is available,
which API applies it, and which configuration key or policy source controls it.
User documentation should be written for people without technical background. It
should explain what the user can do, what they cannot do, and who to ask when a
needed option is missing. It should avoid route names, API calls, raw policy
payloads, internal module ids, and server configuration unless that information
is genuinely meaningful to the user.
Each `DocumentationTopic` declares `documentation_types`, currently `admin`,
`user`, or both. Runtime providers receive the requested type in
`DocumentationContext.documentation_type`, so they can generate different text
from the same effective configuration. For example, mail admin docs can mention
mail profile policy sources and API endpoints, while user docs can simply say
whether the user may choose an approved mail profile or add a local mail server.
The first presentation rule is:
- admin docs show technical context and evidence tables
- user docs show plain-language topics, examples, limits, and escalation paths
- both presentations are filtered by installed modules, active configuration,
permissions, and safe disclosure rules
### Localization
Localization should be prepared before substantial documentation text is added.
Every durable topic should have a stable `i18n_key`. The English source text can
remain in the manifest or provider, but topics may include locale-specific
`translations` for `title`, `summary`, and `body`.
The docs API accepts a requested locale and falls back in this order:
- exact locale, such as `de-AT`
- base language, such as `de`
- English translation if present
- source text
This keeps the first implementation simple while avoiding a later rewrite of
every module documentation contribution. A later dedicated translation catalog
can still use the same `i18n_key` values.
### Public Documentation For Missing Modules
The configured-system docs should not explain every uninstalled module in full.
General documentation for the product and modules not installed in the current
system belongs on `https://govplan.add-ideas.de/`, served by `govoplan-web`.
Runtime documentation should link to the public page when:
- an optional module is not installed
- a feature is unlocked by adding another module
- an example uses modules that are not active locally
- a user needs conceptual background beyond the configured system
## Rendering Model
The runtime docs UI should be context-aware:
@@ -111,6 +224,7 @@ The first implementation should define:
- a configured/available/evidence classifier
- a minimal API for current-context documentation
- a WebUI route contribution for the documentation browser
- a provider contract for configuration-derived runtime topics
The first UI can be simple:
@@ -119,5 +233,6 @@ The first UI can be simple:
- active policies
- available-but-disabled evidence
- source links to wiki or repository docs
- module documentation topics with links and unlock notes
Once the source model is stable, feature modules can add richer documentation contributions through their manifests and capabilities.

70
docs/INSTANCE_AWARE_DOCUMENTATION.md Normal file
View File

@@ -0,0 +1,70 @@
# Instance-Aware Documentation
The docs module renders documentation for the current GovOPlaN instance instead
of showing a static product manual.
## Inputs
The documentation context is built from:
- enabled module manifests
- frontend routes and navigation metadata
- module permissions and the current principal's granted scopes
- documentation topics contributed by manifests
- runtime documentation providers contributed by modules
- optional dependencies and declared capabilities
## Layers
| Layer | Meaning |
| --- | --- |
| `always` | Generic platform concepts that are useful in every deployment. |
| `configured` | Documentation for installed modules/features visible in this instance. |
| `available` | Installed features hidden by missing permissions or unmet conditions. |
| `evidence` | Hints for unavailable optional modules, missing capabilities, or external evidence sources. |
Normal user documentation should emphasize `always` and `configured` content.
Admin documentation may show all layers plus route, permission, module, and
capability diagnostics.
## Conditions
Documentation topics can declare:
- required modules
- any-of module sets
- modules that must be absent
- required capabilities
- required scopes
- any-of scope sets
- related configuration keys
The API returns both a human-readable `reason` and structured `blockers`:
```json
{
"reason": "missing modules: mail; missing scopes: mail:profile:read",
"blockers": {
"modules": ["mail"],
"capabilities": [],
"scopes": ["mail:profile:read"]
}
}
```
The WebUI must display the reason and, when present, the blocker lists. This
prevents dead-end instructions: users see whether a feature is unavailable
because a module is missing, a capability is not registered, or their current
permissions do not expose it.
## Module Guidance
Module docs should not hard-code assumptions about sibling modules. A module
should contribute conditional topics such as:
- "Send selected file by mail" requiring `files` and `mail`
- "Campaign attachments from storage" requiring `campaigns` and `files`
- "Mailbox diagnostics" requiring `mail.devMailbox`
The docs module remains the renderer. Feature modules own their subject matter
and describe unlocks through manifest metadata.