Model App

Before you start

Check that the Easy container is running:

docker compose ps --format '{{.Service}} {{.State}}' | grep -E '^(easy|postgres) '

If not running, tell the user:

The Easy container is not running. Start it with:

  bun run up

Then try again.

Do not proceed with modeling until Easy is running.

What is Simple?

Simple is a minimal full-stack pattern: postgres owns everything, the server relays, the client merges. Auth, business logic, and permissions all live in SQL. The server is a thin WebSocket relay that prepends user_id to every call. The client opens documents, receives live updates via pg_notify, and merges deltas into reactive signals.

Created with bun create blueshed/simple <app-name>.

Simple Concepts

NOT modeled: client-side components, CSS, signals code, SQL queries. Those are generated by the /implement skill from the exported spec.

How Modeling Connects to Building

bun model ... → bun model export > spec.md → /implement

1. You model with the Easy CLI (this skill)
2. Export produces spec.md — a framework-neutral description of entities, documents, methods, and change targets
3. The /implement skill reads spec.md and generates: SQL schema, doc functions, mutation functions with pg_notify, web components with openDoc/closeDoc, routing

Decomposition Order

Always work top-down in this order:

1. Stories — identify actors and what they can do
2. Entities — extract nouns from stories, add fields
3. Relations — has-many / belongs-to between entities
4. Documents — what data does each screen need? Each becomes a postgres doc function
5. Expansions — which related entities load with each document?
6. Methods — what mutations can users perform? Each becomes a postgres function
7. Publish — which fields does each method change? Determines the pg_notify payload
8. Story links — connect each story to its artifacts (inline with story save)
9. Checklists — CAN/DENIED checks that verify permission enforcement (see guidance below)
10. Export — bun model export to generate the spec

Metadata

The model database has a key-value metadata store for application-level information. Use it to capture anything that describes the app being built — theme, project name, target audience, etc.

bun model save metadata '{"key":"theme","value":"60s flower power — warm oranges, earthy browns, groovy rounded shapes"}'
bun model save metadata '{"key":"name","value":"My Chat App"}'
bun model list metadata              # list all
bun model delete metadata '{"key":"name"}'   # remove a key

All metadata is included in export output as a ## Metadata section. The /implement skill reads the theme value (if present) to guide CSS generation. The Easy website displays all metadata on the Stories page.

Account Entity

Simple's auth system provides a user table (id, name, email). In the model, represent this as an Account entity — you must add it before referencing it in relations or expansions:

bun model save entity '{"name":"Account","fields":[{"name":"id","type":"number"},{"name":"name","type":"string"},{"name":"email","type":"string"}]}'

The /implement skill maps Account to the existing user table — it does not create a separate table.

Actor Conventions

• visitor — unauthenticated, can only access public documents (doc functions that skip permission checks)
• Named roles (member, admin, creator) — authenticated via token on WebSocket connect
• Permission checks in mutation functions verify the caller matches (e.g. @author_id)

Publish — What Changes

When a method changes fields on an entity, those fields are "published" in the model. This tells /implement what the mutation function's pg_notify payload should carry — the data field includes the changed row, and the targets array tells the server which clients to notify.

• A method that updates existing fields (rename, status change) → publish those field names
• A method that creates a new child (add message, add tag) → the child entity's Changes section (computed from expansions) lists which documents and collection paths are affected

Rule of thumb: publish captures what changes. Change targets capture where the change appears in document trees.

Key Principles

• Stories drive everything — start with what users need
• Documents are screens — each maps to a client openDoc(fn, id) call and a postgres doc function
• Entities own methods — methods go on the entity they mutate, not the document
• Publish for field changes — all clients with the document open see the update
• Permission checks live in SQL — the server just relays
• Auth from actors — visitor stories → public documents; named roles → auth required

Permission Paths

Permission paths use a DSL to express who can call a method. A path resolves to a set of user IDs — if the current user is in that set, access is granted. Multiple paths on the same method use OR logic.

In Simple, these translate to SQL permission checks in mutation functions (e.g. IF p_user_id != v_author_id THEN RAISE EXCEPTION 'permission denied').

Syntax

@field->table[filter]{temporal}.target_field

Examples

Direct ownership — entity has a user_id column:

@user_id

In SQL: IF p_user_id != v_row.user_id THEN RAISE EXCEPTION 'permission denied'

Organisation membership — user acts for the org that owns this entity:

@owner_id->acts_for[org_id=$]{active}.user_id

Reads: "Take the entity's owner_id, look up acts_for rows where org_id matches and the row is active, return user_id — if the current user is in that set, allow."

Multi-hop — traverse through an intermediate entity:

@venue_id->venues.org_id->acts_for[org_id=$]{active}.user_id

Role-restricted — only admins of the org:

@owner_id->acts_for[org_id=$,role='admin']{active}.user_id

CLI

bun model save permission '{"method":"Organisation.createVenue","path":"@owner_id->acts_for[org_id=$]{active}.user_id","description":"User must be active member of the organisation"}'

Checklists — Avoiding Overlap

Methods already capture permissions and publish as the single source of truth. Checklists are integration test scenarios — they should NOT restate what methods already describe.

DO use checklists for:

• Denied paths — proving someone can't do something (e.g. "user B cannot edit user A's post")
• Document-level behaviour — what appears/disappears from collection queries after an action (e.g. "published post appears in PostFeed")
• Sequenced flows — ordered multi-step scenarios using dependencies
• Cross-cutting concerns — behaviour that spans multiple methods or documents

AVOID in checklists:

• Restating that a method publishes a property (already on the method)
• Restating permission checks (already on the method)

When in doubt, ask: "Is this already expressed on a method?" If yes, don't add a checklist check for it.

For full CLI reference and detailed examples, see reference.md.