What a blueprint can do

Most features are not one table. They are a dozen small decisions that all have to agree with each other — who may see which rows, what happens when a record changes state, which page the team actually works in — and getting them to agree by hand is an afternoon at best and a quiet security hole at worst. A blueprint makes all of those decisions at once, from one document, and shows you the whole set before it writes any of it.

Here is what that looks like.

#A support desk, with the isolation already right

Two audiences share one queue. An agent sees every ticket; a person who raised one sees their own and nothing else. That single sentence needs a table for tickets, a table for replies, two roles, a row scope on each table, a rule that stops a requester quietly marking their own ticket resolved, and a sidebar entry so the team can find it.

Miss one of those and nothing looks broken — the desk works perfectly, and one audience can read the other's mail. A blueprint installs the set, and the plan shows you the access rules as rules, before any of them is in force.

#A publishing workflow that notifies the right people

An article moves from draft to review to published. Each move should tell somebody, the published ones need a page readers can actually open, and an outside system wants a notification when one goes live. A blueprint installs the collection, the editorial roles, the automation that runs on the state change, the page, and the outbound call — wired to each other, rather than five things you wire up yourself afterwards.

#A catalogue that arrives with its contents in it

An empty catalogue is not a catalogue. A blueprint can bring its own starting data: hundreds of rows already seeded, search already configured over them, images with somewhere to live and a layout that shows them. What you get on the day you install it is a working catalogue you can look at, not a schema you still have to fill.

#A public site, made of your own data

Pages, the navigation between them, and a small table behind the one page that needs one. This is the case where a blueprint replaces "build a site and point it at the API" — the pages are built here, from the data that is already here.

#Behaviour added to something you already run

A blueprint does not have to create anything. Point one at a collection you already have, answer one question about which collection it is, and it installs only the watching and the outbound call — a notifier, an archiver, a nightly reconciliation. The tables stay yours; the blueprint owns only the behaviour it added, and takes only that away again.

#An internal application nobody had time to code

Subscriptions, usage, invoices; the roles for the people who work them; the scheduled run that opens the month's invoices; the views each team lives in. Written as one document, installed in one go, and — this is the part that surprises people — the same document installs a second, separate copy beside the first for a different team, because every name it creates is prefixed by an answer you give it at install time.

The documents behind those six ship in the repository, with what each one builds and where each one ran out of road: see Examples.

#The three promises

Whatever the document, three things hold.

You see it first. The plan is computed against your project, not against an empty one, and it says what would be created, what already matches, and what you have edited by hand since. Grants — the permissions a blueprint hands out — are never applied without an explicit tick, on install or on any later change. See Install one.

It cannot exceed you. Every call an install makes runs as the person installing, under their own permissions. A blueprint is a faster way to do things you may already do; it is not a way to acquire power you do not have.

Removing it does not take your data. Uninstalling detaches: the tables, the rows written since, the flows and the pages all stay exactly where they are. The one thing offered back is the permissions the blueprint handed out, and only if you tick it. See Update and uninstall.

#What it cannot do

It is a young format and it is honest about its edges — a document cannot put files into the container it just made, and a brick cannot yet name a resource another brick in the same document creates, so a page it installs cannot be attached to a collection it installs. Each shipped example records where it hit a wall, in Examples.