Qefro architecture

This page answers: what are the moving parts, who owns what, and where does work run?

Use it when evaluating Qefro, onboarding engineers, or explaining the product to stakeholders. For a shorter intro, see Introduction → Architecture. For multi-tenant isolation details, see Multi-tenant AI Architecture.

One-sentence model

Configure knowledge, tools, and Marketplace apps in the Admin Console; execute chat and flows in a single Runtime (RAG + FlowRunner + event bus); reach customers and employees through channels; run domain logic in installable /qefro SDK apps or via REST/OpenAPI / Backend SDK webhooks. Connectors only emit events — they never run a second orchestrator.

System map

Layers

Layer	Responsibility	Not responsible for
Admin Console (app.qefro.com)	Workspaces, knowledge, Marketplace install, People, Marketing, RBAC, billing UX	Running app / ERP business logic
Runtime	Chat orchestration, RAG retrieval, FlowRunner, event ingest/dispatch, tool invoke, approvals	Hosting your ERP
Solutions plane	Catalog, install/upgrade, managed app lifecycle, capability sync, portal UI render	Per-tenant forks of packages
Channels	Widget, WhatsApp, Internal Portal, chat API	Defining flow graphs
SDK apps (/qefro)	Domain tools, ctx.storage, Hub/marketing/org registrations	Platform campaign delivery / RBAC
Backend SDK Connection	Your tools over signed webhooks (Business Tools path)	Emitting platform-wide events without the bus
Connectors	Normalize external webhooks → Qefro event envelopes (+ optional tool packs)	Owning FlowRunner or long-running workflows
REST / OpenAPI tools	Call APIs with credentials stored encrypted in Qefro	Arbitrary code execution in Qefro

Solutions plane

Installable apps are a first-class plane next to assistants and Business Tools:

Piece	Role
solution-service	Package catalog, installations, settings, capability sync, onboarding
Managed app	Docker (or external) process exposing signed /qefro; ADR-003: the process is the app
Marketplace	Tenant-facing install / upgrade UX over the shared catalog
Portal renderer	Declarative ui/* from the package → staff pages under /app/solutions/…
Capability registries	Apps declare marketing audiences, org workflow caps, etc.; platform owns execution

Deep dive: Solutions architecture, Managed apps, Build your first app.

SDK Connection vs SDK app: a Backend SDK webhook is a Business Tool connection to your backend. An SDK app is an installable Marketplace package with its own /qefro. See Core concepts.

Execution paths (same engine)

All of these eventually use FlowRunner (and/or the chat pipeline) inside one Runtime:

1. Chat intent — user message → model may select a Business Flow or tool.
2. Event — connector or API emits namespace.event → matching flow metadata.trigger.
3. Schedule — cron-style trigger materializes an event → FlowRunner.
4. Webhook — inbound HTTP mapped to an event or flow start.
5. Resume — approval granted or challenge verified continues a waiting run.

There is no parallel workflow engine inside connectors. See Event-driven triggers.

Data and tenancy

Organization (tenant)
  └── Teams + RBAC (Owner / Admin / Member)
        └── AI Workspaces
              ├── Knowledge (indexed documents)
              ├── Marketplace app installations (/qefro)
              ├── Business Tools (REST / OpenAPI / SDK Connection)
              ├── Business Flows (versioned)
              ├── Customer Hub bindings (People)
              ├── Conversations + messages
              └── Channel bindings (widget, WhatsApp, …)

• Knowledge and conversations are workspace-scoped.
• Installable apps are catalog packages installed per workspace (settings overlay).
• Secrets for REST tools are encrypted at rest; SDK secrets sign webhooks to your origin or the managed app.
• Audit and tool invocation logs support support and compliance workflows.

Control vs data plane

Plane	Examples
Control	Create workspace, upload docs, Accept flow version, manage members, configure WhatsApp
Data / runtime	Chat messages, RAG chunks, flow runs, event records, tool.invoke payloads

Operators mostly use the control plane. Developers extend the data plane with tools, events, and Customer Provider.

Identity and trust boundaries

1. Org users — JWT to Admin Console and org APIs.
2. Widget / channel sessions — channel-specific tokens; optional identify() for known customers.
3. Customer Provider — your backend authorizes high-risk tools and challenges (OTP, etc.).
4. SDK webhook — HMAC (or equivalent) over body + timestamp; tools never run unauthenticated against Qefro’s trust of your origin.

Deep links: Identity & authentication, Challenges, Business Tool runtime.

What Qefro deliberately is not

Not this	Why it matters
A general visual automation canvas (n8n-class)	Flows are AI + business process graphs with RAG, channels, and approvals — not arbitrary ETL
A low-level agent graph library (LangGraph-class)	You get a productized Runtime and Admin Console, not a framework you host and invent UX for
A full human contact-center inbox	Human handoff exists; deep agent desktop is not the core product
A replacement CRM / ERP	Qefro calls systems of record via tools and hosts domain apps that use Customer Hub + managed storage — not a full CRM replacement

Comparisons: Qefro vs n8n, Qefro vs LangGraph.

Deployment shapes

• Qefro Cloud — multi-tenant SaaS (typical).
• Self-host / Docker — compose stack (api, llm-service, retrieval, portals, nginx). See Self-hosting and Production deployment.

Mental model for new engineers

First week architecture checklist

1. Draw the tenant tree — Org → workspace → knowledge/tools/apps/channels.
2. Trace one chat tool call — Widget → API → model → tool.invoke → SDK app or Connection → response.
3. Trace one Marketplace install — Publish → catalog → install → /qefro healthy → staff UI.
4. Trace one event flow — Connector emit → bus → FlowRunner → steps → complete.
5. Read security boundaries — What never leaves your VPC (SDK Connection handlers) vs managed apps.

Related topics