Skip to content
Docs

Architecture

Architecture is the layer where the screen inventory and navigation get committed. Ontology says what objects and tasks exist. Architecture says how many screens there are, where each one sits in the hierarchy, what template + variant gives each screen its structure, and how screens connect.

What Architecture captures

A graph. Two top-level arrays:

  • Screens — the nodes. Each carries name, hierarchy level, parent, group, position, and a template + variant pair.
  • Edges — typed navigation between screens.

Screens

Each screen has:

  • Name + short description.
  • Level — L1 (top-level), L2 (sub-screen), L3 (nested).
  • Parent screen ID — null for L1 roots.
  • Group — section cluster (e.g. main, account, admin).
  • Path — structural identifier (/recipes, /recipes/:id); the implementer translates it to whatever router the target project uses.
  • Template — one of 20 UX patterns (list_detail, dashboard, wizard, card_grid, detail_page, kanban, inbox_queue, settings, form, table, ...).
  • Variant — the spatial expression of the template (list_detail:inline / list_detail:drill_out / card_grid:with_filters, etc.). 48 variants in the catalog.
  • Persona access — which personas can reach this screen.
  • Landing flag — which persona, if any, lands here by default.
  • Position — x, y on the canvas.

The template + variant pair carries the screen's structural identity. There's no separate "Pattern Assignment" object — the decision lives directly on the screen.

Edges

Each edge is a typed navigation step between two screens:

  • From screen ID + to screen ID.
  • Type — primary_nav, drill, modal_invoke, back, cross_section, etc.
  • Optional label + metadata for that edge type.

Variants imply specific edges. list_detail:inline keeps list + detail on the same screen (no drill). list_detail:drill_out requires a drill edge to a linked detail screen. The skill enforces this.

The canvas

[Screenshot TODO: Architecture sitemap view with four screen nodes rendered as PatternSchematic thumbnails arranged in a tree, navigation lens toggled showing typed edges between them.]

Architecture renders as a ReactFlow canvas with three lenses:

  • Sitemap (default) — screens as silhouette thumbnails (rendered via PatternSchematic at node scale); edges are parent-child hierarchy lines. Drag screens between parents, reorder, split, combine.
  • Navigation lens — same nodes, but edges show typed navigation flow. Draw new edges, adjust types.
  • Tasks lens — multi-screen task threads. See which screens support which tasks.

Click any screen → right panel opens with the Screen view (nested shell + page silhouette + parts list). Click the page row → jumps to that screen in the Screens layer.

The file written

design/architecture.json — one file, top-level screens[] + edges[].

The skill

/architecture populates the layer.

  • Reads: design/ontology.json + design/vision.json + design/architecture.json if it exists.
  • Writes: design/architecture.json. Also writes task.screenTouchpoints[] back into ontology.json so each task knows which screens carry it.

Behavior:

  • Starts from tasks. Each task implies a screen or two. Adjacent task steps on shared entities may collapse into one screen with tabs.
  • Picks a template + variant per screen based on task shape + entities involved. A browse-and-pick task → card_grid : with_filters. A multi-step creation task → wizard : centered. A scan-and-drill task → list_detail : inline or : drill_out depending on density.
  • Drill-out variants emit linked screens automatically — the skill creates the detail screen and wires the edge.
  • Derives paths from entity names and task verbs (/recipes, /recipes/:id).
  • Leaves positions at sensible defaults; reposition on the canvas and the layout writes back.

The recipe example

The recipe-scaling tool's Ontology produces:

Screens

  • recipes-list — L1, group main, path /, template card_grid, variant with_filters, persona access Home Cook, landing for Home Cook.
  • recipe-detail — L2, parent recipes-list, group main, path /recipe/:id, template detail_page, variant with_aside, persona access Home Cook.
  • preferences — L1, group account, path /preferences, template settings, variant sectioned, persona access Home Cook.

Edges

  • recipes-list → recipe-detail, type drill.
  • recipe-detail → recipes-list, type back.
  • recipes-list ↔ preferences, type primary_nav.

Three screens, four edges.

What Architecture is not for

  • Composition. Per-screen zones, chips, and overlays live in Screens. Architecture commits the template + variant; Screens fills the zones.
  • Pattern reasoning. That happens in Ontology via task shape + entity traits. Architecture picks the template; the reasoning lives upstream.
  • Visual treatment. Denote captures none of it.

The discipline: Architecture commits the inventory and the navigation graph. Everything inside each screen is pushed to Screens.

Where to next