Building Apps on the Cloud

This skill covers everything you need to build a complete app. For platform overview and auth concepts, see the cloud skill. For deployment, see cloud-ops.

Detailed references: Backend patterns → references/backend.md | Frontend patterns → references/frontend.md

What Belongs In An App — And What Does NOT

Apps are domain features on top of the platform. They must not redefine platform primitives.

Keep out of apps — these live in packages/cloud/ (core):

• Auth flows, session semantics, role/permission logic — every container shares the same auth model. A new login flow or role type is a core change, not an app change.
• The auth.* schema and anything that writes to it — user/group/access/account-request/deleted-account tables are owned by core. Apps reference auth.users(id) via foreign keys; they never migrate or mutate those tables directly.
• Account lifecycle, IPA sync, provider switching, magic-link issuance — these are platform invariants.

The existing accounts app (packages/accounts/) is pure admin UI backed by @valentinkolb/cloud/services/accounts. It owns no schema, no service layer, no lifecycle. It exists so operators can fork or replace the admin frontend without touching auth semantics. If you find yourself wanting to add auth logic there, move it to packages/cloud/src/services/ first — then consume it from the app.

Good app candidates: domain features (files, notebooks, spaces, quotes, weather), tools, reporting. Anything where swapping the app out wouldn't change how users log in or what roles mean.