The blueprint

One JSON document per space holds everything a person can see or change. It holds settings and shapes, never live data: a collection's fields are in the blueprint, its records are in the database. Type and checks: convex/lib/blueprint.ts.

Fields #

New fields arrive with new engines. Old blueprints keep opening: upgradeBlueprint fills in anything missing with its default.

A new space starts from starterBlueprint(style): the HQ page, a Home page with a hello, the default roles, private access, and the style the person picked.

Ids #

• Block ids are unique across the whole space, not just their page. Use short kebab-case (hero, links-ig).
• Collection, field, stream and role ids: lowercase letters, digits and dashes, starting with a letter (^[a-z][a-z0-9-]{0,39}$, roles up to 32).
• A kit's ids start with the kit's id (tasks-board, forms-responses) so kits never clash.

Pages #

{ "id": "menu", "title": "Menu", "blocks": [ … ], "look": { "colors": { "accent": "#c2410c" } }, "visibleTo": ["member"] }

• blocks is a tree: a block with children holds other blocks (Blocks).
• look is a style layer for this page only (Styles).
• visibleTo lists role ids (or level:<id>, level:<id>+, badge:<id>); unset means everyone who can see the space (People).
• Every page opens at /p/<page-id> with no new code; a button with href: "#menu" goes there.
• The hq page is core: it can be rearranged and added to, never removed.

Dashboard #

"dashboard": { "panes": [{ "kind": "page", "page": "hq" }, { "kind": "page", "page": "home" }, { "kind": "chat" }] }

A pane is a page or the AI chat. Phones show one pane at a time with tabs; screens 900 px and wider show them side by side. People who can't manage don't see the chat pane or pages hidden from their role.

Panes are the app's navigation. With nav: "tabs" (the default), on phones the first five are native tabs and the rest are top-bar buttons; with nav: "list" there's no tab bar: home is the chat list and panes are rows in it (the chats block's rowsTop and rowsUnder), switched in HQ → Navigation; each page's icon (a name from src/icons/icons.json) is its tab icon. Wide screens get a sidebar, or this side-by-side dashboard when a space has three panes or fewer.

Photo books #

Full detail in docs/PHOTOBOOK.md. A book points at photos in a feed (the Gallery by default) and never copies them, so a deleted photo simply drops out. tag makes it an album, while from and to (YYYY-MM-DD) pick a date range. Without pages, a book lays itself out from its photos (fill: order, photos per page, chapters by month, day or tag, captions, max) and grows with them. The same photos always make the same pages. Hand-made pages are { id, layout, photos?, title?, text?, date?, tint? }, where tint is a style colour name and never a hex value. Limits are 24 books, 200 pages a book and 1,200 placed photos in all. Words are words["book.<key>"].

{ "op": "add", "path": "/books/-", "value": { "id": "italy", "name": "Italy", "tag": "italy", "fill": { "chapters": "day" } } }

Words #

Every word the shell shows is words.<key>; a missing key falls back to a built-in default. Keys today: chatTitle, chatPlaceholder, approve, reject, undo, back. Blocks carry their own words in their props (label, empty, submit, done). A new screen that needs a word adds a key here, never a string in code.

Changes #

Every change is a list of JSON Patch ops:

• Paths are JSON Pointers. - adds at the end of a list. ~1 is a / inside a key, ~0 a ~.
• add on an object key sets it; add on a list index inserts there.
• Replacing the whole blueprint (path "") is refused.
• Ops apply in order to a copy; if any fails or the result fails a check, nothing changes.

Keep a change small and about one thing, with a one-line summary people read in History.

Checks #

checkBlueprint runs on every change, from anyone. It refuses, with a readable message:

• unknown block kinds, missing required props, props of the wrong type, children on a block that can't hold them, duplicate ids;
• a missing hq page, a pane pointing at a page that doesn't exist;
• a miniapp block pointing at no app, a stream block at no stream, a records.* block at no collection or field, a groupBy that isn't a choice field, a poll or wheel with fewer than two options;
• bad collections, roles, streams, access, styles or looks (see each page);
• a kit id that isn't in the library.

The AI gets the same messages and fixes its proposal itself.

Versions and undo #

• Every applied change bumps version and stores the whole blueprint in versions with its summary and who made it (person or ai).
• Undo is restore(version): the old blueprint is saved as a new version, so undo can be undone and nothing is ever lost.
• AI changes wait in proposals as pending until a person approves (or discards) them.

Three ways in #

1. HQ: system blocks (hq.*) that edit parts of the blueprint.
2. The AI: proposes ops; a person approves.
3. The API: blueprint.change with ops, under the same permission (manage). See API.