govoplan/docs/VIEWS_ARCHITECTURE.md

GovOPlaN Views Architecture

Purpose

GovOPlaN Views are governed presentation projections for a task, responsibility, or workflow step. A View can reduce the visible modules, navigation entries, routes, page sections, and commands to the interface needed for the current job.

Views are optional. If govoplan-views is not installed or enabled, the normal permission-derived interface remains unchanged.

Security Boundary

A View is not an authorization mechanism.

• Access, tenant isolation, resource guards, and backend permission checks remain authoritative.
• A View may hide an interface surface that the actor is otherwise allowed to use.
• A View can never expose a route, action, tenant, or resource that normal authorization denies.
• An authorized deep link outside the current View should offer an explicit temporary escape or View switch. It must not be presented as a permission denial.

This boundary lets Views improve focus without creating a second, weaker RBAC system.

Ownership

Core owns the versioned, module-neutral surface contract and WebUI runtime hooks. Modules declare stable surfaces and use shared hooks to respect the effective projection. Modules do not import govoplan-views.

govoplan-views owns:

• draft and immutable published View revisions
• system, tenant, group, and user assignments
• default, mandatory, and user-selectable Views
• active per-user View state
• effective projection resolution and provenance
• the View editor, preview, validation, and stale-surface diagnostics

Policy optionally owns inherited ceilings and explainable decisions. Workflow optionally references a pinned View revision for an instance or step and may narrow it further.

Surface Contract

Modules announce only useful, semantic surfaces:

• module
• navigation item
• route or workspace
• section or panel
• command or action

Each descriptor has a stable namespaced id, parent id, kind, label, default visibility, ordering, and dependency metadata where needed. Surface ids are public module contracts, not CSS selectors, component paths, or arbitrary DOM fragments.

The first release supports visible or hidden. Read-only states, layout replacement, visual emphasis, and arbitrary styling are separate concerns and are deferred.

Effective Resolution

The effective interface is the intersection of:

1. installed and enabled modules
2. actor permissions and resource access
3. administrator and Policy ceilings
4. an assigned or user-selected View
5. an optional workflow instance or step overlay

Lower scopes and workflow overlays may narrow inherited visibility but cannot broaden it. Every inherited, locked, hidden, unavailable, or stale choice should carry provenance that the editor and runtime can explain.

Published View revisions are immutable. Active workflow instances pin the revision they use. Unknown or retired surface ids produce diagnostics rather than breaking startup. If no valid effective View can be resolved, the system uses the last valid projection or the normal authorized interface and reports the configuration problem to administrators.

Workflow Behavior

A workflow definition may reference a View for the whole instance or a particular step. Starting, resuming, or advancing the workflow activates the appropriate projection. Users can intentionally leave focused mode and return from an open-work widget or notification without losing workflow state.

Module handoffs carry the workflow and View context through Core contracts. Workflow does not import the target module or the Views implementation.

Delivery Order

1. Define the Core surface registry and runtime hooks.
2. Initialize govoplan-views and persist versioned definitions.
3. Add assignment, selection, resolution, provenance, and the editor.
4. Add Policy inheritance and administrator ceilings.
5. Add Workflow instance and step activation.
6. Adopt semantic section/action descriptors module by module.

Implementation Status

Implemented in the initial Views slice:

• Core contract version 1, stable module/navigation/route identifiers, custom section/action descriptors, manifest validation, and platform API metadata
• shell navigation, route-boundary, settings, administration, dashboard-widget, embedded-capability, and organization-action filtering
• govoplan-views definitions, immutable revisions, system/tenant/group/user assignments, user selection, provenance, and stale-surface recovery
• a system and tenant administration editor with unsaved-change protection, publish/archive controls, assignment management, and server-enforced lockout prevention
• surface declarations for every currently installed module that contributes a WebUI, including finer-grained shared administration and settings surfaces

Still intentionally separate:

• Policy-owned inherited ceilings and policy decision provenance
• workflow-instance and workflow-step activation of pinned View revisions
• read-only and layout-replacement projections beyond the version 1 visible/hidden contract

Gitea Work Packages

• govoplan#17: task-focused Views user story
• govoplan#16: initialize and implement govoplan-views
• govoplan-core#271: versioned surface and runtime contracts
• govoplan-policy#9: inheritance, ceilings, and provenance
• govoplan-workflow#7: workflow instance and step activation
• govoplan-workflow#3: focused workflow mode user story