App scaffold

Prefer the full walkthrough

Primary path: Build your first app (qefro app init restaurant-pro). This page covers ownership + generated layout. The shorter Quickstart assumes you already have publish credentials.

Ownership model

Tenant
  └── Workspace
        ├── Channels (e.g. WhatsApp — owned by the workspace)
        └── Application (one primary installable app per workspace)

Layer	Owns	Notes
Tenant	Org, users, billing	Portal login boundary
Workspace	Channels + one primary app	WhatsApp number binds to the workspace, not the package
Application	Metadata package (entities, flows, UI)	Shared catalog package; per-workspace install + settings. Qefro Runtime executes it.

Installing a second primary app into a workspace that already has one is rejected. Channel digits (?n= on booking links) come from the workspace WhatsApp binding — do not put whatsapp_business_number in install settings.

See Architecture and Installation.

Create an app (default — metadata)

qefro app init restaurant-pro --name "Restaurant Pro"
cd restaurant-pro
qefro app validate .

(qefro app init aliases qefro create-app.)

Generated layout

restaurant-pro/
├── manifest.yaml          # id, version, hosting: runtime, entities, flows, events
├── entities/              # required — domain schemas
│   └── record.yaml
├── workflows/             # Business Flows → FlowRunner
│   └── create-record.yaml
└── ui/
    ├── navigation.yaml
    ├── pages.yaml
    ├── widgets.yaml
    └── sources.yaml       # type: entity

No src/, no Dockerfile, no /qefro endpoint.

Reference verticals

App	Docs	Path (platform repo)
Restaurant Pro Runtime	example	apps/restaurant-pro-runtime/
Real Estate Runtime	example	apps/real-estate-runtime/
Shopify Runtime	example	apps/shopify-runtime/

Trees live in qefro-marketplace-apps.

SDK connection scaffold (not a Marketplace App)

Use this only to connect an external ERP, POS, or CRM:

qefro create-app my-erp --hosting external --endpoint https://api.example.com/qefro
qefro create-app my-erp --hosting external --minimal   # hello-only SDK stub

export QEFRO_APP_TEMPLATE=/path/to/templates/sdk-app-starter

That copies templates/sdk-app-starter (src/ + /qefro). This is not how you build Restaurant, Clinic, or Real Estate Marketplace Apps.

See External SDK Connection.

From scaffold to live

1. Edit entities, workflows, and UI YAML.
2. qefro app validate .
3. qefro app package . — validate + sign.
4. Platform admin publishes — see Publishing.
5. Tenant installs into a workspace — see Installation.

important

Tenants and workspace admins install apps. Only platform admins publish versions into the global catalog.

Related topics

• Build your first app — primary path
• Runtime vs SDK
• Managed apps — SDK-hosted packages
• Manifest — package identity
• Publishing — platform-admin-only catalog write
• Quickstart — shorter loop