Solution Development
Solution Development is how you build complete, branded business applications on Qefro: a restaurant manager, a hospital front desk, a CRM, a hotel property system, a school administration portal, or an inventory back office — all shipped as a single installable package.
The SDK process is the application (ADR-003):
domain logic lives in required src/ (Node / Rust / Python) on signed
/qefro. Optional YAML workflows, prompts, and UI only orchestrate and
present. Solution-owned documents persist via
managed storage from inside the SDK
(ctx.storage). External systems of record stay behind pool connectors.
Start here: Build your first app
(qefro create-app warehouse-pro → publish → install).
YAML-only packages that call storage/* from workflows or UI sources are
incorrect. See Managed apps.
What you can build
Any business domain that fits the Qefro model — an SDK app with tools, optional workflows/events, managed storage and/or pool connectors, and an optional portal-rendered UI — can be packaged as a solution:
| Domain | Typical pages | Typical data plane |
|---|---|---|
| Restaurant management | Dashboard, reservations, tables, kitchen, orders, payments | SDK + managed storage (+ optional POS) |
| Hospital management | Appointments, wards, billing, duty roster | SDK + storage + HMS connectors |
| CRM | Pipeline, contacts, activities, reports | SDK + storage + CRM hub |
| Hotel management | Rooms, bookings, housekeeping, folios | SDK + storage + PMS |
| School management | Classes, attendance, fees, timetables | SDK + storage + SIS |
| Inventory management | Stock levels, transfers, purchase orders | SDK + storage + WMS |
Throughout this section, restaurant-pro
is the canonical reference solution. Every concept page uses it as the
running example.
Core principles
- The SDK process is required. Business logic runs in
src/on/qefro. The platform must not encode domain rules (reservation, menu, …). - UI is declarative data. Theme, nav, pages, and widgets are YAML — no package JS in the portal UI (no iframes, no injected scripts).
- Capability mediation is mandatory. Host interactions pass through the capability registry; negotiated at install and re-checked on every call.
- Event-driven communication is mandatory. Solutions react to the
platform event bus and emit
ui.*lifecycle events — no out-of-band signaling. - Persist only via
ctx.storage. Workflows/UI call app tools ({solution}/{tool}), neverstorage/*directly.
Platform rules
These rules are enforced at publish time and at render time. Packages that violate them are rejected:
| # | Rule |
|---|---|
| 1 | No arbitrary JavaScript |
| 2 | No direct DOM access |
| 3 | No iframe execution |
| 4 | No direct database access |
| 5 | No direct Redis access |
| 6 | No direct network access |
| 7 | Capability mediation is mandatory |
| 8 | Event-driven communication is mandatory |
See Security model for how each rule is enforced.
The delivery pipeline
A solution travels a fixed pipeline from your editor to a tenant's portal:
| Stage | Responsibility | Details |
|---|---|---|
| Solution package | Required src/ SDK + optional UI/workflows/connectors | Package structure |
| Registry | Signed global catalog (platform-admin publish only) | Publishing |
| Installer | Activation, capabilities, installation binding | Installation |
| Runtime | Executes workflows, serves runtime data sources | Workflows |
| SDK app | Domain tools on /qefro | Managed apps |
| Managed storage | Documents via ctx.storage → Mongo | Managed storage |
| Connector bridge | External pool connectors | Connectors |
| Portal renderer | Declarative pages/widgets/themes | Pages |
The full architecture is covered in Architecture.
Package structure
Prefer qefro create-app <id> — see App scaffold.
Every solution is a directory with this layout:
restaurant-pro/
├── manifest.yaml # identity, hosting, endpoint, permissions, settings
├── src/ # required — SDK application (/qefro)
├── package.json # and/or Cargo.toml / pyproject.toml
├── Dockerfile # required for hosting: managed
├── assets/ # images only (png/jpg/jpeg/svg/webp)
├── workflows/ # optional — tool steps → {solution}/{tool}
├── connectors/ # optional — external pool connector contracts
├── ui/ # optional declarative staff UI
│ ├── theme.yaml
│ ├── navigation.yaml
│ ├── pages.yaml
│ ├── layouts.yaml
│ ├── widgets.yaml
│ └── sources.yaml # runtime | {solution}/{tool} | pool connector
└── README.md
YAML sources are assembled into a canonical JSON package, checksummed and signed at build time — see Packaging.
Documentation map
| Topic | Page |
|---|---|
| Managed apps (start here) | Managed apps |
| Platform architecture | Architecture |
| Build your first solution | Quickstart |
| Tenant-side activation | Installation |
manifest.yaml reference | Manifest |
| Branding | Themes |
| Sidebar + routes | Navigation |
| Pages & layouts | Pages · Layouts |
| Widgets | Metric · Table · Chart · Markdown · Form · Timeline |
| Host capabilities | Capabilities |
| Event model | Events |
| Data sources | Sources |
| Managed document storage | Managed storage |
| Images & branding files | Assets |
| Connector dependencies | Connectors |
| Workflow definitions | Workflows |
| Publish-time checks | Validation |
| Building a signed package | Packaging |
| Publishing to the registry | Publishing |
| Security model & rules | Security |
| Fixing common failures | Troubleshooting |
| Complete reference solution | restaurant-pro |
How this differs from playbooks
Solution playbooks are outcome-oriented guides that compose existing platform features (customer support, order tracking, refunds). Solution Development produces new installable packages with their own manifest, UI, workflows and data-plane requirements (managed storage and/or connectors).
Related platform concepts
- Runtime — the execution engine that runs installed workflows.
- Events — the platform event bus that solutions ride.
- Managed storage — document plane via
ctx.storage(SDK-only). - Connectors — stateless integration containers behind the bridge.
- Business Flows — the flow model workflows compile to.