Core concepts
Five ideas explain how every Appbricx app works. Knowing them helps you write better prompts, read what your agent reports and fix problems quickly.
1. The contract: the app in one file
An Appbricx app is described by one JSON document, the contract. It names the people who use the app, the tables and fields, who may read and change which rows, the rules every write must pass, the workflows, the seed data, the pages and any custom React screens. Your agent or the builder writes it; Appbricx builds everything else from it.
{
"app": { "name": "Stillwater", "brand_color": "#2F7D6D" },
"auth": { "google": true },
"personas": [
{ "id": "member", "label": "Member", "kind": "consumer" },
{ "id": "instructor", "label": "Instructor", "kind": "staff" }
],
"entities": [
{ "name": "session", "fields": [
{ "name": "title", "type": "text" },
{ "name": "starts_at", "type": "timestamp" },
{ "name": "capacity", "type": "number" } ] }
],
"workflows": [],
"pages": []
}Because the app lives in one file, any later session (or the builder) can read it with get_contract and carry on. Every key is listed in the contract format reference.
2. Dev and prod: two databases per app
Every app has a development database (behind the preview) and a production database (behind the live app). Applying the contract changes dev only. Publishing copies the schema changes to prod.
- Changes are additive. New tables, fields and indexes are added; rows are kept. A removed field leaves the app but its column and data stay.
- Destructive changes wait. Dropping a column or table only happens on a publish that explicitly allows it.
- A backup comes first. Production is snapshotted before every publish, and before any change you make to production data by hand.
- Your own SQL is kept. Indexes, views, functions and tables you add by hand survive apply and publish. See operating your app.
3. Roles and access, enforced by the database
A persona is a kind of user (member, instructor, dispatcher). Each has a kind: consumer personas sign up and act through the app's pages; staff personas manage shared records. From the personas, the pages and any explicit accesssettings, Appbricx derives who may read, create, update and delete each table, and enforces it with Postgres row-level security. A bug in a screen can't leak another user's rows. See access and roles.
For conditions that depend on the data ("not when the class is full"), add business rules.
4. Verify: tested as every user
verify checks a release the way a careful tester would, in three stages: static (the contract, page reachability, a type check), data (signs in as each role, tries every action on every table, checks signed-out visitors and workflows) and browser (opens every page as each role). Each failure comes with evidence and a fix. A deploy refuses to go out while verify is red. See verify.
5. Publish: a live link, with a way back
Publishing puts the app on https://<name>.apps.appbricx.com or your own domain. Each publish is recorded, so you can roll back the served files to an earlier deploy, and restore the data from any of the last 30 snapshots. See publishing, domains and rollback.
The loop, end to end
| Step | MCP tool | CLI | What happens |
|---|---|---|---|
| Read | get_contract | appbricx pull | The current contract, or none for a new app |
| Check | check_contract | appbricx check | Errors, fixes and warnings. Nothing changes |
| Apply | apply_contract | appbricx apply | Builds dev: database, access, pages, workflows. Lists demo sign-ins |
| Look | screenshot | A real browser opens the preview as a role | |
| Verify | verify | appbricx verify | Static, data and browser checks |
| Deploy | deploy | appbricx deploy | Verify again, snapshot prod, publish |