Skip to main content

Solution Development

Solution Development is how you build complete, branded business applications on Qefro: a restaurant manager, a clinic front desk, a real estate CRM, a booking product — shipped as a single installable package.

A Qefro Marketplace App is a declarative package, not an SDK server. Developers do not need a backend to create Restaurant, Clinic, Real Estate, Booking, or CRM apps. Qefro Runtime executes the metadata: UI, entities, storage, Business Flows, Business Events, CRM, and Automation.

Default developer story:

Developer → Create App Metadata → Validate → Package → Publish
  → Install into Workspace → Qefro Runtime
qefro app init restaurant-pro
qefro app validate restaurant-pro
qefro app package restaurant-pro
qefro app install restaurant-pro

Start here: Build your first app using restaurant-pro-runtime.

Runtime vs SDK

Build a Qefro Marketplace App with metadata. Use the SDK only to connect an external ERP, POS, or CRM. See Runtime vs SDK.

What is a Qefro Marketplace App?​

An installable YAML package with hosting: runtime. Identity, entities, workflows, events, UI, and permissions live in the package. After install, Qefro Runtime:

  • renders dashboards, tables, forms, detail pages, navigation, and widgets
  • persists entities in managed storage (no direct DB)
  • compiles workflows/ into the same BusinessFlow / FlowRunner as every other flow
  • emits business events that CRM Automation can consume
  • hosts Contacts (host: contacts) and Automations (host: automations)

You never run npm run dev on a /qefro process for this path.

What you can build​

Any business domain that fits entities + flows + UI:

DomainTypical pagesData plane
RestaurantDashboard, reservations, tables, menuRuntime entities + managed storage
ClinicAppointments, patients, scheduleRuntime entities + managed storage
Real estateProperties, leads, viewingsRuntime entities + managed storage
CommerceProducts, customers, ordersGeneric Runtime HTTP (Shopify) or entities
CRM / bookingPipeline, contacts, bookingsRuntime entities + Person CRM

Canonical references:

PackageApp idRole
restaurant-pro-runtimerestaurant-pro-runtimeHospitality metadata app
real-estate-runtimereal-estate-runtimeSame model, different nouns
shopify-runtimeshopify-runtimeCommerce metadata + generic Runtime HTTP

Collection repo: qefro-marketplace-apps (index).

SDK-hosted Marketplace examples (restaurant-pro, clinic-pro, salon-pro) were removed. Build those products as metadata, or connect a real external system with the SDK.

Core principles​

  1. Metadata is the application. hosting: runtime packages ship manifest.yaml, entities/, workflows/, and ui/. No SDK process.
  2. UI is declarative data. Theme, nav, pages, and widgets are YAML — no package JS in the portal UI (no iframes, no injected scripts).
  3. Storage is Qefro-managed. Entity tools such as entity.reservation.create persist documents. No Mongo connection, no direct storage/* from YAML.
  4. Flows compile to FlowRunner. ask → tool → condition → approval / challenge → complete on the same engine as every Business Flow.
  5. Capability mediation is mandatory. Host interactions pass through the capability registry.
  6. Event-driven communication is mandatory. Business events drive automation; ui.* events are observational.

Platform rules​

These rules are enforced at publish time and at render time. Packages that violate them are rejected:

#Rule
1No arbitrary JavaScript
2No direct DOM access
3No iframe execution
4No direct database access
5No direct Redis access
6No direct network access
7Capability mediation is mandatory
8Event-driven communication is mandatory

See Security model for how each rule is enforced.

The delivery pipeline​

StageResponsibilityDetails
App packageMetadata: manifest, entities, workflows, UIPackage structure
RegistrySigned global catalog (platform-admin publish only)Publishing
InstallerActivation, capabilities, workspace installInstallation
Qefro RuntimeUI, entity tools, FlowRunner, eventsArchitecture
Managed storageDocuments for declared entitiesManaged storage
Portal rendererDashboards, tables, forms, widgetsPages

External ERP / POS / CRM integrations take a separate path: SDK → /qefro → Runtime. See Runtime vs SDK.

Package structure​

Prefer qefro app init <id>. The implemented tree (from restaurant-pro-runtime / qefro app init) is:

my-app/
├── manifest.yaml        # identity, hosting: runtime, entities, flows, events, UI, permissions
├── entities/            # domain schemas (required for hosting: runtime)
│   └── record.yaml
├── workflows/           # Business Flows → FlowRunner
│   └── create-record.yaml
└── ui/                  # Runtime-rendered staff UI
    ├── theme.yaml
    ├── navigation.yaml
    ├── pages.yaml
    ├── layouts.yaml
    ├── widgets.yaml
    └── sources.yaml     # type: entity | runtime

There is no src/, no events/ directory, and no automations/ directory. Events are declared on the manifest (events:). Automations are a portal host page (host: automations), not package files.

YAML is assembled into a canonical JSON package, checksummed and signed — see Packaging.

Documentation map​

TopicPage
Runtime vs SDK (read this)Runtime vs SDK
Build your first Marketplace AppBuild your first app
Platform architectureArchitecture
Tenant-side activationInstallation
manifest.yaml referenceManifest
BrandingThemes
Sidebar + routesNavigation
Pages & layoutsPages · Layouts
WidgetsMetric · Table · Chart · Markdown · Form · Timeline
Host capabilitiesCapabilities
Event modelEvents
Data sourcesSources
Managed document storageManaged storage
Images & branding filesAssets
Connector dependenciesConnectors
Workflow definitionsWorkflows
Publish-time checksValidation
Building a signed packagePackaging
Publishing to the registryPublishing
Security model & rulesSecurity
Fixing common failuresTroubleshooting
Canonical metadata apprestaurant-pro-runtime
Second verticalreal-estate-runtime
Commerce metadata appshopify-runtime
SDK-hosted packages (not default)Managed apps

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, entities, UI, and workflows.