154 lines
6.2 KiB
Markdown
154 lines
6.2 KiB
Markdown
# 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 also project configurable product areas and Quick Access contributions.
|
|
They may select, order, rename or hide permitted presentation identities but
|
|
do not move ownership or merge Mail, Postbox, Files, Calendar, Tasks or other
|
|
domain state.
|
|
|
|
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
|
|
- immutable presentation settings for grouped or flat navigation, product-area
|
|
order and product-area labels; the shell resolves these settings through the
|
|
same system, tenant, group, user and Workflow-aware View projection
|
|
- live product-area identities from module manifests, with authorized
|
|
unclassified destinations retained under More tools during incremental
|
|
adoption
|
|
|
|
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
|
|
|
|
Quick Access ordering and availability remain owned by
|
|
`govoplan-quick-access`; Views only narrow its declared surfaces for the active
|
|
task. Neither contract permits arbitrary layout or styling. See
|
|
`docs/QUICK_ACCESS_AND_PRODUCT_AREAS.md` in the meta repository.
|
|
|
|
## 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
|