govoplan/docs/architecture/QUICK_ACCESS_AND_PRODUCT_AREAS.md

Quick Access And Product Areas

Purpose

GovOPlaN presents institutional work without requiring ordinary users to understand the installed package graph. Two complementary projections provide that experience:

• product areas group destinations, objects, work and actions by the outcome a person recognizes;
• Quick Access keeps a small set of task-local tools available without leaving the current page, case, record or Workflow context.

Technical modules remain the implementation, release and provenance boundary. Product areas and Quick Access are presentation contracts over those owners; they do not copy domain state or bypass authorization.

Implementation is tracked by Core #283 and #285, GovOPlaN's product-experience umbrella, Views, Policy and govoplan-quick-access.

The repository and product name is govoplan-quick-access, with module id quick_access. govoplan-qar was rejected because the abbreviation hides the purpose in package catalogues, diagnostics, permissions and operations.

Implementation Status

The first production-shaped slice is implemented:

• Core validates and publishes versioned product_areas and quick_access_tools manifest contracts;
• govoplan-quick-access derives its live catalogue from installed modules, persists optimistic-concurrency-protected system, tenant and user profiles, and resolves blocked, forced, ordered and stale preferences;
• the shell hosts the optional right rail and one composed drawer with keyboard dismissal, focus return, responsive mobile behavior and full-page fallbacks;
• Tasks, Calendar, Mail, Postbox and Files contribute the first owner-rendered tools; Mail and Postbox remain separate sections inside Messages;
• immutable View revisions now carry grouped/flat navigation, product-area order and optional labels. Scoped Views therefore configure product presentation for system, tenant, group, user and Workflow contexts;
• the expanded left rail groups classified destinations while retaining Dashboard and every authorized unclassified destination under More tools;
• Core promotes Work (/work), Calendar (/agenda), Messages (/messages) and Files (/documents) into stable primary destinations and collapses the compatible owner routes under All available tools;
• All available tools is permission-derived but independent of the active View, providing a deliberate escape without granting access or discarding the original /tasks, /calendar, /mail, /postbox and /files links.

The baseline classification and the four initial stable destinations are now manifest-declared. The area classification covers every ordinary user-facing module and is enforced by the workspace manifest check. A separately versioned launch-context contract carries bounded active-object, acting, temporal, View and return references into full-page Quick Access fallbacks; Cases publishes the first active-object reference. The remaining rollout is to add useful bounded tools and active-object publishers only where a maintained journey benefits. The pinned German Anwohnerparkausweis browser composition verifies stable product labels, technical escape, keyboard access and WCAG conformance. Authorized global and technical routes remain visible through their dedicated shell entry or All available tools.

Quick Access Boundary

Core owns a versioned contribution contract. Feature modules may register a tool when they have a useful bounded surface. They do not import Quick Access. govoplan-quick-access owns configuration, effective resolution, ordering, the right-side rail and its drawer. Views may narrow tools for the current task. Policy may constrain availability and customization. Access and each owner's backend remain authoritative.

The initial categories are:

Category	Typical contributions
Work	Explicit Tasks, Workflow handoffs, approvals, deadlines and exceptions
Calendar	Today/upcoming agenda, event creation and scheduling launch
Messages	Mail, function-bound Postbox messages and future governed chat providers
Files	Contextual/recent files, attachment selection and upload

Messages is one shell category but not one data model. Mail, Postbox and future chat providers retain their channel semantics, custody, policy, audit and delivery behavior. The drawer identifies the channel where that distinction matters.

Contribution Contract

A Quick Access contribution declares:

• contract version 1, a stable id, category and human label;
• icon, order and optional badge/summary provider;
• required permissions and optional dependencies;
• global or active-object availability, accepted context-reference kinds and produced result-reference kinds;
• an owner-rendered bounded WebUI surface and full-page fallback route;
• View surface, help context and availability explanation;
• whether the contribution supports preview, create, select or resume.

The shell passes only bounded references: tenant, acting context, temporal read context, active task/Workflow, current institutional object, selected resources and a safe return location. The owner reauthorizes every read and effect. Credentials, protected content and permission decisions are never embedded in launch context.

Launch-context version 2 identifies reference contract version 1 and carries the exact resolved View revision plus optional recommended and focused tool ids. Recommendations affect order and emphasis only. Focus narrows the rail only when at least one focused contribution survives module enablement, configuration, context compatibility and authorization; otherwise the normal effective rail remains available. Workflow gets the same behavior by resolving the exact View revision instead of acquiring separate presentation authority.

An owner-rendered tool explicitly returns result contract version 1 as either completed with an action and typed owner reference, or cancelled with a reason. The shell correlates the result with the source and tool, rejects cross-tenant or undeclared reference kinds, and does not interpret closing the drawer as completion. Owner modules validate, persist, recover and audit their own effects. The overlay leaves the host route mounted, so unsaved host-page state is preserved; the full-page route remains the bounded-work fallback.

Effective Configuration

The effective rail is resolved from:

1. installed and enabled modules and their registered contributions;
2. system availability, forced entries and ordering defaults;
3. tenant availability, forced entries and ordering defaults;
4. group and user View/Policy ceilings where configured;
5. the user's enabled categories, entries and ordering;
6. the active View and optional Workflow-step narrowing overlay;
7. current authorization and contribution availability.

Lower scopes may narrow or reorder allowed entries but cannot enable a tool blocked above them. A forced entry cannot be removed below its source. User configuration stores stable contribution ids; unavailable or retired ids are retained as explained stale preferences without rendering broken controls.

Configuration screens derive their available choices from the live registry. Installing or enabling a contributing module adds its permitted choices; disabling it removes the runtime tool while preserving harmless preferences. If Quick Access is absent, contributors behave exactly as before.

Interaction Model

Desktop uses a narrow right-side rail with at most four initial category buttons and an overflow when an administrator or user adds more categories. Selecting a category opens one fixed, owner-neutral drawer. Contributions are shown inside that drawer as tabs, sections or commands according to the category contract. The default drawer overlays content so DataGrid and fixed workspace layouts do not resize unexpectedly; a later explicit pinned mode may reserve layout width on sufficiently wide screens.

The drawer preserves host-page state, has a deterministic focus return, closes with Escape, supports keyboard traversal, and provides explicit completion, cancellation and full-page actions. Mobile and narrow layouts use the same category/configuration semantics in a bottom sheet or compact menu.

Product Areas

Product areas are stable configurable identities, not repositories. The recommended baseline is:

• Work;
• Services and Cases;
• Records and Documents;
• Communication;
• Meetings and Decisions;
• Data and Assurance;
• People and Responsibility.

Modules contribute routes, objects, actions, widgets, work sources and help to one or more areas. Product packages and administrators may define sensible system and tenant defaults. Views select, order, rename or narrow allowed areas, and users may personalize them within Policy ceilings. An empty area is omitted. An area with one destination may open it directly. A multi-destination area provides a useful work/recent/action surface rather than another menu.

Familiar product nouns such as Calendar or Files remain direct product destinations. The objective is not to hide every implementation name from administrators; it is to prevent repository topology from determining a person's workflow.

The initial module classification is deliberately outcome-oriented:

Product area	Contributing user-facing modules
Work	Approvals, Projects, Tasks, Workflow
Services and Cases	Cases, Forms, Forms Runtime, Portal
Records and Documents	Files, Records, Templates
Communication	Campaigns, Distribution Lists, Mail, Notifications, Postbox
Meetings and Decisions	Calendar, Committee, Scheduling, Voting
Data and Assurance	Dataflow, Datasources, Reporting, Risk Compliance
People and Responsibility	Address Book, IDM, Organizations

Dashboard, Search, Documentation and Quick Access remain global shell affordances. Access, Administration, Audit, Encryption, Identity Trust, Operations, Policy, Tenancy and Views remain administrative or platform surfaces available through their dedicated entry point or All available tools. The manifest-shape check enforces both this explicit exception set and the shared label, icon, description and ordering of every canonical area.

Full Access And Provenance

The existing permission-derived module rail remains available as All available tools for power users and deliberate escape from a focused View. It contains only currently authorized destinations. Technical module, capability, provider and package provenance remains visible in administration, diagnostics, evidence and expandable details.

Search, deep links and help distinguish three states:

• available in the active View;
• authorized but outside the active View, with a temporary escape or View switch;
• unavailable because of authorization, Policy, configuration or a missing capability, with an actionable explanation.

Delivery Order

1. Define Core product-area and Quick Access contracts and validation.
2. Implement govoplan-quick-access configuration, effective resolution and shell capability.
3. Contribute Work, Calendar, Messages and Files bounded surfaces.
4. Add configurable product-area defaults through Views and product packages.
5. Migrate navigation, breadcrumbs, search, errors, documentation, dashboard and administration toward product terminology.
6. Prove keyboard, focus, responsive, optional-module and reference-journey behavior before making it the ordinary-user default.

Acceptance Criteria

• A user can configure allowed Quick Access categories and ordering without gaining authority.
• System and tenant administrators can make entries available, forced or unavailable with provenance.
• Mail, Postbox and another future channel can share Messages presentation while retaining independent state and channel semantics.
• A reference journey can use a bounded tool and return without losing host state or Workflow context.
• Product areas remain useful under sparse and rich permission sets and under optional-module permutations.
• All available tools and technical provenance remain deliberately reachable.