From 30351a8373cb481b7bc58f31fb8672a3fd035c15 Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Tue, 28 Jul 2026 19:06:24 +0200 Subject: [PATCH] Sync wiki from project files --- Codex-Project-Index.md | 1 + Repo-docs-VIEWS-ARCHITECTURE.md | 121 ++++++++++++++++++++++++++++++++ 2 files changed, 122 insertions(+) create mode 100644 Repo-docs-VIEWS-ARCHITECTURE.md diff --git a/Codex-Project-Index.md b/Codex-Project-Index.md index 2104daa..1aded4f 100644 --- a/Codex-Project-Index.md +++ b/Codex-Project-Index.md @@ -21,3 +21,4 @@ This page is generated from repository and product-directory project files. - [Repo-docs-REPOSITORY-STRUCTURE](Repo-docs-REPOSITORY-STRUCTURE) - `/mnt/DATA/git/govoplan/docs/REPOSITORY_STRUCTURE.md` - [Repo-docs-SECURITY-AUDIT](Repo-docs-SECURITY-AUDIT) - `/mnt/DATA/git/govoplan/docs/SECURITY_AUDIT.md` - [Repo-docs-SYSTEM-ADMINISTRATOR-LIFECYCLE-USER-STORY](Repo-docs-SYSTEM-ADMINISTRATOR-LIFECYCLE-USER-STORY) - `/mnt/DATA/git/govoplan/docs/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md` +- [Repo-docs-VIEWS-ARCHITECTURE](Repo-docs-VIEWS-ARCHITECTURE) - `/mnt/DATA/git/govoplan/docs/VIEWS_ARCHITECTURE.md` diff --git a/Repo-docs-VIEWS-ARCHITECTURE.md b/Repo-docs-VIEWS-ARCHITECTURE.md new file mode 100644 index 0000000..14b0356 --- /dev/null +++ b/Repo-docs-VIEWS-ARCHITECTURE.md @@ -0,0 +1,121 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan/docs/VIEWS_ARCHITECTURE.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# 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