The Board Tree

A board is not a diagram with panels bolted onto it. It's a workspace with a canvas inside it — alongside its sources, its insights, its intents, and everything else it tracks. And boards nest: one board drills into another, which drills into another, until the whole system is one navigable structure.

That structure is the board tree, and it's the spine of the product. Almost everything you do happens somewhere in it, and almost every navigation is a move within it.

This page is about the tree itself: how it's shaped, what each level carries, how you move around it, and where app boards are allowed to sit.

One tree, from system to subsystem

Every workspace starts with a Root Board. From there, any node can drill into a layer — a full board nested inside that node. Layers nest as deep as your system needs, usually two or three levels.

Expand

Three kinds of board live in that tree, and which one you're looking at decides what it can do:

The interesting part is that these aren't just labels — they change what the board is, and what you see when you open it.

What a board carries depends on what it is

Open a board and the tab strip shows only the surfaces that board actually has:

An app board earns the full set because it has a repo behind it: aspects pulled from the code, specs and intents flowing back, skills compiled into it. A root board watching several apps gets a narrower strip on purpose — aspects, specs, and skills only make sense one repo at a time, so pooling two repos' database tables into one list would be incoherent. A plain layer is a diagram, and shows you a diagram.

The short version: hubs and facet tabs appear exactly where a repo binding gives them meaning. Everywhere else, the canvas is the whole board.

A new root board with no app boards anywhere below it opens on its canvas, but still carries the Command center tab. Open it and you get an invitation to drill into a system's layer and bind a repo — the empty command center, waiting for its first app.

Three ways to know where you are

Because the tree can get deep, the board shell answers "where am I" three times over, each at a different zoom level:

• The breadcrumb — the path to the board you're on: Root › Payments › API. Click any crumb to pop back up the chain. It appears once you're inside a layer.
• The tab strip — the facets of the board you're on, and which one is active.
• The board map — the whole tree at once, with your position marked.

The breadcrumb tells you the path you took. The map tells you everything you didn't.

You'll want the map, because layers don't appear in the workspace sidebar. That list stays deliberately short — top-level boards only — so a fifty-board tree doesn't bury the handful of boards people actually start from. Everything below the top level lives in the tree, and the map is how you see it.

Under all of it sits one rule: the URL is the whole answer. Board, facet, and open item all live in the address bar, so every state you can reach is a link you can send and a page you can reload without losing your place. The shell's own back and forward arrows retrace your steps board by board, telling you where each one goes — Back to Payments · Intents.

The board map

Hit Map in the board bar and a panel docks on the left with your entire board tree in it. It's the 360° view: every board in the tree, which ones are apps, what each one carries, and one click to any of it.

Expand

Each row tells you what that board is:

• App boards carry a type badge — agent, infrastructure, fullstack — naming what kind of codebase the repo is, plus a pulse dot showing how fresh its data is: live, quiet, dormant, or never.
• Plain layers carry the icon of the node that owns them, so the tree still shows what each board is even without a badge.
• Beneath every app board and root row sits a strip of small facet icons — one per surface that board has. Hover for the name.

Those facet icons are the point. Clicking a board's row takes you to that board; clicking one of its facet icons takes you to that board and that surface. You can go from an intent on one app straight to the aspects of a sibling app without passing through a single canvas.

A few behaviours worth knowing:

• The panel stays open while you navigate, so you can move through several boards without reopening it.
• Clicking a facet on the board you're already on preserves your canvas moment — your viewport and selection survive the switch. Jumping to a different board deliberately clears them, so you land on that board's own view instead of dragging a stale viewport across.
• Collapse any branch with the chevron when a subtree gets noisy.
• Right-click a row to create an intent about that board, or to rename it if you have edit access.
• The Map button only appears once the tree has more than one board — a single board has no tree to map.

An app board's hub also carries a Layers card listing that board's direct children, for when you want the next level down rather than the whole tree.

Where app boards can sit

There are two ways to put an app board in the tree:

• Drop one on the canvas. Open the Apps palette and drag an app onto the board. You name the repo and branch, and you get a new layer beneath that node with the repo bound to it. This is the usual path — it creates the node and its app board in one move.
• Promote a board you already have. On a board that's already modelling a system, hit Make this an app and bind its repo. The board becomes an app board where it stands.

Either way the result is identical, because being an app board isn't a setting — it's just what a board is once a governing repo is bound to it. Nodes that represent a codebase can host one; a node that models something else (a managed queue, a third-party API, a model artifact) can't, and won't offer it.

One rule then shapes the whole tree, and it's worth understanding rather than discovering:

An app board can't contain another app board.

An app board is bound to exactly one repo, and everything beneath it describes the inside of that repo. Think of it as a checkout: the folders inside a checkout nest as deep as you like — and they're absolutely worth mapping, which is what layers are for — but no folder in there gets its own remote, its own branch, or its own push. A second repo isn't a deeper folder in the first one. It's a second checkout, sitting beside it.

Two repos, two app boards, sitting as siblings under the root — and the root becomes the command center watching both. Layers below each app board go as deep as the codebase does.

Two related rules follow from the same idea:

• One repo per app board, pinned to one branch. Only pushes from that branch are accepted, the way a hosting product pins a release branch.
• A monorepo is still one repo — so it's one app board, even when it holds several deployable apps. Model web and server as layers inside it, not as separate app boards. Separate repos are what earn separate app boards.

None of this is a setting you maintain. Bind a repo and the board is an app board from that moment; unbind it and the board goes back to being a plain board with a canvas, and the tree reshapes itself around the change. App Boards & the Hub walks through what you get when it does.

How deep to go

Depth is what keeps the tree readable. A 400-file system doesn't become a 400-node diagram — you read a 20-node overview and drill only where you need to. Most trees settle at three levels:

• L0 — the root. How your systems relate. One board, the whole landscape.
• L1 — one board per system. This is where app boards normally live: one per repo.
• L2 — subsystems inside a system. The modules, services, and areas a repo is built from.
• L3 — go here only when a subsystem genuinely earns its own map.

Let the tree grow with the questions people actually ask. A layer nobody drills into is a layer that didn't need to exist — and depth is easier to add than to unwind, because a board can't be picked up and re-parented somewhere else later. Nesting is free in plan terms, though: only top-level boards count toward your plan's board limit, so layers and app boards don't.

Two things to know before you go deep:

• Published boards include layers about ten levels down. Anything deeper is simply left out of the published view. Well past where a readable tree stops, but worth knowing if you're generating one. See Publishing Boards.
• Delete from the bottom up. A layer with sub-layers under it asks you to remove those first, so you can't drop a whole branch with one click by accident.

What's next