Building on Zvessa
Everything a person, a developer or their AI needs to build anything on Zvessa, and everything the system gives them from the first minute. Start here.
The idea in one line. A space is one JSON document, the blueprint. Pages, blocks, styles, words, roles, data shapes, mini-apps and kits all live in it. You build by changing it: ask the AI, tap in HQ, or call the API. Every change is checked, saved as a version and can be undone.
What you get from the start #
Every new space has, with no setup:
| You get | What it is | Page |
|---|---|---|
| A dashboard | HQ, a hello page and the AI chat (tabs on phones, side by side when wide) | Blueprint |
| The AI builder | Describe anything; it proposes a change you approve | AI |
| Versions and undo | Every save is kept; undo is one tap and can itself be undone | Blueprint |
| Blocks | Layout, words, media, data, chat, coins, games, bookings, charts, calls, TV | Blocks |
| Styles | Classic and Futuristic, plus any style you or the AI write | Styles |
| People | Roles you name, seven permission verbs, invites, friends, visibility and join rules | People |
| A kit library | Dozens of optional features; none is on until you add it | Kits |
| Engines | Data, talk, levels, coins, games, calls, media, TV, bookings, counts, apps, connections, kids | Engines |
| Mini-apps | Any HTML game or tool, sandboxed, matching your style, paused when hidden, with a bridge to the phone and the space, 21 starters and a public library | Mini-apps |
| Device features | Native icons, video, audio, photos, files, push, calls; more as blocks need them | Device |
| Build from anywhere | An MCP server and the same API the app uses, under the same permissions | API |
| Templates | Business, Personal, Feeds, Journal and Photo book starters, or a purpose (team, family, kids…) with kits picked for it | Templates |
| Safety built in | Permissions, hidden data, kids rules, a key vault, safe outside calls and limits, all on the server | Security |
Calls and live rooms, big videos, push notifications and the key vault run on services the platform already provides (docs/LIVE.md, docs/CAPABILITIES.md).
How to read these docs #
- Want to build something? Read Quick start, then the recipe closest to it.
- Writing a block, kit or engine? Blocks, Kits, Engines.
- Writing a mini-app or game? Mini-apps, then Performance.
- Need the exact list of what exists? Catalog is generated from the code.
| Page | What's in it |
|---|---|
| QUICKSTART.md | Getting started, your first change three ways, recipes |
| BLUEPRINT.md | Every field of the blueprint, ids, changes (JSON Patch), checks, versions |
| BLOCKS.md | Every block, how blocks are drawn, adding a block |
| STYLES.md | Styles as data, colour formulas, layers, recipes |
| DATA.md | Collections, fields, records, events and analytics |
| PEOPLE.md | Roles, permissions, visibility, invites, hidden pages and blocks |
| KITS.md | What a kit is, the library, writing a kit |
| ENGINES.md | The 14 engines underneath every kit, what each stores and does |
| MINIAPPS.md | The sandbox, the style, the bridge and every call, the public library, starter mini-apps |
| AI.md | The builder AI and its tools, the MCP server, keys and connections, bots |
| NOTIFY.md | Notifications: topics, each person's choices (on, digest, off, quiet hours, pause), space settings, blocks, tools, notify() for kits |
| ACCOUNT.md | Account basics: change email or password, sign out elsewhere, forgot password, delete my account |
| AI-JOBS.md | How AI work runs: streaming replies, Stop, background builds, model sizes (/ai/model), AI notes, and starting jobs from bots |
| AI-LIMITS.md | How much AI each person and space may use: server and space limits, /ai/limits, what counts, the limit message |
| DEVICE.md | Native features: icons, haptics, sensors, media, push, and their permissions |
| PERFORMANCE.md | Budgets every block, kit and mini-app keeps: battery, heat, size |
| API.md | Every server function, who may call it, what it returns |
| TEMPLATES.md | Starting points: the five starters, picker covers, onboarding purposes, making a template |
| SECURITY.md | What the server guards, and its limits |
| CATALOG.md | Generated: every engine, block, kit, permission and field type |
Status words #
Each page marks what exists today:
- Ready: works in the app now.
- Being built: designed and partly in the code, not usable yet.
- Planned: decided, not started. The shape here is the plan and may change.
The rules that make it work #
These hold for anything you build (from CLAUDE.md):
- Abstract, never one use case. A
statis a number with a label, not a "streak counter". - Every word and every look is a setting in the blueprint.
- The AI proposes, a person approves, every version can be undone.
- No user code inside the app. Custom logic runs only in the mini-app sandbox.
- Looks come from the style. Nothing writes its own colour, font or size.
- Features are kits on engines. A new engine only when no engine can express it.
- Light on the device. Nothing runs when it can't be seen (
useLive(), Performance).