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, what scope each one covers, what template + variant gives it structure on each surface, and how screens connect.

What Architecture captures

A graph. Two top-level arrays:

  • Screens — the nodes. Each carries a name, a purpose, a level (its content scope), a group, a route, a template + variant per surface, and the reason for that choice.
  • Edges — typed navigation between screens.

Levels are scopes, not tree depth

Every screen owns a content scope, shown as a level pill on the canvas:

  • L1 — Vertical. A whole area of the product. The L1 screens are peers, and together they are what the persistent navigation shows. In a cooking app: Recipes.
  • L2 — Topic. A topic within a vertical: the collection an L1 screen opens into. In a cooking app: one cuisine inside Recipes.
  • L3 — Item. A single item within a topic: the detail screen. In a cooking app: one recipe.

A level says what the screen is for, not where it sits in a tree. There is no single root: the verticals are peers, and the persistent navigation exposes them by existing. That's also why Architecture doesn't need a web of navigation edges between the verticals — the roots are the nav.

Mini Apps

Some flows aren't screens in the hierarchy at all — they're contained takeovers: a guided cook-along, a multi-step import, an onboarding wizard. Architecture captures these as Mini Apps:

  • No level. A Mini App floats above the L1/L2/L3 scopes.
  • Launched from one or more screens; it takes over while it runs and returns you when done.
  • Always a step-shaped template (wizard or stepper).

Mini Apps are used sparingly. Steps alone don't make one; the takeover and the mandatory exit do.

Screens

Each screen has:

  • Name + purpose — what this screen is for, in one sentence.
  • Level — its content scope (see above). Mini Apps have none.
  • Parent — the screen it drills out of; verticals have no parent.
  • Group — section cluster (e.g. main, account).
  • Route — structural identifier (/recipes, /recipes/:id); the implementer translates it to whatever router the target project uses.
  • Template + variant — one of 20 UX templates and its spatial expression (48 variants in the catalog), chosen per surface the screen appears on. A screen can be card_grid : with_filters on desktop web and card_grid : single_col on the phone.
  • Why this template — the written rationale for the choice.
  • Surfaces — which surfaces the screen appears on. Unspecified means all of them. See Surfaces and platforms.
  • Persona access + landing flag — who can reach it, and who lands here by default.
  • Entities — the ontology objects this screen fronts.

Some variants span two screens — list_detail : drill_out implies a linked detail screen, and the skill creates it and wires the edge.

Edges

Each edge is a typed navigation step between two screens:

  • Type — local_nav (drilling within a vertical), cta (a task-driven jump across the product), global_nav (a genuine top-level shortcut, rare because the verticals are already the nav), footer, or utility.
  • Optional surfaces — an edge can exist on one platform and not another, so the phone tab bar and the desktop sidebar can expose different routes.

The canvas

[Screenshot TODO: Architecture sitemap with screen silhouettes in level bands, level pills on each node, a Mini App lane below with dashed launch connectors, and the surface switcher in the page header.]

Architecture renders as a canvas with three lenses:

  • Sitemap (default) — screens as silhouette thumbnails arranged by scope; parent-child lines show the drill structure. Mini Apps sit in their own lane below, joined to their launcher screens by dashed connectors.
  • Navigation — same nodes, edges show typed navigation flow, with a legend for the edge types in play. Draw new edges, adjust types.
  • Tasks — multi-screen task threads. See which screens support which tasks.

Hover a level pill and it explains its scope. On multi-surface projects, a surface switcher in the page header flips the whole canvas between surfaces — narrow surfaces render portrait phone frames.

Click any screen and its detail panel opens: name, a live render of its layout (click through to the Screens layer), purpose, page template, why this template, and where it appears.

The file written

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

The skill

/architecture populates the layer.

  • Reads: everything in design/sources/, design/project.json (which platforms), design/ontology.json, design/vision.json, and 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 and entities. Each task implies a screen or two; adjacent steps on shared entities may collapse into one screen.
  • Assigns each screen a scope and keeps the verticals a flat set of peers.
  • Picks a template + variant per screen per surface, and writes the reasoning down. A browse-and-pick task → card_grid : with_filters. A multi-step creation task → a wizard. Narrow surfaces get narrow-friendly variants.
  • Captures contained takeover flows as Mini Apps with their launcher screens.
  • Derives routes from entity names and task verbs; leaves canvas positions at sensible defaults.

The recipe example

The recipe-scaling tool's Ontology produces three screens and a quiet graph:

  • Recipes — the vertical the Home Cook lands on. card_grid : with_filters, because the entity is image-led and the task is scan-and-pick.
  • Recipe — the item screen for one recipe, opened from the list. detail_page : with_aside, scaling as the primary action with saved ratios in the aside.
  • Preferences — a small utility vertical. settings : sectioned.

One local_nav edge carries the drill from the list into a recipe. No edges between the verticals: as peer roots, they are what the navigation shows.

What Architecture is not for

  • Composition. Per-page zones, chips, and overlays live in Screens. Architecture commits the template + variant; Screens fills the zones.
  • 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