115 lines
4.3 KiB
Markdown
115 lines
4.3 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 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.
|
|
|
|
## 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
|