# 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](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/283).
The accepted configurable product-area and task-local tool design is defined
in [Quick Access And Product Areas](QUICK_ACCESS_AND_PRODUCT_AREAS.md).

## 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.