From 9e7103f6135455f43c9d264ca2fcaf1f8cb2b474 Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Mon, 20 Jul 2026 16:49:30 +0200 Subject: [PATCH] docs: define the interface pattern language --- docs/FRONTEND_LAYOUT_PRINCIPLES.md | 8 + docs/INTERFACE_PATTERN_LANGUAGE.md | 392 ++++++++++++++++++++++++++++ docs/INTERFACE_SURFACE_INVENTORY.md | 236 +++++++++++++++++ 3 files changed, 636 insertions(+) create mode 100644 docs/INTERFACE_PATTERN_LANGUAGE.md create mode 100644 docs/INTERFACE_SURFACE_INVENTORY.md diff --git a/docs/FRONTEND_LAYOUT_PRINCIPLES.md b/docs/FRONTEND_LAYOUT_PRINCIPLES.md index b84b9a0..8501b15 100644 --- a/docs/FRONTEND_LAYOUT_PRINCIPLES.md +++ b/docs/FRONTEND_LAYOUT_PRINCIPLES.md @@ -3,6 +3,11 @@ GovOPlaN modules should choose their page layout by the kind of work the user is doing, not by the repository that owns the feature. +These concise layout choices are one canonical input to the broader +[`INTERFACE_PATTERN_LANGUAGE.md`](INTERFACE_PATTERN_LANGUAGE.md). The current +route and rollout evidence lives in +[`INTERFACE_SURFACE_INVENTORY.md`](INTERFACE_SURFACE_INVENTORY.md). + ## Structured Data Directories Use a full-available-space workspace for structured data directories: files, @@ -41,6 +46,9 @@ Principles: summaries, and dashboard widgets. - Collapsible panels and segmented controls are appropriate when a dense configuration area needs controlled disclosure. +- A collapsible card whose sole content is a table gives that table the full + available card body; avoid nested cards, duplicate padding, inner max-widths, + and nested scrolling. - Avoid forcing workflow/configuration pages into a file-explorer style unless the primary interaction is genuinely directory browsing. diff --git a/docs/INTERFACE_PATTERN_LANGUAGE.md b/docs/INTERFACE_PATTERN_LANGUAGE.md new file mode 100644 index 0000000..148cece --- /dev/null +++ b/docs/INTERFACE_PATTERN_LANGUAGE.md @@ -0,0 +1,392 @@ +# GovOPlaN Interface Pattern Language + +This document is the cross-repository pattern language for GovOPlaN user +interfaces. It turns the existing ethical doctrine, binding UI/UX decisions, +layout principles, and module boundary into a common composition and review +grammar. It does not replace those sources. + +The companion [interface surface inventory](INTERFACE_SURFACE_INVENTORY.md) +records which surfaces the current code contributes and where each surface +enters the rollout. + +## Source Of Truth And Precedence + +Use the narrowest owning document when changing a rule: + +1. `govoplan-core/docs/INTERFACE_ETHICS_AND_DESIGN_DOCTRINE.md` owns why a + consequential interface must preserve context, decision, consequence, + responsibility, contestability, and traceability. +2. `govoplan-core/docs/UI_UX_DECISION_LEDGER.md` owns accepted product decisions + such as progressive disclosure, adaptive forms, blocker language, guided + operations, and the platform theme contract. +3. `docs/FRONTEND_LAYOUT_PRINCIPLES.md` owns the high-level choice between a + full-space structured-data workspace and a heading/menu/card workflow or + configuration surface. +4. `govoplan-core/docs/MODULE_ARCHITECTURE.md` owns the shell, route, navigation, + UI-capability, and shared-component boundaries. +5. This document owns the common pattern names, placement grammar, wording and + state conventions, focused-view composition, and definition of done across + those sources. + +If two rules appear to conflict, do not create a third local convention. Record +the conflict in the owning decision ledger, resolve it there, and update the +affected patterns and surfaces together. + +## Product Contract + +GovOPlaN should feel calm because it shows what is relevant to the task, not +because it hides authority, risk, or evidence. Every surface follows these +rules: + +- Start with the user's current object and task. +- Show common actions before advanced controls. +- Keep context, status, problems, and the next action spatially connected. +- Make consequential effects explicit before execution and observed effects + inspectable afterwards. +- Treat permissions, policy, privacy, and module availability as behavior, not + decoration. +- Keep optional modules optional. Compose through core route and UI-capability + contracts, never sibling-private components. +- Preserve a stable way back to the containing object and the broader system. +- Do not let navigation, selection, or a view switch imply consent. + +## Surface Archetypes + +Choose an archetype from the task, then specialize it for the domain. A route +may contain more than one bounded archetype, but it should have one dominant +one. + +| Archetype | Use when | Standard anatomy | Do not use when | +| --- | --- | --- | --- | +| Directory or explorer | Users browse hierarchical collections such as files, mailboxes, calendars, addresses, or records. | Collection/source pane, collection actions, filter in the pane it affects, main list/content pane, optional detail pane. | The content is a set of unrelated settings or workflow stages. | +| List-detail workspace | Users repeatedly find objects, inspect one, and act without losing list context. | Search/filter/list, persistent selected-object context, detail/actions, stable selection and URL. | A single guided operation is the primary task. | +| Focused task view | Only a bounded composition is needed to complete one task. | Task identity and reason, selected object, necessary module regions/actions, progress or status, obvious exit to the full system. | Hiding a surface would obscure a consequence, blocker, or required evidence. | +| Create or edit | Users change one coherent object state. | Adaptive typed form, field-level validation, advanced section, save/cancel, unsaved-change guard. | Discovery-heavy setup or a broad consequential change needs staged review. | +| Guided setup or import | The user must discover, upload, map, test, or preflight before a safe result exists. | Named steps, current progress, preserved inputs, validation/problem list, review, resumable completion where work is durable. | An ordinary edit can be understood as one coherent form. | +| Review or decision | A person must inspect evidence and deliberately approve, reject, send, publish, or otherwise commit. | Decision context, evidence/problems, consequence and reversibility, authority/provenance, explicit action, resulting record. | The interaction is passive inspection. | +| Monitoring, progress, or report | Users observe asynchronous or aggregate state and intervene when needed. | Summary, filters, durable job/item state, last update, retry/reconcile/intervention, detail and evidence. | A toast is sufficient for a short, non-durable local action. | +| Administration or configuration | Users compare and configure separate concerns. | Heading and scope, grouped subnavigation, overview/list plus selected details, adaptive editor or guided risky operation, effective policy and source. | The primary task is browsing one structured object space. | +| Dashboard | Users need a task-oriented starting point across modules. | Prioritized actionable widgets, scoped status, clear destination per widget, explicit refresh/staleness. | It merely duplicates every module navigation item or metric. | +| Public service or entry | An unauthenticated or external participant starts or resumes a service. | Service identity, eligibility/context, privacy and evidence expectations, accessible form/task, save/resume or handoff. | The actor is performing internal administration. | + +## Placement Grammar + +### Shell And Navigation + +- The global title bar and rail belong to core. A module contributes routes, + navigation metadata, and explicit UI capabilities; it does not reproduce the + shell. +- Global navigation answers "which service area?" Local subnavigation answers + "which stable facet of this object or area?" A progress indicator answers + "where am I in this operation?" Do not use those three controls + interchangeably. +- Keep the current tenant, actor, object, and selected version or scope stable + across local navigation. Guard unsaved work before navigation. +- Permission and capability filtering happens before view composition. A + missing menu item is not evidence that an actor lacks backend access, and a + visible item is never authorization by itself. +- Route, selection, panel, and view changes must not execute consequential + actions. + +### Page And Workspace + +- Structured directories use the full available content space and persistent + panes. They do not add a decorative heading row that reduces working height. +- Workflow, configuration, dashboard, and explanatory pages may use a heading. + The heading names the task or scoped object and contains only route-level + actions. +- Put filters beside the list or pane they affect. Put bulk actions immediately + above or beside the current selection. Put object actions with the object + detail, not in the global title bar. +- Full-page create and edit surfaces put their persistent action cluster in the + upper-right of the page heading. `Discard` comes before `Save …`, with the + primary save action at the far right. Keep both controls in the same place + across validation, loading, and saved states; guard unsaved work when the + user discards or navigates away. +- A page or panel has one visually primary action for its current state. Put + secondary actions beside it. Separate destructive actions and name their real + effect. +- Dialog actions use a stable footer: cancel/back first, then the primary action + at the end. Header and footer stay fixed while long bodies scroll. +- Use cards for independent groups, summaries, and settings blocks. Do not wrap + every region in a card or nest cards merely to create spacing. +- When a collapsible card contains one table and no other content, the table + uses the card's full available width and body height. The card/table region + owns overflow; do not add an inner max-width, decorative wrapper, duplicate + padding, or nested scroll container that reduces the working area. +- Row actions in tables are icon-only controls in a stable rightmost action + column. Order them by intent: inspect/open, edit, copy/duplicate, + transfer/share/download, retry/restore, then remove/delete last. Omit actions + that do not apply without closing the gap or changing the relative order. + Every icon has a translated accessible name and matching tooltip. Separate + destructive actions visually, and use a named confirmation/review surface + when the consequence cannot be understood from the icon and row context. +- Transient feedback should not shift the workspace. Durable failures, partial + results, and blockers remain attached to the affected item or operation. + +### Detail And Explanation + +- Keep the selected object's identity and material status visible while its + detail changes. +- Short field help sits with the label. Longer "Why?", policy source, + diagnostics, or provenance belongs in an expandable area, detail panel, or + review step. +- Empty space is not an error. An empty state states what is empty, why that can + happen, and the permitted next action. Do not show creation actions to actors + who cannot create. + +## Visual Grammar + +- Core owns the appearance contract and shared CSS tokens. Modules use core + colors, spacing, radii, shadows, focus treatment, status colors, and disabled + treatment; module CSS may specialize layout only. +- Establish hierarchy through spacing, typography, grouping, and placement + before adding borders or color. +- Color never carries status or required action alone. Pair it with text and, + where useful, an icon. +- Icons support recognition but do not replace accessible names. Use the core + icon-name mapping for navigation. +- Keep list columns, tree indentation, headers, dialog dimensions, and action + positions stable as content changes. +- Density is a user preference, not a license to remove labels, focus targets, + explanations, or consequences. +- Respect system/light/dark themes and reduced-motion preferences through the + core contract. Do not build module-local theme systems. + +## Wording Grammar + +Use the same noun for the same domain object in navigation, headings, fields, +actions, states, API-facing explanations, and documentation. Prefer the most +specific user-facing noun: "Recipients" rather than "Data", "Delivery job" +rather than "Process", and "Mail profile" rather than "Configuration" when +that is what the user is acting on. + +Actions use a verb plus the object or consequence: + +- Prefer `Save campaign`, `Review messages`, `Queue delivery`, `Retry failed + deliveries`, or `Delete calendar`. +- Avoid `Submit`, `OK`, `Continue`, or `Execute` when a more precise action is + available. +- Use `Continue` only when it advances a reversible guided flow without + committing the final effect. +- Do not say `Undo` when the system can only cancel future work, create a + correction, supersede a record, or request retraction. + +State text describes observed state, not optimism. Use stable shared terms where +they fit: `Draft`, `Ready for review`, `Blocked`, `Queued`, `Running`, +`Retry scheduled`, `Partially completed`, `Completed`, `Failed`, and +`Cancelled`. Domain-specific states may refine these terms but should not give a +shared term a contradictory meaning. + +Blocked and failed actions use the structured language from DUE-005: + +- what is unavailable or failed +- why, in plain language +- what must happen next +- who can do it +- where to go +- optional technical details behind deliberate disclosure + +Errors should identify the affected object and whether saved state or external +effects may already exist. Never expose raw exception text as the only user +message. + +## State Contract + +Every surface implements the states it can reach; it does not render a blank +region while waiting or collapse distinct outcomes into a generic error. + +| State | Required treatment | +| --- | --- | +| Loading | Keep the stable shell and context visible. Name what is loading; preserve usable prior data when safe. | +| Empty | State the scope and reason, then show only permitted next actions. | +| Validation problem | Attach the problem to the field/item and provide a navigable summary when problems span regions or steps. | +| Permission denied | Name the unavailable action or object, the required actor/role where safe, and a valid exit. Do not leak protected data. | +| Capability unavailable | Distinguish not installed, disabled, not configured, unhealthy, and not permitted when the actor may know. Give the responsible actor and target. | +| Offline or unreachable | Preserve local context and unsaved input, show last-known/stale state, and offer a safe retry. Do not present network absence as an authentication failure. | +| Stale or conflicting | Show which data changed, preserve both values where feasible, and offer reload, merge, or explicit overwrite according to policy. | +| Partial result | Show completed and incomplete effects separately. Never label a partial operation successful without qualification. | +| Asynchronous work | Show durable job identity, queued/running/retry/block/final state, last update, progress if meaningful, and leave/return behavior. | +| Success | State the resulting object/effect and provide its evidence or destination. Use a transient toast only when the result is already visible and durable elsewhere. | +| Destructive or corrective action | Preview scope, downstream effects, reversibility limit, evidence, and required confirmation or approval. | + +Long-running or external work must expose retry and reconciliation as observable +states. The UI must not imply that a request and its external effect were one +atomic success when an outbox, worker, or remote system sits between them. + +## Consequence And Provenance + +Before an action affects records, rights, policy, retention, communications, +money, external systems, or workflow state, its action surface must answer the +decision-surface questions in the interface doctrine. At minimum show: + +- affected object and scope +- acting identity or system actor and relevant authority +- immediate and possible downstream effects +- whether the operation is reversible, cancellable, corrective, or final +- blockers and their resolution path +- audit/evidence that will be created +- effective policy or configuration source when it changes the decision + +After execution, users must be able to reach the command/job, observed effects, +policy result, failures, retries, reconciliation outcome, actor, time, and source +data that explain the result. Provenance may be quiet by default, but it must not +be absent. + +Privacy follows the same rule: lists, previews, logs, notifications, and +diagnostics show only the personal or secret data needed for the actor's task. +Redaction must be explicit enough that users do not mistake a redacted value for +missing source data. + +## Focused Views + +A focused view is a declarative UI composition for a task. It selects the +routes, local regions, navigation entries, and actions relevant to that task +after installed-module, capability, permission, and policy filtering. It does +not change backend authorization or domain state. + +A view definition must be able to explain: + +- its stable identifier, label, and task purpose +- the current object/scope and default destination +- included navigation and contributed regions/actions, with deterministic order +- the visible escape to the containing module and full system +- why the view is active and how the user may switch when switching is allowed +- what happens to unsaved work when entering, leaving, or switching views + +Focused views follow these invariants: + +- Do not hide a blocker, material consequence, provenance, or required review + merely to make the screen quieter. +- Preserve the global tenant/actor context and provide an obvious exit. +- Filter unavailable contributions without leaving broken separators, empty + groups, or dead destinations. +- A manual or automatic switch is navigation, not consent. Guard unsaved work + and never execute a domain action as a side effect. +- Display why a non-manual default was selected, for example a role or task + default, without exposing protected policy details. +- Treat an unknown or invalid view as a recoverable fallback to the normal + module surface. + +When more than one source proposes a focused view, use this precedence: + +1. a manual view pinned for the current user session +2. a current-task suggestion, including a future workflow-step suggestion +3. the user's saved default +4. the role or tenant default +5. the normal full interface + +Show the active source and an escape to the full interface. A task or workflow +suggestion is never an authorization change and never locks the user into the +composition; tenant policy may constrain which views are selectable, but it +must not hide required evidence or remove that escape. Workflow implementation +is explicitly postponed and is not a prerequisite for defining, manually +selecting, testing, or piloting focused views. A future workflow module may +request a view through a core contract; it must not own the view composition +implementation. + +## Accessibility And Responsive Contract + +- Every action is reachable and operable by keyboard in a logical order. +- Use semantic headings, landmarks, labels, tables/lists, and native controls + before adding ARIA. Icon-only controls need stable accessible names. +- Focus is visible. Dialogs trap focus, announce their name, and return focus to + the control that opened them. Validation moves or links focus to the first + relevant problem without losing the problem summary. +- Loading, saved, failed, queued, progress, and externally updated states are + announced without repeatedly interrupting the user. +- Disabled primary actions need a focusable explanation; a pointer-only tooltip + is insufficient. +- Do not rely on color, hover, drag-and-drop, pointer precision, or animation as + the only interaction. Provide keyboard and explicit-control equivalents. +- At narrow widths and high zoom, preserve task order and action access. Collapse + secondary panes into an explicit drawer/step and never move a destructive + action into the primary position. +- Honor reduced motion. Avoid motion that implies progress when the operation is + merely waiting. +- Truncation has an accessible full-value path. Personal or secret values remain + redacted according to permission and policy in that path. + +## Component Ownership + +Core already exports shell, navigation, access-boundary, form, dialog, loading, +status, policy/provenance, blocker, review, table, tree, message-display, and +unsaved-change primitives. Reuse them when their contract fits. + +Do not promote a component only because two screens look similar. Promote it to +`@govoplan/core-webui` after a second consumer or a clear platform contract has +proved shared behavior, accessibility, state, and extension needs. Modules own +domain composition, wording, and policy semantics; core owns generic contracts +and appearance. + +## Test Expectations + +For every changed surface, select tests from each applicable layer: + +- route and permission tests: module enabled/disabled permutations, route guard, + contribution filtering, fallback, and direct-link behavior +- behavior tests: primary task, validation, unsaved-change guard, confirmation, + retry/reconcile, partial result, and leave/return behavior +- accessibility tests: semantic names/roles, keyboard order, focus entry/return, + live-state announcements, and non-color status meaning +- state tests: loading, empty, denied, capability-missing, stale/conflict, + offline, partial, success, and destructive/corrective outcomes as applicable +- composition tests: absent optional module, duplicate/unknown contribution, + deterministic ordering, and focused-view fallback +- presentation checks: supported widths/zoom, light/dark/system theme, reduced + motion, comfortable/compact density, and long translated text +- i18n checks: user-facing strings owned by the rendering package and structural + audits passing +- visual regression: useful for geometry and hierarchy after behavior and + accessibility assertions exist; never the only evidence + +If the current harness cannot automate a required check, record the gap and the +manual evidence in the owning issue. "Not tested" is an inventory state, not a +reason to infer that a pattern is satisfied. + +## Definition Of Done For A Surface + +- The dominant task and archetype are recorded in the inventory. +- Placement, action hierarchy, wording, and every reachable state follow this + pattern language or an explicit ledger exception. +- Permission, capability, privacy, and redaction behavior are verified. +- Consequence, reversibility, authority, evidence, and provenance are present + where applicable. +- Keyboard, focus, announcement, responsive, theme, density, motion, and i18n + behavior are covered in proportion to the surface. +- Optional modules remain optional and no sibling-private UI import was added. +- Behavioral/accessibility evidence is linked from the rollout matrix and issue. +- Configured-system help can reach the applicable pattern or reference topic + when [Docs #15](https://git.add-ideas.de/add-ideas/govoplan-docs/issues/15) + supplies that experience. + +## First Pilot: Campaign + +[Campaign #74](https://git.add-ideas.de/add-ideas/govoplan-campaign/issues/74) +is the first full-domain audit and migration. It should prove patterns before +generic extraction: + +- [#59](https://git.add-ideas.de/add-ideas/govoplan-campaign/issues/59) and + [#73](https://git.add-ideas.de/add-ideas/govoplan-campaign/issues/73): stable, + accessible preview and attachment-detail overlays +- [#63](https://git.add-ideas.de/add-ideas/govoplan-campaign/issues/63): review + stages, outcomes, blockers, and intervention vocabulary +- [#62](https://git.add-ideas.de/add-ideas/govoplan-campaign/issues/62): explicit + synchronous/asynchronous send mode and durable delivery progress +- [#65](https://git.add-ideas.de/add-ideas/govoplan-campaign/issues/65): one + coherent report filtering and count-affordance model +- [#35](https://git.add-ideas.de/add-ideas/govoplan-campaign/issues/35): guided + first-campaign entry + +These slices do not depend on the Workflow runtime. Campaign's current +domain-owned review/send state is enough to prove layout, wording, focused-view, +progress, intervention, and evidence patterns. + +## Revision Procedure + +1. Record a changed product decision in the core UI/UX decision ledger. +2. Update the relevant pattern here without copying the full owning doctrine. +3. Update the surface inventory and rollout owner/issues. +4. Change shared components only where the proven contract belongs to core. +5. Migrate and test affected module surfaces. +6. Publish configured-system pattern/reference help through the Docs module. diff --git a/docs/INTERFACE_SURFACE_INVENTORY.md b/docs/INTERFACE_SURFACE_INVENTORY.md new file mode 100644 index 0000000..6818b56 --- /dev/null +++ b/docs/INTERFACE_SURFACE_INVENTORY.md @@ -0,0 +1,236 @@ +# GovOPlaN Interface Surface Inventory And Rollout + +This is the initial evidence inventory for the product-wide interface pattern +language. It records code contributions, not an assertion that every listed +surface is complete, enabled in a deployment, usable, or compliant. + +The applicable design contract is +[`INTERFACE_PATTERN_LANGUAGE.md`](INTERFACE_PATTERN_LANGUAGE.md). + +## Snapshot And Method + +Snapshot date: 2026-07-20. + +Evidence was read from tracked Git `HEAD` in the local GovOPlaN checkouts: + +- core routes and fallback behavior in `govoplan-core/webui/src/App.tsx` +- every present `govoplan-*/webui/src/module.ts` +- the matching backend `src/*/backend/manifest.py` +- named UI capabilities and contribution identifiers in each `module.ts` +- Campaign nested routes in its tracked `CampaignWorkspace.tsx` and + `SectionSidebar.tsx` + +Tracked `HEAD` is used as the integrated baseline. Dirty worktree changes are +not treated as delivered behavior. One material exception is called out in the +Campaign inventory: local WIP folds the tracked `recipient-data` surface into +`recipients`, but that change is not yet part of the baseline. + +Runtime visibility remains conditional on the module being packaged and +enabled, server metadata, installed optional capabilities, the authenticated +actor, tenant context, route permission guards, and inner-surface permission +checks. A route in this inventory therefore means "the code contributes this +route when its module is active", not "every user sees it". + +Inventory states: + +- **Contributed**: a route or named UI capability exists in tracked source. +- **Metadata gap**: frontend runtime source contributes a route but the backend + manifest does not describe the same route/navigation surface. +- **Unreviewed**: the surface has not yet completed the pattern, state, + accessibility, privacy, and consequence audit. This is the default unless an + issue supplies verification evidence. +- **Pilot**: the surface is in the Campaign-first rollout. + +## Core Shell Surfaces + +| Surface | Owner and code evidence | Audience/access evidence | Primary task and target archetype | Audit / rollout | +| --- | --- | --- | --- | --- | +| Public landing and login | `govoplan-core` `PublicLandingPage`; rendered while no authenticated principal exists | Unauthenticated; maintenance and backend-reachability context are shell inputs | Understand the service and authenticate; public entry | Unreviewed; later public-entry audit | +| Session/bootstrap state | `govoplan-core` `App.tsx` and `AppShell` | All browser sessions during bootstrap | Understand that session/platform state is loading; state contract | Unreviewed; core shell | +| `/` authenticated redirect | `govoplan-core` chooses the first visible navigation destination | Authenticated; result depends on visible nav contributions | Enter the actor's first accessible service area; navigation behavior, not a content page | Unreviewed; focused-view/default-route work must preserve this fallback | +| `/dashboard` fallback | `govoplan-core` `DashboardPage` only when the Dashboard module is absent | Authenticated; no route-specific scope in core | Cross-module starting point; dashboard | Unreviewed; compare with module dashboard before shared changes | +| `/settings` | `govoplan-core` `SettingsPage` | Authenticated; contributed sections and integrations filter internally | Profile, UI/workspace preference, local connection, and user-scoped integration settings; configuration | Unreviewed; Core #225 program | +| Shell chrome | `AppShell`, `Titlebar`, `IconRail`, `BreadcrumbBar`, `HelpMenu`, language menu, unsaved-change provider | Public/authenticated variants; nav filtered later | Tenant/actor context, global navigation, help, language, session and maintenance state | Unreviewed; platform-owned prerequisite for focused views | + +## Direct Module Route Contributions + +The access guard column reports only the route-level declaration in +`module.ts`. Inner APIs and controls may impose additional checks. + +| Route | Owner / render evidence | Route-level access evidence | Primary task | Target archetype | Status / priority | +| --- | --- | --- | --- | --- | --- | +| `/admin` | `govoplan-access` `AdminPage` | Any core `adminReadScopes` | Administer system and tenant concerns assembled from module sections | Administration/configuration | Contributed; unreviewed; P1 under [Core #225](https://git.add-ideas.de/add-ideas/govoplan-core/issues/225) | +| `/address-book` | `govoplan-addresses` `AddressBookPage` | `addresses:contact:read` | Browse and manage contacts, address books, and lists | Directory/list-detail | Contributed; unreviewed; P2 after Campaign | +| `/calendar` | `govoplan-calendar` `CalendarPage` | `calendar:event:read` | Browse calendars/events and act on calendar data | Directory/list-detail | Contributed; metadata gap; unreviewed; P2 after Campaign | +| `/campaigns` | `govoplan-campaign` `CampaignListPage` | `campaigns:campaign:read` | Find, compare, create, and open campaigns | List-detail entry | Pilot; P1 [Campaign #74](https://git.add-ideas.de/add-ideas/govoplan-campaign/issues/74) | +| `/campaigns/:campaignId/*` | `govoplan-campaign` `CampaignResourceRoute` and `CampaignWorkspace` | `campaigns:campaign:read`, plus resource probe | Configure, review, send, and inspect one campaign/version | List-detail workspace containing edit, review, monitoring, and evidence surfaces | Pilot; P1 Campaign #74 | +| `/operator` | `govoplan-campaign` `OperatorQueuePage` | Any campaign queue/review/send scope declared by the module | Monitor and intervene in campaign jobs | Monitoring/work queue | Pilot; P1 Campaign #74 | +| `/reports` | `govoplan-campaign` inline `ReportsPage` | `campaigns:report:read` | Reach campaign reporting; current component identifies itself as prepared for later functionality | Reporting | Pilot inventory; implementation maturity explicitly incomplete; P2 after campaign report pilot | +| `/templates` | `govoplan-campaign` `TemplatesPage` | No route guard declared in `module.ts` | Browse/manage campaign templates | Directory/list-detail | Pilot audit; permission intent must be verified; P2 | +| `/dashboard` | `govoplan-dashboard` `DashboardPage` | No route-specific scope | Assemble module-provided actionable widgets | Dashboard | Contributed; unreviewed; P2 | +| `/docs` | `govoplan-docs` `DocsPage` | Docs read or system/tenant settings read scopes | Read configured, available, and evidence-aware documentation | Documentation directory/reference | Contributed; unreviewed; P1 [Docs #15](https://git.add-ideas.de/add-ideas/govoplan-docs/issues/15) after initial pattern content | +| `/files` | `govoplan-files` `FilesPage` | `files:file:read` | Browse folders/files and perform managed-file work | Directory/explorer | Contributed; metadata gap; unreviewed; P2 after Campaign | +| `/idm` | `govoplan-idm` `IdmPage` | Any IDM assignment/write or organization function-assign scope | Inspect and govern identity/function assignments | List-detail/configuration | Contributed; unreviewed; P2 | +| `/mail` | `govoplan-mail` `MailboxPage` | `mail:mailbox:read` | Browse mailboxes and messages | Directory/list-detail | Contributed; metadata gap; unreviewed; P2 after Campaign | +| `/notifications` | `govoplan-notifications` `NotificationCenterPage` | `notifications:notification:read` | Inspect and acknowledge notification state | List-detail/inbox | Contributed without a nav item or backend frontend metadata; navigation intent unknown; P2 discovery | +| `/ops` | `govoplan-ops` `OpsPage` | Ops read or system/tenant settings read scopes | Inspect runtime health and readiness | Monitoring | Contributed; unreviewed; P2 | +| `/organizations` | `govoplan-organizations` `OrganizationsPage` | Organization model/unit/function or admin settings read scopes | Model and inspect organizational structures/functions | Directory/list-detail | Contributed; unreviewed; P2 | +| `/scheduling` | `govoplan-scheduling` `SchedulingPage` | `scheduling:schedule:read` | Plan and decide scheduling requests and availability | List-detail/guided decision | Contributed; metadata gap; unreviewed; P2 | + +## Manifest And Runtime Route Alignment + +Backend route metadata lets operators, Docs, release tooling, and remote bundle +loading reason about the configured interface without executing module UI code. +`module.ts` remains the executable local route/render source. Missing metadata +is recorded here as an evidence gap; this inventory does not infer whether each +gap is intentional. + +| Module | `module.ts` routes | Backend manifest frontend routes | Backend nav alignment | Result | +| --- | --- | --- | --- | --- | +| Access | `/admin` | `/admin` | Aligned | Described | +| Addresses | `/address-book` | `/address-book` | Aligned | Described | +| Admin | No direct route; `admin.sections` | None | Not applicable | Composed surface | +| Audit | No direct route; `admin.sections` | None | Not applicable | Composed surface | +| Calendar | `/calendar` | None | `/calendar` nav exists | Metadata gap | +| Campaign | Five routes | None | Four top-level nav items exist | Metadata gap; wildcard resource route is also undescribed | +| Dashboard | `/dashboard` | `/dashboard` | Aligned | Described | +| Docs | `/docs` | `/docs` | Aligned | Described | +| Files | `/files` | None | `/files` nav exists | Metadata gap | +| IDM | `/idm` | `/idm` | Aligned | Described | +| Mail | `/mail` | None | `/mail` nav exists | Metadata gap | +| Notifications | `/notifications` | No frontend metadata | No nav item | Metadata and discovery gap | +| Ops | `/ops` | `/ops` | Aligned | Described | +| Organizations | `/organizations` | `/organizations` | Aligned | Described | +| Policy | No direct route; `admin.sections` | None | Not applicable | Composed surface | +| Scheduling | `/scheduling` | None | `/scheduling` nav exists | Metadata gap | + +Before a release claims a complete configured-system route inventory, add a +contract check or explicit exceptions so executable routes and manifest +metadata cannot silently diverge. + +## Composed Surfaces And Extension Points + +These surfaces are active only when the host and contributing modules are +enabled and the actor passes the declared filters. + +| Host surface | Contributor and evidence | Contributed regions/actions | Pattern implication | Audit | +| --- | --- | --- | --- | --- | +| `/admin` | Access host (`AdminPage`) | System tenants/users/roles, tenant users/groups/roles/API keys/settings, function-role mappings, user/group mail and file connector scopes | One stable admin information architecture must contain both host-owned and contributed sections | Unreviewed; P1 Core #225 | +| `/admin` | `govoplan-admin` `admin.sections` | Overview; system settings; configuration changes; configuration packages; role/group templates; module management | Configuration, guided operations, review/preflight, consequence | In progress under Core #225; surface-level evidence still needed | +| `/admin` | `govoplan-audit` `admin.sections` | System audit; tenant audit | Evidence/provenance and reporting | Unreviewed | +| `/admin` | `govoplan-files` `admin.sections` and `files.connectors` | System and tenant file connections plus scoped connector managers used by Access | Adaptive configuration, discovery/test, policy and credentials | First migration family in Core #225; verification incomplete in this inventory | +| `/admin` | `govoplan-organizations` `admin.sections` | Tenant organization settings | Configuration/list-detail | Unreviewed | +| `/admin` | `govoplan-policy` `admin.sections` | System, tenant, group, and user retention | Effective value, source/provenance, consequential configuration | Unreviewed; Core #225 phase 4 | +| `/admin` and `/settings` | `govoplan-mail` `mail.profiles` | System/tenant/group/user mail profile and policy managers | Same server/credential/policy grammar as file connectors | Unreviewed; Core #225 mail migration | +| `/settings` | Core host | Profile; interface; workspace; local connection | Personal configuration with adaptive forms and immediate feedback | Unreviewed | +| `/settings` | Files and Mail named capabilities | User-scoped file connections and mail profiles/policy | Optional integration regions disappear cleanly when capability absent | Unreviewed | +| `/settings` | `govoplan-notifications` `settings.sections` | Notification preferences | Personal configuration | Unreviewed | +| `/dashboard` | Dashboard host and `dashboard.widgets` | Installed-modules widget; Ops health widget when Ops contributes it | Widget ordering, staleness, permissions, destination behavior | Unreviewed | +| `/organizations` | IDM `organizations.functionActions` | Action leading to assignment view filtered by IDM scopes | Cross-module context action through explicit capability | Unreviewed | +| Campaign attachments/import | Files `files.fileExplorer` | Folder tree, managed chooser, file listing/pattern resolution/sharing | Optional domain composition without sibling-private imports | Pilot audit under Campaign #74 | +| Campaign review/send | Mail runtime `mail.devMailbox` | Mock-mail verification when backend advertises runtime capability | Optional review stage with unavailable/optional states | Pilot audit under Campaign #63/#62 | + +Other named capability exports (`files.connectors`, `organizations.functionPicker`, +and mail profile validation) are contracts consumed inside the composed surfaces +above; they are not independent routes. + +## Campaign Pilot Surface Map + +Campaign is detailed first because it exercises almost every archetype. The +tracked baseline still contains a dedicated `recipient-data` section. The dirty +local WIP redirects that path into `recipients` and removes it from the sidebar; +do not mark that consolidation delivered until +[Campaign #67](https://git.add-ideas.de/add-ideas/govoplan-campaign/issues/67) +is integrated or the issue state is corrected. + +Campaign already consumes core primitives including `ModuleSubnav`, `Card`, +`PageTitle`, `Button`, `LoadingFrame`, `DismissibleAlert`, `FormField`, +`StatusBadge`, `MetricCard`, `Dialog`, `ConfirmDialog`, `FileDropZone`, +`MessageDisplayPanel`, policy components, access/module capabilities, and +unsaved-navigation guards. Reuse alone does not prove that the composition or +states satisfy the pattern. + +| Surface / code evidence | Primary task | Target pattern | Material consequence/state | Known issue / rollout | +| --- | --- | --- | --- | --- | +| Campaign list (`CampaignListPage`) | Find, compare, create, open | List-detail entry | Campaign lifecycle/status and creation | Audit in [#74](https://git.add-ideas.de/add-ideas/govoplan-campaign/issues/74); guided entry [#35](https://git.add-ideas.de/add-ideas/govoplan-campaign/issues/35) | +| Overview (`CampaignOverviewPage`) | Understand/edit campaign identity, version, access, lifecycle | Object overview plus adaptive edit | Lock/archive/delete/access changes need real consequence and reversibility wording | #74; integrate/reconcile #67 before migration claims | +| Fields (`CampaignFieldsPage`) | Define recipient/template field schema | Structured editor | Schema changes can invalidate recipient/template data | #74 audit | +| Attachments/files (`AttachmentsDataPage`, `AttachmentRulesOverlay`) | Select sources and attachment/ZIP rules | Directory chooser plus adaptive rule editor | Missing or mismatched files affect built messages | #74; attachment-detail [#59](https://git.add-ideas.de/add-ideas/govoplan-campaign/issues/59) | +| Recipients (`RecipientDataPage`) | Select/import/map/edit recipients and per-recipient values/files | Import/mapping plus list-detail editor | Personal data, validation, bulk activation, file links | #74; guided entry #35 | +| Recipient data (`RecipientDetailsPage` in tracked baseline) | Inspect/edit a dedicated recipient-data view | List-detail editor | Personal data and send eligibility | Local WIP removes this separate surface; #67 integration state must decide baseline | +| Template (`TemplateDataPage`, placeholder/expression dialogs) | Author subject/body and preview substitutions | Adaptive editor plus stable preview | Generated communication content and unresolved expressions | #74; stable overlay [#73](https://git.add-ideas.de/add-ideas/govoplan-campaign/issues/73) | +| Mail settings (`MailSettingsPage` settings view) | Select/configure campaign mail transport | Adaptive configuration | Credentials, SMTP/IMAP destinations, test outcomes | #74; align with Core #225 mail pattern | +| Campaign settings (`GlobalSettingsPage` settings view) | Configure campaign behavior | Adaptive configuration | Can alter validation/build/send behavior | #74 audit | +| Mail policy (`MailSettingsPage` policy view) | Inspect/override effective mail policy | Effective policy/provenance editor | Inheritance and locks affect allowed delivery | #74; Core #225 policy pattern | +| Campaign policy (`GlobalSettingsPage` policy view) | Inspect/override campaign policy | Effective policy/provenance editor | Inheritance, actor authority, and blocked edits | #74; Core #225 policy pattern | +| Review/send (`ReviewSendPage`) | Validate, build, mock-test, confirm/send, inspect results | Guided review/decision plus durable progress | External communication, partial effects, retries, evidence | Intervention vocabulary [#63](https://git.add-ideas.de/add-ideas/govoplan-campaign/issues/63); sync/async progress [#62](https://git.add-ideas.de/add-ideas/govoplan-campaign/issues/62) | +| Message and attachment detail overlays | Inspect one built/mock message and its attachment links | Stable detail/review dialog | Personal data, exact outbound content, reviewed state | Implement/verify [#59](https://git.add-ideas.de/add-ideas/govoplan-campaign/issues/59) and [#73](https://git.add-ideas.de/add-ideas/govoplan-campaign/issues/73) together | +| Campaign report (`CampaignReportPage`) | Filter and inspect delivery outcomes | Reporting/list-detail | Partial, failed, skipped, SMTP/IMAP outcomes and retries | Filtering [#65](https://git.add-ideas.de/add-ideas/govoplan-campaign/issues/65), dependent on [Core #263](https://git.add-ideas.de/add-ideas/govoplan-core/issues/263) | +| Audit (`CampaignAuditPage`) | Inspect campaign evidence/history | Provenance timeline/report | Actor/action/effect trace | #74 audit | +| JSON (`CampaignJsonView`) | Inspect expert representation | Advanced diagnostics/reference | Raw data may contain personal/configuration values; not a primary editor | #74 privacy/redaction audit | +| Create wizard (`CreateWizard`) | Seed a campaign through basics, sender, fields, recipients, template, attachments, review, send | Guided setup | Current steps mix creation and later consequential delivery; completion semantics need audit | Guided first campaign [#35](https://git.add-ideas.de/add-ideas/govoplan-campaign/issues/35) | +| Review/send wizard routes | Alternate guided review/send shells | Guided review | Tracked routes exist; implementation relationship to `ReviewSendPage` must be established, not guessed | #74 inventory decision | +| Operator queue (`OperatorQueuePage`) | Monitor jobs and intervene | Monitoring/work queue | Retry/pause/reconcile and system actor/effect evidence | #74, then #62 vocabulary | +| Top-level reports placeholder | Enter cross-campaign reports | Reporting | Component explicitly says functionality is prepared for later passes | Keep marked incomplete; do not infer parity with per-campaign report | +| Templates route (`TemplatesPage`) | Browse template records | Directory/list-detail | Template availability and later generated outputs | #74 audit; verify missing route guard intent | + +The five review stages currently named in code are `Validate and inspect`, +`Build and review`, `Mock send and verify`, `Confirm and send`, and `Delivery +results`. Campaign #63 owns the intervention and status vocabulary; Workflow is +not required to define or implement it. + +## Repositories Without A WebUI Route Contribution + +The following local repositories contain a backend manifest but no +`webui/src/module.ts` at this snapshot: + +`govoplan-approvals`, `govoplan-assets`, `govoplan-booking`, +`govoplan-certificates`, `govoplan-committee`, `govoplan-consultation`, +`govoplan-contracts`, `govoplan-dist-lists`, `govoplan-evaluation`, +`govoplan-facilities`, `govoplan-forms-runtime`, `govoplan-grants`, +`govoplan-helpdesk`, `govoplan-identity`, `govoplan-inspections`, +`govoplan-issue-reporting`, `govoplan-learning`, `govoplan-permits`, +`govoplan-poll`, `govoplan-procurement`, `govoplan-records`, +`govoplan-resources`, `govoplan-rest`, `govoplan-risk-compliance`, +`govoplan-soap`, `govoplan-tenancy`, and `govoplan-transparency`. + +This is only negative route evidence. It does not classify the backend module's +maturity or decide that it needs a WebUI. Connector-only, capability-only, or +backend-only modules may remain intentionally headless. + +## Rollout Matrix + +| Order | Scope | Current evidence | Target | Owner / issue | Verification gate | Status | +| --- | --- | --- | --- | --- | --- | --- | +| 0 | Product grammar and route inventory | Doctrine, ledger, layout rules, module contract, current route sources | One reconciled pattern language and evidence inventory | Meta [#11](https://git.add-ideas.de/add-ideas/govoplan/issues/11) | Docs links/diff checks; issue/wiki sync after integration | Initial slice in this document | +| 1 | Campaign baseline integration | Closed work and local WIP can differ from tracked baseline | Integrated, testable baseline before migration claims | Campaign #67 and tracker cleanup | Clean scoped diff, behavior tests, build, issue evidence | Must precede claiming Campaign migration complete | +| 2 | Campaign previews/details | Existing message/attachment overlays and known overflow/geometry issues | Stable header/body/footer, accessible long-content detail | Campaign #59 and #73 | Keyboard/focus/scroll behavior, long content, responsive and translated text | P1 ready | +| 3 | Campaign review/interventions | Five domain-owned stages with unresolved intervention language | Clear stages, outcomes, blockers, next actor/action, reviewed evidence | Campaign #63 | State matrix behavior/accessibility tests and agreed vocabulary | P1 needs product wording decision | +| 4 | Campaign send/progress | Synchronous/asynchronous behavior is not explicit enough | Pre-send mode/consequence plus durable leave/return progress, retry and reconciliation | Campaign #62 | Sync and async behavior, partial/failure/retry, reload/return tests | P1 ready after stage vocabulary | +| 5 | Campaign report filtering | Duplicate/inconsistent filter models are reported | One shared status/list/filter/count model | Campaign #65 and Core #263 | Query/filter behavior, keyboard, counts, large result set | P1 blocked on shared DataGrid direction | +| 6 | Guided first campaign | Existing wizard routes and ordinary workspace overlap | Task-oriented entry that hands off clearly to normal editing/review | Campaign #35 | First-run flow, resume/back, validation, optional modules, no implicit send | P1 after core pilot patterns stabilize | +| 7 | Prove/extract generic primitives | Core already exports many primitives; Campaign composition still unreviewed | Extract only contracts with a second consumer or clear platform ownership | Core #225 plus bounded follow-ups | Core behavior/accessibility tests and module-permutation tests | After Campaign proof | +| 8 | Configured-system pattern help | Docs route and classification exist | Role/config-aware pattern and route/field/blocker help | Docs #15 | Topic grouping, audience filtering, stable links/anchors | P1 after initial pattern IDs stabilize | +| 9 | Admin/configuration family | Phase inventory and connector primitives exist in the ledger | Apply the pattern to files, mail, policy, retention, packages, modules, API keys, settings | Core #225 and module children | Per-surface state/accessibility/consequence evidence | Parallel where independent of Campaign shared decisions | +| 10 | Remaining direct routes | Routes are contributed; most are unreviewed | Per-module bounded audit and migration plan | New module issues derived from this inventory | Applicable definition-of-done gates | P2 after Campaign, not a bulk rewrite | +| 11 | Manifest/runtime alignment | Several executable routes are absent from manifest metadata | Declared alignment or explicit validated exception | Core contract issue to create | Automated manifest/module route check and configured Docs verification | Discovery follow-up | + +Workflow/user-story implementation is postponed. It is not on the critical path +for rows 0 through 10. Focused views can be specified, manually selected, and +tested through core composition contracts; a later workflow step may become one +activation source without changing the proven surface patterns. + +## Inventory Maintenance + +When a route, nav item, named UI capability, host section, or Campaign workspace +surface changes: + +1. Update the owner, evidence, task, archetype, and consequence here. +2. Link the implementation issue and verification evidence. +3. Keep "unreviewed" until state, permission/privacy, consequence/provenance, + accessibility, responsive, theme, i18n, and applicable async behavior have + been checked. +4. Re-scan both `module.ts` and the backend manifest; do not infer one from the + other. +5. Recreate the inventory from a clean release lockfile before using it as + release evidence.