docs: define the interface pattern language

2026-07-20 16:49:30 +02:00
parent 05ae81d641
commit 9e7103f613
3 changed files with 636 additions and 0 deletions
--- 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.
--- a/docs/INTERFACE_PATTERN_LANGUAGE.md
+++ 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.
--- a/docs/INTERFACE_SURFACE_INVENTORY.md
+++ 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.