diff --git a/docs/INTERFACE_SURFACE_INVENTORY.md b/docs/INTERFACE_SURFACE_INVENTORY.md index e2e7ba6..58da310 100644 --- a/docs/INTERFACE_SURFACE_INVENTORY.md +++ b/docs/INTERFACE_SURFACE_INVENTORY.md @@ -17,6 +17,13 @@ interpretation and rollout ledger; generated evidence does not replace it. Snapshot refreshed: 2026-08-03. +The generated snapshot contains 65 module manifests, 35 WebUI-contributing +repositories, 40 statically declared module routes, 1,156 UI fields, and 836 +backend endpoints. All backend endpoints are classified and no stale endpoint +declarations were found. The 234 endpoints without a static WebUI reference are +kept visible as review evidence; they may intentionally serve workers, public +clients, connectors, or external integrations. + Evidence was read from tracked Git `HEAD` in the local GovOPlaN checkouts: - core routes and fallback behavior in `govoplan-core/webui/src/App.tsx` @@ -60,28 +67,45 @@ Inventory states: ## 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. +The access column summarizes only the route-level declaration in `module.ts`. +Inner APIs and controls may impose additional checks. Public and compatibility +routes are called out explicitly because they do not have the same manifest +semantics as authenticated navigation routes. -| 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/GovOPlaN/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/GovOPlaN/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` | `campaigns:campaign:read` and any of queue, control, retry, or reconcile | Monitor and intervene in campaign jobs through authority-specific controls | Monitoring/work queue | Pilot; durable queue controls delivered in [Campaign #78](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/78); #74 audit remains | -| `/reports` | `govoplan-campaign` `AggregateReportsPage` | `campaigns:report:read` | Compare privacy-protected cross-campaign outcome totals without recipient detail, diagnostics, export, or drill-down | Aggregate reporting | Pilot; aggregate-reader surface delivered in [Campaign #80](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/80); #74 audit remains | -| `/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/GovOPlaN/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 | +| Routes | Owner | Route-level access | Primary archetype | Migration issue | +| --- | --- | --- | --- | --- | +| `/admin` | Access | Any declared administration/read scope | Administration/configuration host | [Access #19](https://git.add-ideas.de/GovOPlaN/govoplan-access/issues/19), [Core #225](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/225) | +| `/address-book` | Addresses | `addresses:contact:read` | Directory/list-detail | [Addresses #23](https://git.add-ideas.de/GovOPlaN/govoplan-addresses/issues/23) | +| `/approvals` | Approvals | `approvals:workspace:read` | Work queue/guided decision | [Approvals #3](https://git.add-ideas.de/GovOPlaN/govoplan-approvals/issues/3) | +| `/calendar` | Calendar | `calendar:event:read` | Calendar/list-detail | [Calendar #22](https://git.add-ideas.de/GovOPlaN/govoplan-calendar/issues/22) | +| `/campaigns`, `/campaigns/:campaignId/*`, `/campaigns/queue`, `/campaigns/reports`, `/templates` | Campaign | Campaign read/report/control scopes; template route has no route guard | List-detail, guided review, monitoring, reporting | [Campaign #74](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/74) | +| `/operator` | Campaign | Campaign read plus queue/control scope | Compatibility redirect to `/campaigns/queue` | Campaign #74; retire under the compatibility policy | +| `/cases`, `/cases/:caseId` | Cases | `cases:case:read` | List-detail/case workspace | [Cases #4](https://git.add-ideas.de/GovOPlaN/govoplan-cases/issues/4) | +| `/committee` | Committee | `committee:workspace:read` | Governed workspace | [Committee #2](https://git.add-ideas.de/GovOPlaN/govoplan-committee/issues/2) | +| `/dashboard` | Dashboard | No route-specific scope | Dashboard | [Dashboard #3](https://git.add-ideas.de/GovOPlaN/govoplan-dashboard/issues/3) | +| `/dataflow` | Dataflow | Pipeline read/admin | Graph editor/execution evidence | [Dataflow #20](https://git.add-ideas.de/GovOPlaN/govoplan-dataflow/issues/20) | +| `/datasources` | Datasources | Catalogue read/source admin | Directory/configuration | [Datasources #7](https://git.add-ideas.de/GovOPlaN/govoplan-datasources/issues/7) | +| `/distribution-lists` | Distribution Lists | List read/write/admin | Directory/list-detail | [Distribution Lists #8](https://git.add-ideas.de/GovOPlaN/govoplan-dist-lists/issues/8) | +| `/docs` | Docs | Documentation or settings read | Documentation/reference | [Docs #15](https://git.add-ideas.de/GovOPlaN/govoplan-docs/issues/15) | +| `/files` | Files | `files:file:read` | Directory/explorer | [Files #42](https://git.add-ideas.de/GovOPlaN/govoplan-files/issues/42) | +| `/forms` | Forms | `forms:definition:read` | Definition library/editor | [Forms #4](https://git.add-ideas.de/GovOPlaN/govoplan-forms/issues/4) | +| `/forms-runtime`, `/forms-runtime/:instanceId` | Forms Runtime | Participate or workspace read | Guided form execution | [Forms Runtime #5](https://git.add-ideas.de/GovOPlaN/govoplan-forms-runtime/issues/5) | +| `/idm` | IDM | Assignment, function-change, relationship, or organization scopes | Directory/governed change | [IDM #12](https://git.add-ideas.de/GovOPlaN/govoplan-idm/issues/12) | +| `/mail`, `/mail/bounces` | Mail | Mailbox or bounce read/manage | Inbox/list-detail/monitoring | [Mail #20](https://git.add-ideas.de/GovOPlaN/govoplan-mail/issues/20) | +| `/notifications` | Notifications | `notifications:notification:read` | Inbox/list-detail | [Notifications #4](https://git.add-ideas.de/GovOPlaN/govoplan-notifications/issues/4) | +| `/ops` | Ops | Operations or settings read | Monitoring/evidence | [Ops #4](https://git.add-ideas.de/GovOPlaN/govoplan-ops/issues/4) | +| `/organizations` | Organizations | Model/unit/function or settings read | Directory/hierarchy editor | [Organizations #7](https://git.add-ideas.de/GovOPlaN/govoplan-organizations/issues/7) | +| `/portal` | Portal | `portal:service:read` | Service portal | [Portal #2](https://git.add-ideas.de/GovOPlaN/govoplan-portal/issues/2) | +| `/postbox` | Postbox | `postbox:postbox:read` | Inbox/list-detail | [Postbox #26](https://git.add-ideas.de/GovOPlaN/govoplan-postbox/issues/26) | +| `/projects` | Projects | `projects:project:read` | List-detail/project workspace | [Projects #2](https://git.add-ideas.de/GovOPlaN/govoplan-projects/issues/2) | +| `/reporting`, `/reports` | Reporting | `reporting:definition:read` | Reporting/definition library | [Reporting #8](https://git.add-ideas.de/GovOPlaN/govoplan-reporting/issues/8) | +| `/risk-compliance` | Risk Compliance | Workspace or sanctions read | Governed work queue/evidence | [Risk Compliance #8](https://git.add-ideas.de/GovOPlaN/govoplan-risk-compliance/issues/8) | +| `/scheduling` | Scheduling | `scheduling:schedule:read` | List-detail/guided decision | [Scheduling #8](https://git.add-ideas.de/GovOPlaN/govoplan-scheduling/issues/8) | +| `/scheduling/public/:requestId/:token` | Scheduling | Public signed token | Public participation | Scheduling #8 | +| `/search` | Search | `search:result:read` | Search overlay/results | [Search #4](https://git.add-ideas.de/GovOPlaN/govoplan-search/issues/4) | +| `/templates` | Templates | Template read/write/publish/render/admin | Definition library/editor | [Templates #5](https://git.add-ideas.de/GovOPlaN/govoplan-templates/issues/5) | +| `/voting` | Voting | `voting:ballot:read` | Governed ballot workspace | [Voting #1](https://git.add-ideas.de/GovOPlaN/govoplan-voting/issues/1) | +| `/workflow` | Workflow | Definition read or instance admin | Graph editor/execution evidence | [Workflow #15](https://git.add-ideas.de/GovOPlaN/govoplan-workflow/issues/15) | ## Manifest And Runtime Route Alignment @@ -91,28 +115,27 @@ loading reason about the configured interface without executing module UI code. 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 | +The generated comparison is aligned for all authenticated canonical routes. +Two deliberate exceptions remain visible: -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. +- Campaign contributes `/operator` as a compatibility redirect for saved View + projections; its canonical and manifest-declared destination is + `/campaigns/queue`. +- Scheduling contributes `/scheduling/public/:requestId/:token` through the + separate `publicRoutes` contract. Authenticated manifest routes intentionally + do not describe public signed-token entry points yet. + +Admin, Audit, Policy, Tenancy, and Views contribute composed administration or +settings surfaces rather than direct routes. Their migration issues are +[Admin #8](https://git.add-ideas.de/GovOPlaN/govoplan-admin/issues/8), +[Audit #8](https://git.add-ideas.de/GovOPlaN/govoplan-audit/issues/8), +[Policy #11](https://git.add-ideas.de/GovOPlaN/govoplan-policy/issues/11), +[Tenancy #6](https://git.add-ideas.de/GovOPlaN/govoplan-tenancy/issues/6), and +[Views #2](https://git.add-ideas.de/GovOPlaN/govoplan-views/issues/2). + +Release evidence must continue to run the generated inventory and manifest +shape checks so new executable routes, public routes, aliases, and composed +surfaces cannot silently diverge from their declared metadata. ## Composed Surfaces And Extension Points @@ -182,24 +205,26 @@ The five review stages currently named in code are `Validate and inspect`, results`. Campaign #63 owns the intervention and status vocabulary; Workflow is not required to define or implement it. -## Repositories Without A WebUI Route Contribution +## Repositories Without A WebUI Package -The following local repositories contain a backend manifest but no -`webui/src/module.ts` at this snapshot: +The generated manifest snapshot reports no WebUI package for: -`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-tickets`, `govoplan-learning`, `govoplan-permits`, -`govoplan-poll`, `govoplan-procurement`, `govoplan-records`, -`govoplan-resources`, `govoplan-rest`, `govoplan-risk-compliance`, -`govoplan-soap`, `govoplan-tenancy`, and `govoplan-transparency`. +`govoplan-assets`, `govoplan-booking`, `govoplan-certificates`, +`govoplan-connectors`, `govoplan-consultation`, `govoplan-contracts`, +`govoplan-decisions`, `govoplan-encryption`, `govoplan-evaluation`, +`govoplan-facilities`, `govoplan-grants`, `govoplan-helpdesk`, +`govoplan-identity`, `govoplan-identity-trust`, `govoplan-inspections`, +`govoplan-learning`, `govoplan-mandates`, `govoplan-parties`, +`govoplan-permits`, `govoplan-poll`, `govoplan-procurement`, +`govoplan-records`, `govoplan-resources`, `govoplan-rest`, +`govoplan-services`, `govoplan-soap`, `govoplan-tickets`, +`govoplan-transparency`, `govoplan-wiki`, and `govoplan-workflow-engine`. -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. +Tenancy does provide composed administration surfaces despite having no direct +route. This section is only negative package evidence; connector-only, +capability-only, runtime-only, and backend-only modules may intentionally remain +headless. A new WebUI should be created only for a concrete user task, not to +make every module symmetrical. ## Rollout Matrix @@ -208,7 +233,7 @@ backend-only modules may remain intentionally headless. | 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/GovOPlaN/govoplan/issues/11) | Docs links/diff checks; issue/wiki sync after integration | Initial slice in this document | | 1 | Campaign baseline integration | Recipient-editor WIP and tracker state have been reconciled with remote `main` | Integrated, testable baseline before migration claims | Campaign #67 and tracker cleanup | Backend and focused WebUI suites; issue evidence | Complete 2026-07-22 | | 2 | Campaign previews/details | Stable shared dialog with bounded scrolling and fixed responsive preview workspace | Stable header/body/footer, accessible long-content detail | Campaign #59 and #73 | Review-preview and overlay structure tests | Complete 2026-07-22 | -| 3 | Campaign review/interventions | Five domain-owned stages use central blocker and guided-review primitives; validation/build warnings name action, actor, and destination; hard blockers, individual review, and group review remain distinct; reviewed/remaining counts survive reload through build-bound review evidence | Clear stages, outcomes, blockers, next actor/action, reviewed evidence | Campaign #63 | `reviewProgress` state tests, shared-component structure contract, TypeScript build, configured-system help topic, and Campaign documentation tests | Complete 2026-08-03 (`1d6c745`; Core primitive `70fc6da`) | +| 3 | Campaign review/interventions | Five domain-owned stages use central blocker and guided-review primitives; validation/build warnings name action, actor, and destination; hard blockers, individual review, and group review remain distinct; reviewed/remaining counts survive reload through build-bound review evidence | Clear stages, outcomes, blockers, next actor/action, reviewed evidence | Campaign #63 | `reviewProgress` state tests, shared-component structure contract, TypeScript build, configured-system help topic, and Campaign documentation tests | Complete 2026-08-03 (`d635f3a`; Core primitives and contextual help `b823a22`) | | 4 | Campaign send/progress | A hard deployment ceiling bounds synchronous delivery; the selected synchronous, worker-queue, or database-queue mode is explicit and persisted; progress and recovery survive navigation; immediate-send response and audit evidence are allowlisted | Pre-send mode/consequence plus durable leave/return progress, retry and reconciliation without recipient/provider leakage | Campaign #62 and #79 | Boundary/concurrency/preflight, async selection, persisted mode, sanitized response/audit, partial/failure/retry and reload/return tests | Complete 2026-07-22 (`7e16603`, `60efd1c`, `62a6879`, `b0282eb`, `f095a3e`) | | 5 | Campaign report filtering | Core DataGrid distinguishes client/full-result from server-owned queries; Campaign applies filter/sort/count before pagination and synchronizes count shortcuts with the grid query | One shared server-owned status/list/filter/count model | Campaign #65 and Core #263 | DataGrid contract/build tests plus exact shortcut/query/filter/count and large-result behavior | Complete 2026-07-22 (`e6062fe`, `cece71d`, `aa4ec66`, `4eb651c`) | | 6 | Campaign operator recovery | A durable campaign/version queue page exposes historical work, exact non-overlapping state counts, persisted mode, permission-safe controls, server-paged job evidence, bounded refresh and active-state recovery | Fixed-position actions, disabled explanations, leave/return state, version-scoped retry/queue/reconcile and explicit campaign-wide pause/resume/cancel | Campaign #78 | Queue model/structure, historical-version, permission, paging, recovery-control, stale-response and delta tests | Complete 2026-07-22 (`21f3014`, `99d44ee`, `735e874`) | @@ -216,9 +241,9 @@ backend-only modules may remain intentionally headless. | 8 | Campaign excluded outcomes | Excluded build rows become explicit skipped transport outcomes and remain protected from queue/cancel/retry ambiguity | One durable source-to-job-to-report meaning with guarded historical normalization | Campaign #66 | Builder/persistence, migration, query/count, queue-control and report-explanation tests | Complete 2026-07-22 (`7229fb8`) | | 9 | 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 | | 10 | 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 | -| 11 | 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 | +| 11 | Configured-system pattern help | Role/config-aware workflow, reference, pattern, and system topics are projected by Docs; shared route, field, blocker, and action links resolve to configured Docs or the hosted fallback | Stable configured-system guidance without feature-to-Docs imports | Docs #15 | Docs suite, shared component tests, Campaign review tests, 46 module permutations, full-product bundle budget | Complete 2026-08-03 (Docs `abe2f78`; Core `b823a22`; Campaign `d635f3a`) | | 12 | 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 | -| 13 | 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 | +| 13 | Remaining module surfaces | 33 bounded module-owned issues now cover every WebUI contributor not already tracked by Campaign #74 or completed Docs #15 | Per-module audit and migration, ordered by user task and consequence rather than a bulk rewrite | Issues linked in the direct-route and composed-surface sections | Module-focused tests, manifest shapes, contextual Docs, and applicable definition-of-done gates | Ready; Scheduling and admin/configuration are the first implementation slices | | 14 | 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 remains outside this rollout matrix because it has its own runtime and