Build Your First App (App Studio)

Before You Put It in Front of Users

Overview

From Description to Running App

• •Describe your app — write what you want in plain English: the entities, how they relate, and who uses the app. You can also start from a reference screenshot instead of typing, and App Studio will extract a starting description from it.
• •Review the brief — App Studio elaborates a short description into a fuller requirements brief you can read and edit before anything is generated, so the result matches what you meant.
• •Generate the backend — App Studio produces your schema (entities, fields, relationships), access policies, and starter seed data. Review this first: it is the foundation everything else is built on.
• •Choose your UI — pick an app name and emoji, a colour theme, a tone for the AI-written copy, how people sign in, and which entities appear on the landing page.
• •Generate the app — App Studio builds the web UI on top of the backend you reviewed. Generated applications target the web; a mobile surface is not part of the bundle.
• •Deploy — publish your app to an address the platform generates for you. This is the one step in this list that your plan can refuse; see Deploying Your App below.
• •Iterate — describe the next change in plain English and regenerate with your current app as context, or edit the generated files directly for full control.

What App Studio Generates

Task = {
    "schema_type": "object",
    "name": "Task",
    "namespace": "myapp",
    "parent_type": "tenant",
    "description": "A unit of work owned by a tenant.",
    "attributes": [
        {"name": "title", "type": "string", "mandatory": True},
        {"name": "status", "type": "string", "values": ["todo", "in_progress", "done"]},
        {"name": "due_date", "type": "datetime"},
        {"name": "priority", "type": "integer"},
        {"name": "owner_username", "type": "string"},
    ],
}

Choosing Your UI

Access Policies App Studio Generates

from supero.app_setup import PolicyDef, PolicyRule

access_policies = [
    PolicyDef(role="tenant_admin", default_access="full", rules=[]),
    PolicyDef(role="tenant_user", default_access="full", rules=[
        PolicyRule(entity="task", can_read=True, can_create=True, can_update=True,
                   filter_field="owner_username", filter_match="$user.name"),
    ]),
    PolicyDef(role="viewer", default_access="none", rules=[
        PolicyRule(entity="task", can_read=True),
    ]),
]

Deploying Your App

https://live-{domain}-{project}.supero.live

Preview and Go Live are not the same deployment

Iterating on Your App

• •Describe the change — tell App Studio what to change in plain English (for example, "add a due_date field to tasks" or "let managers see every team's tasks") and it regenerates using your current app as context, rather than starting over.
• •Edit the files directly — the generated schema, UI, and setup files are plain, readable source. Open them and change them by hand for full control, then redeploy.

When Something Goes Wrong

Generation fails, or the progress stops updating

• •The build runs on the server, not in your browser. If the page goes quiet — a sleeping laptop, a network change, a throttled background tab — the job has usually carried on and finished. Reopen the project in App Studio before regenerating anything: the most recent bundle is listed there with its own download and launch actions, and regenerating would only spend another app generation.
• •A generation that genuinely fails ends with an error rather than going quiet. Re-run it with a shorter, more concrete description — a brief asking for several apps at once is the failure that repeats.
• •App generations are metered per month by plan. Once that allowance is spent the request is refused with a plan response rather than an error you can retry — see Plans & Billing.

The app builds but a screen is empty

• •Not every entity gets sample rows. App Studio writes one coherent narrative worth of seed data, and entities at the edge of that narrative — along with anything meant to fill at runtime, such as carts and order lines — routinely ship with zero rows. On a brand-new app, an empty tab is far more often "nothing was seeded here" than "the read failed".
• •Check which account you are signed in as. A generated rule can scope a role to its own records, so a screen that is full for the admin account is legitimately empty for a demo user.
• •A list read is scoped to the project carried in your credential, and answers with 200 and an empty array rather than an error when it finds nothing there. An empty list is also how some denials are expressed — see Errors & Status Codes before concluding a table is empty.
• •If the entity came from a later regeneration, confirm you regenerated the UI and then deployed. Until that deploy, the entity has no screens and no table.

A button or service call appears to do nothing

• •Transactional service calls report failure inside a success response. POST /api/v1/services/execute returns 200 with success: false plus error, error_code and status_code in the body, so a client checking only the status sees a call that silently did nothing. Branch on the body, not the status — see Transactional Services.
• •An illegal state transition arrives in several wrappings — a 409, a 200 with success: false, or a plain string with the payload embedded in the error text. Match on INVALID_STATE_TRANSITION wherever it appears rather than on the status code.
• •If workflows or event bindings never fire, check that "workflows" is the last entry in the services list in the generated config. An out-of-order list drops that registration with no error at all — see Anatomy of a Supero App.
• •A write that returns success but changed less than you asked for is usually field-level policy: fields a role may not write are stripped from the payload rather than refused. Read the record back and compare.

A deploy hangs, or never produces a URL

• •Publishing is asynchronous. The call is accepted immediately and the deployment moves from launching to running or failed, so App Studio polls rather than blocking. A deployment sitting in launching is still building; give it a few minutes before treating it as stuck.
• •An upgrade prompt where the link should be is the plan gate, not a failure — see Deploying Your App above. Downloading the bundle and running it yourself is unaffected.
• •A preview on a plan without a live-deployment allowance expires on its own, so an address that worked earlier and now does not has most likely been reaped rather than broken. Relaunch it, or publish properly on a plan that includes a live deployment.
• •If the deploy succeeds but the app does not reflect your change, check that you deployed after the change. Regenerating and hand-editing both leave the live app untouched until the next deploy.

Next Steps

• •Schema Reference — model entities, fields, and relationships in depth, including editing the generated schema by hand.
• •Dynamic UI — how the UI is generated from your schema and how to customize individual views.
• •Access Control — the full role and policy model, including custom roles and field-level rules.
• •In-App AI Agent — the built-in chat every generated app ships with for its end users.
• •Plans & Billing — which plan includes a live deployment, and how app generations are metered.
• •Errors & Status Codes — the failures that arrive as a 200, and the triage order that resolves most of them fastest.