From 117ce818eae723f1a972a5d2de0f0aabf4e52e39 Mon Sep 17 00:00:00 2001 From: Ruben van der Linde Date: Sat, 23 May 2026 07:34:54 +0200 Subject: [PATCH] docs(architecture): add ADR-003 information architecture Lift cross-cutting IA design rules from the 2026-05-22 small-five IA design pass (ia-small5.md) into a per-app ADR. Documents the 5 top-level menu structure (Apps / Designers / Catalog / Deploy / Beheer), maps all chain specs to IA placements, and codifies four numbered rules: 1. Designers are tools, not destinations (launched in app context). 2. Runtime/RBAC/Exporter/Snapshots are infrastructure (per-app tabs + Beheer globals, never own top-level menus). 3. Catalog and Deploy stay separate menus (distinct personas, distinct workflows; do not merge into Lifecycle). 4. GEMMA-starterpack is a curated sub-page inside Catalog, not a top-level menu. --- .../adr-003-information-architecture.md | 120 ++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 openspec/architecture/adr-003-information-architecture.md diff --git a/openspec/architecture/adr-003-information-architecture.md b/openspec/architecture/adr-003-information-architecture.md new file mode 100644 index 00000000..602b1687 --- /dev/null +++ b/openspec/architecture/adr-003-information-architecture.md @@ -0,0 +1,120 @@ +# ADR-003: Information architecture — 5 top-level menus, designers as sub-tools + +**Status**: accepted + +**Date**: 2026-05-23 + +## Context + +openbuilt is the low-code application builder where citizen developers and ambtenaren assemble register-based apps from schemas, pages, workflows, and business rules. The chain ships roughly a dozen specs (`openbuilt-application-register`, `openbuilt-page-designer`, `openbuilt-schema-designer`, `workflow-designer`, `business-rules-engine`, `openbuilt-template-catalogue`, `gemma-starter-pack`, `openbuilt-runtime`, `openbuilt-rbac`, `openbuilt-exporter`, `openbuilt-version-snapshots`, `environments-deployment-pipeline`) plus assorted infra concerns. + +The naive sidebar would put each spec on its own top-level menu — twelve-plus items in a sidebar, no clear daily home for the maker, and four "Designer" menus competing with the surfaces they edit. That violates the fleet-wide 5–7 top-level menu ceiling and forces the maker to context-switch between "where my app lives" and "where I edit it". + +Two persona groups must be served without splitting the app: + +- **Maker** (citizen-dev / ambtenaar) — spends 90% of their time editing one app: its schemas, pages, workflows, rules, RBAC. Needs Apps as a home, designers launched in app context, Catalog for templates. +- **Operator / release manager** — promotes between environments, runs pipelines, manages snapshots. Needs Deploy and Beheer. + +A cross-cutting IA design pass (`/tmp/ia-small5.md`, 2026-05-22) covered openbuilt alongside four sibling apps (financeq, purchaseq, planix, scholiq) and applied the same compression discipline: collapse tier-suffixed and adapter specs into sub-pages/tabs/widgets, demote infrastructure to per-resource tabs, keep top-level menus bounded between 4 and 6. + +## Decision + +Adopt a **5-menu top-level navigation** for openbuilt: + +1. **Apps** — Mijn apps, Alle apps, App-detail, App-runtime preview +2. **Designers** — Page Designer, Schema Designer, Workflow Designer, Business Rules Designer (as sub-tools) +3. **Catalog** — Templates, GEMMA-starterpack, Component-bibliotheek, Imports +4. **Deploy** — Omgevingen, Pipelines, Releases, Snapshots +5. **Beheer** — RBAC-rollen (global), runtime-config, snapshot-policy, catalog-feeds, pipeline-templates, connectors, logs, audit + +The twelve+ specs collapse into this shape per the mapping in §IA-mapping below. + +### Numbered design rules + +**Rule 1 — Designers are tools, not destinations.** + +The four visual editors (Page, Schema, Workflow, Business Rules) are always launched in the context of an app. The Designers menu is a discovery surface that lists the four sub-tools; clicking a designer without an app first opens a "kies een app" picker, never a blank canvas. + +*Rationale:* a designer without a target schema/page/workflow has nothing to edit. Promoting each designer to its own top-level menu forces the maker to remember which app they were editing and re-select it; keeping designers tool-shaped keeps the App detail as the maker's home. + +*How to apply:* register the four designers as routes under `/designers/{page|schema|workflow|rules}` that require an `app` query param; when the param is missing, render the app picker rather than the editor. The App detail page exposes "Pagina bewerken / Workflow bewerken / Regel bewerken" actions that open the designer with the context pre-filled. + +**Rule 2 — Runtime, RBAC, Exporter, Snapshots are infrastructure: surface as per-app tabs, configure globally in Beheer.** + +Each of these concerns has both a per-app dimension (this app's runtime health, this app's roles, this app's export bundle, this app's snapshot history) and a global dimension (resource limits, reusable role templates, export-format defaults, retention policy). The per-app dimension lives as a tab on the App detail (`Overzicht / Schemas / Pagina's / Workflows / Rules / RBAC / Versies / Runtime/Preview / Export / Deploy-status / Audit`). The global dimension lives under Beheer. + +*Rationale:* a maker tweaking roles for one app should stay inside that app; a separate top-level "RBAC" menu would force them to leave their work, find the app in a list, and lose context. Operators configuring shared policy work in Beheer where all global config lives together. + +*How to apply:* never add a top-level menu for an infrastructure concern that already has a per-app expression. When in doubt: if the artefact belongs to one app, it is a tab on that app; if it applies across apps, it is a Beheer sub-page. + +**Rule 3 — Catalog and Deploy stay separate menus despite both being "lifecycle".** + +Catalog is template-shopping for citizen-devs (browse, install, fork, publish); Deploy is release management for operators (promote snapshot, rollback, run pipeline). Their audiences and workflows are distinct. + +*Rationale:* merging them under one "Lifecycle" menu would mix decision-making (what to install) with execution (what to promote). The personas barely overlap — a citizen-dev rarely promotes to prod, an operator rarely picks a template — so a unified menu forces both to scan past content they don't use. + +*How to apply:* keep Catalog and Deploy as siblings. Cross-link only where the user flow demands it (e.g. "this template, after install, deploys to dev by default" is a Deploy hint inside Catalog, not a shared menu). + +**Rule 4 — GEMMA-starterpack is a curated sub-page inside Catalog, not a top-level menu.** + +The GEMMA-pack for overheid use cases is highly visible and politically important, but it is one (well-curated) template feed among many. + +*Rationale:* promoting GEMMA to its own top-level menu would imply openbuilt is a GEMMA tool first and an app builder second, and would force every non-overheid maker to scan past it. Inside Catalog, GEMMA gets prominence via ordering and badging without distorting the IA. + +*How to apply:* keep `gemma-starter-pack` mapped as `Catalog > GEMMA-starterpack`. Give it a visual treatment (top of the list, conformity-score badge) inside Catalog rather than a sidebar slot. + +### IA mapping (chain specs → IA placement) + +| spec_slug | placement | parent | +|---|---|---| +| `openbuilt-application-register` | menu | Apps | +| `openbuilt-page-designer` | sub-tool | Designers > Page Designer | +| `openbuilt-schema-designer` | sub-tool | Designers > Schema Designer | +| `workflow-designer` | sub-tool | Designers > Workflow Designer | +| `business-rules-engine` | sub-tool | Designers > Business Rules Designer | +| `openbuilt-template-catalogue` | menu | Catalog | +| `gemma-starter-pack` | sub-page | Catalog > GEMMA-starterpack | +| `openbuilt-runtime` | tab | Apps > app > Runtime/Preview (+ global in Beheer) | +| `openbuilt-rbac` | tab | Apps > app > RBAC (+ global in Beheer) | +| `openbuilt-exporter` | tab | Apps > app > Export (+ global in Beheer) | +| `openbuilt-version-snapshots` | tab | Apps > app > Versies (+ snapshot-policy in Beheer) | +| `environments-deployment-pipeline` | menu | Deploy | + +### Implementation phases (informational, mirrored from IA doc) + +- **Phase 1 (MVP):** Apps (register + detail) + Schema Designer + Page Designer + Beheer (RBAC global, runtime-config). +- **Phase 2 (workflow + rules):** Workflow Designer, Business Rules Designer, runtime expansion (events + scheduled jobs), per-app RBAC. +- **Phase 3 (catalog):** Template catalogue, GEMMA-starterpack, exporter, version-snapshots, forken. +- **Phase 4 (deploy):** Environments + deployment pipeline, releases, snapshot-policy, drift-detection, rollback. + +## Consequences + +**Positive:** +- Sidebar stays at 5 items — well under the fleet 5–7 ceiling — so the maker's daily surface is scannable. +- App detail is the unambiguous home for the maker; designers launch from where the work lives. +- Maker and operator personas have distinct primary menus (Apps/Designers/Catalog vs Deploy/Beheer) without splitting the app. +- Infrastructure concerns (Runtime/RBAC/Exporter/Snapshots) have one global config home (Beheer) and one per-app surface (App detail tabs), so there is never a question of where a setting lives. +- New chain specs land in known IA slots: a new designer is a sub-tool, a new template feed is a Catalog sub-page, a new per-app concern is an App detail tab. + +**Negative / trade-offs:** +- Designers cannot be deep-linked without an app context — a marketing page that says "try the Page Designer" has to either pick a demo app or accept the picker step. +- Infrastructure surfacing in two places (per-app tab + Beheer global) requires careful UX to avoid duplicating fields; the rule is "global = defaults + policy, per-app = overrides + status". +- GEMMA stakeholders may push for top-level prominence; Rule 4 has to be defended. +- Operators using only Deploy may find Apps/Designers/Catalog irrelevant — that's acceptable for v1, RBAC will eventually hide irrelevant menus per role. + +## Alternatives considered + +| Option | Reason not chosen | +|---|---| +| One top-level menu per chain spec (~12 items) | Violates 5–7 ceiling; no daily home; designers compete with the surfaces they edit | +| Single "Lifecycle" menu merging Catalog + Deploy | Mixes citizen-dev decision-making with operator execution; distinct personas forced to scan past irrelevant content | +| Designers as top-level (4 sibling menus) | Forces app-context switching; designer with no app context is meaningless; bloats sidebar | +| GEMMA-starterpack as top-level menu | Implies openbuilt is a GEMMA tool first; non-overheid makers scan past it; one template feed shouldn't shape the IA | +| RBAC / Snapshots / Runtime as top-level menus | Drags the maker out of the app to manage one app's settings; per-app tab is where the work happens | + +## Related + +- Builds on the fleet IA design pass `ia-small5.md` (2026-05-22) that covered financeq, purchaseq, planix, scholiq, openbuilt with the same compression discipline. +- Aligns with `adr-002-versioned-app-deployment-model.md` — the per-app Versies tab is the surface for the linear-chain promotion model from ADR-002. +- Aligns with `adr-001-app-assets-via-openregister-files.md` — app-level assets surface inside App detail tabs, never in a separate "Assets" menu. +- Downstream cascades: any new chain spec must be placed via the IA mapping table; new top-level menus require an ADR superseding this one.