docs: organize cross-product documentation
This commit is contained in:
@@ -0,0 +1,153 @@
|
||||
# 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/architecture/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
|
||||
Reference in New Issue
Block a user