govoplan/docs/architecture/PRODUCT_EXPERIENCE_AND_MODULE_BOUNDARIES.md

Product Experience and Module Boundaries

Problem

GovOPlaN's runtime modularity is a strength, but the implementation structure is exposed too directly in the product. Ordinary users encounter module names, one top-level route per module, one navigation item per repository, package and provider identifiers, and errors framed as missing modules. This makes the system look like a toolbox of adjacent applications instead of one operating environment for institutional work.

The correction is not a monolithic frontend and not hidden provenance. It is a separate product information architecture assembled from typed module contributions.

Implementation is tracked in Core #283. The accepted configurable product-area and task-local tool design is defined in Quick Access And Product Areas.

Current Exposure Inventory

Surface	Direct exposure	Appropriate audience	Product-facing alternative
Side rail	One icon and route for many installed modules	Administrators and power users	Work areas, services, inboxes, records, communication, data and assurance
Route paths	Technical owners such as /dataflow, /forms, or /postbox	Deep links and diagnostics	Stable product aliases and journey routes that resolve to owner surfaces
Dashboard	Installed module count and module-owned widget library	Operators	Outcome, obligation, work, exception, and service widgets
Administration	Package names, database state, capabilities, providers	Module and system administrators	Guided product/package configuration with technical details on demand
Errors	"Module/capability not installed"	Diagnostics	Explain the unavailable outcome, responsible administrator, and enabling path
Documentation	Topics grouped primarily by module	Administrators	Task, role, service, and object documentation with module provenance secondary
Permissions	Module-namespaced scopes	Access administrators	Human-readable responsibility bundles; exact scopes remain inspectable
Search	Provider/module as a result facet	Advanced filtering	Object type, institution, time, purpose, case/service, and source authority
Workflow	Steps can expose target route/module details	Workflow designers	User-facing action and expected result; technical binding in definition details
Connector state	Provider IDs and source types	Integration owners	Named source, authority, freshness, health, last effect, and recovery state

Boundary Decision

Three layers remain distinct:

1. Technical module layer: package ownership, dependencies, capabilities, permissions, migrations, routes, and provider identifiers.
2. Product composition layer: work areas, object types, journeys, commands, inboxes, configuration packages, and role-based defaults.
3. Presentation projection: active view, tenant policy, current task, temporal context, language, accessibility preferences, and device layout.

Modules own implementation and contribute typed product metadata. Core assembles it. Views filters it. Policy constrains it. Access authorizes the underlying actions. No consumer imports another optional module's UI directly.

Product Surface Contract

Each WebUI module should be able to announce:

• product_areas: stable areas to which a route, command, widget, or object belongs;
• object_types: user-facing nouns, icons, search context, detail route, and owner provenance;
• work_item_sources: open work, exceptions, deadlines, and responsible capacity;
• journey_actions: launch, resume, review, correct, decide, publish, and reconcile commands;
• workspace_surfaces: embeddable but owner-rendered list, detail, editor, and status surfaces;
• configuration_contributions: guided settings with consequence and prerequisite metadata;
• help_contexts: user/admin documentation for the product identity as well as the technical owner;
• technical_provenance: module, interface version, capability, and provider identifiers shown only in details and evidence.

The contract references surfaces. It does not permit Core or a product package to import their implementation.

The versioned product_surfaces slice is implemented in Core. It binds a stable product identity and entry path to one or more owner routes, View surfaces, presentations, capabilities, search sources, help contexts and documentation topics. It also carries standard unavailable/degraded explanations and migration aliases. Mail and Postbox contribute the first shared identity, communication.messages: /messages and the migration alias /inbox select the first currently authorized, View-visible owner while the underlying /mail and /postbox deep links, custody and permissions remain unchanged. Tasks, Calendar and Files contribute the corresponding single-owner identities:

Product identity	Stable destination	Compatible owner route
Work	/work	/tasks
Calendar	/agenda	/calendar
Messages	/messages (/inbox alias)	/mail, /postbox
Files	/documents	/files

Core replaces those owner entries in the ordinary rail with the stable product destinations. A collapsed All available tools catalogue retains every authorized technical owner route independently of View focus; unauthorized entries are never disclosed. The original deep links remain valid, and all contributing owner paths keep the corresponding product entry active. Alias resolution emits a bounded client telemetry event before the redirect.

Core's ProductAvailabilityState is the shared presentation primitive for authorization, Policy, configuration, disabled, missing-capability, offline and provider-degraded states. Product language is primary; exact module, capability, provider and correlation provenance is available only in an expandable technical section.

Navigation Model

The default shell should prioritize:

1. global search and create/resume commands;
2. personal and function-bound work;
3. configured product areas;
4. pinned user destinations;
5. administration and technical module inspection when authorized.

The baseline product areas are Work, Services and Cases, Records and Documents, Communication, Meetings and Decisions, Data and Assurance, and People and Responsibility. They are configurable system/tenant defaults and Views projections, not hard-coded repository groups. Empty areas disappear; single-destination areas may link directly; familiar tools may remain pinned.

The complete permission-derived module rail is available as the collapsed All available tools escape. It is deliberately independent of the active View while still enforcing authorization. Its ability to scroll is useful and is not itself the product defect. The defect is requiring people to infer a task or outcome from repository topology.

Task-local Work, Calendar, Messages and Files tools may be contributed to the optional govoplan-quick-access rail. Messages composes Mail, Postbox and future governed chat presentation without merging their channel semantics or state.

A module route remains a valid deep link. A product area may combine links and owner-rendered surfaces from several modules. When a required contribution is absent, the area explains the missing outcome rather than rendering a broken placeholder.

Views remain the projection mechanism. They may select product areas, routes, sections, commands, widgets, and fields. A view must not grant a permission or change data semantics. Policy can force, allow, or prohibit a surface at system, tenant, group, or user scope.

Core browser conformance exercises the German Anwohnerparkausweis reference context with Work, Calendar, Messages and Files entries, verifies that package owner labels are absent from the primary rail, expands the technical catalogue, and runs WCAG 2 A/AA checks over the result. Unit permutations cover two-owner, one-owner, unauthorized-owner and focused-View compositions.

Error And Provenance Language

Normal errors answer:

• what the person was trying to achieve;
• why it is unavailable or failed;
• whether data was saved or an external effect may have occurred;
• who can resolve it and where;
• the correlation/evidence reference.

An expandable technical section may then identify the module, capability, provider, request, and version. This keeps the product intelligible without hiding operational truth.

Migration

Core's product-area and Quick Access contracts, the optional Quick Access module, the first five providers and immutable View presentation revisions are implemented. The migration below now concerns broader classification and product-language adoption; it is not a prerequisite for safely enabling the first rail slice.

Slice 1: inventory and aliases

• continue classifying every route, navigation item, widget, setting, search object, and help context by product area and object type;
• extend the implemented product-surface aliases without removing existing deep links;
• flag raw module IDs in ordinary-user labels and errors.

Slice 2: work-first shell

• provide a generic work/exception/deadline aggregation capability;
• make work areas and configured packages the default navigation;
• move the complete module catalogue to administration and an optional power- user surface.
• implement the configurable Quick Access rail through Core-mediated contributions, system/tenant/user resolution and View/Policy ceilings.

Slice 3: composite journeys

• let product packages define journey launch/resume actions and default views;
• let Workflow Engine activate a view and focus an owner surface without controlling authorization;
• expose provider provenance and technical bindings on demand.

Slice 4: enforceability

• make product classification mandatory for user-visible manifest surfaces;
• reject duplicate product identities and missing owner routes in CI;
• add browser tests proving that reference users can complete a journey without knowing module names.

Acceptance Criteria

• An ordinary user can describe every primary navigation item as work or an institutional object, not as a package.
• A product package can remove irrelevant navigation while retaining deep-link and help integrity.
• Missing optional modules produce an actionable product explanation.
• Administrators can still inspect exact module, capability, provider, schema, and evidence provenance.
• Module permutation tests prove that no product surface assumes an optional owner is installed.