govoplan/docs/INTERFACE_SURFACE_INVENTORY.md

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.

Snapshot And Method

Snapshot refreshed: 2026-07-22.

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 commits are used as the integrated baseline. Dirty worktree changes are not treated as delivered behavior. The former Campaign recipient-editor and preview WIP is integrated in tracked commits; completed work is no longer described as a local exception.

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
/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
/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; #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; #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 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 recipient-data editor is now consolidated into the recipients section on remote main; Campaign #67 records the accepted and verified integration boundary.

Campaign already consumes core primitives including ModuleSubnav, Card, PageTitle, Button, LoadingFrame, DismissibleAlert, FormField, StatusBadge, MetricCard, DataGrid, TableActionGroup, 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; guided entry #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 remaining audit
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
Recipients (RecipientDataPage)	Select/import/map/edit recipients, address fields and per-recipient values/files	Import/mapping plus list-detail editor	Personal data, validation, bulk activation, file links	Consolidated editor delivered in #67; #74 remaining audit and guided entry #35
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
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, bounded synchronous execution, persisted queue mode, partial effects, retries, evidence	Bounded synchronous and explicit/persisted queued modes delivered in #62 and #79; #63 wording and #74 audit remain
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	Delivered and verified in #59 and #73
Campaign report (CampaignReportPage)	Filter and inspect delivery outcomes	Reporting/list-detail	Partial, failed, explicitly excluded/skipped, SMTP/IMAP outcomes and retries	Server-owned filtering and counts delivered in #65 with the full-result DataGrid contract from Core #263; excluded semantics in #66
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
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	Campaign/version/job identity, historical active-version discovery, fixed action positions, authority-aware disabled states, exact non-overlapping queue counts, server-paged jobs, bounded refresh, retry/queue/reconcile per version, campaign-wide pause/resume/cancel, and leave/return progress	Durable operator controls delivered in #78; #74 wording/accessibility audit remains
Aggregate reports (AggregateReportsPage)	Compare cross-campaign delivery outcomes	Privacy-preserving aggregate reporting	Tenant/campaign ACL, deployment/tenant small-cell policy, complementary and overlapping-cell suppression, explicit denominator, and no recipient detail/diagnostics/export/drill-down	Separate aggregate-reader surface delivered in #80; not parity with the permission-gated per-campaign detail 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	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 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	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)
7	Campaign aggregate reports	A separate aggregate-reader projection and UI expose only policy-suppressed business totals with a stable status domain	Explicit denominator and exclusions, deployment floor plus tenant-strengthened small-cell threshold, complementary and overlapping-cell suppression, no detail/export/diagnostics	Campaign #80	Aggregate query, cross-metric suppression, route/role/ACL, stable filter and UI structure tests	Complete 2026-07-22 (06125cc, fc36aee, 8ee87b7, ac3329c, 1225802)
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
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
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/user-story implementation is postponed. It is not on the critical path for this rollout matrix. 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.