Engineering briefing — architects & security teams
Sherlock
The Technical Briefing
How the platform is put together: the runtime, the trust boundaries, and the seams where it extends. Diagrams and decisions — the marketing stayed in the other deck.
01 — Architecture
Three tiers.
One seam.
Web renders and orchestrates; the worker executes; Postgres is the only state. Every box is replaceable because every seam is explicit.
02 — Execution engine
Durable execution,
not fire-and-forget.
Webhook (with a test mode), email, chat, schedule, manual and sub-workflow triggers — work starts wherever work arrives.
Draft → publish → activate. Workflows are versioned; runs are pinned to the version that started them.
If/else routing, merge nodes, call-workflow composition, and in-flow responses for synchronous webhook and chat replies.
03 — Agent runtime
Agents are bounded loops,
not vibes.
The model reasons, calls tools, sees results, repeats — capped by a hard maxTurns ceiling and abortable mid-loop via a cancellation signal.
REST connectors, data stores, whole workflows — any registered capability can be handed to an agent, with typed parameters.
Credentials decrypt only at execution, inside the worker. The model sees masked secret fields in tool descriptions — never values.
Full transcript plus a structured event for every tool call — arguments, results, timing — straight into the audit trail.
04 — Nodes & SDK
Capability ships
as nodes.
A node is a typed definition plus an execute(). The visual builder renders its configuration UI from the definition — no UI code per node.
Triggers, logic, actions, stores — and an AI set: classify, detect intent, extract structured, tag, validate, agent.
Confidence gates route uncertain AI outputs to humans instead of guessing — accuracy by architecture, not by hope.
A JavaScript node covers the long tail; the @apg/node-sdk package makes custom nodes first-class citizens of the builder.
import type { Node } from "@apg/node-sdk"; export const ifNode: Node = { definition: { type: "logic.if", displayName: "If", inputs: [{ name: "main" }], outputs: [{ name: "true" }, { name: "false" }], properties: [{ name: "conditions", type: "conditions" }], }, execute: async ({ params, items, itemIndex }) => { const item = items[itemIndex ?? 0]!; return passes(params) ? [[item], []] : [[], [item]]; }, };
Abridged from packages/nodes-core/src/logic-if.ts — the real contract
05 — Security model
Supabase Auth with public signup disabled. The first admin is bootstrapped on the server — no seeded credentials.
admin / editor / user. Middleware gates navigation — business users never reach the builder surfaces.
Postgres row-level security is the data backstop: every query is filtered at the database, not in application code.
Credentials encrypted AES-256-GCM at rest, decrypted only at execution in the worker. The key round-trip is the DR gate.
Execution traces and tool-call events for every run — with sensitive values redacted before they reach any log.
Five layers between
a request and your data.
None of this is an add-on module. The layers below are the foundation the features are built on — they apply to every workflow, agent and app, including the ones you build yourself.
Chat sessions are isolated per user — no context bleed between conversations.
A reserved egress-allowlist contract for air-gapped installs — outbound reach is a deployment decision, not an accident.
06 — The model seam
Models are a config choice,
not an architecture choice.
Core42 Compass (UAE cloud) and fully local Ollama are first-class providers — not afterthoughts bolted onto a US-cloud default.
Provider credentials live in the encrypted vault and are selected per agent and per node — different minds for different jobs.
Agents reference a provider + model pair. Changing the mind behind a workflow is configuration, not a migration.
Embeddings serving is reserved for the RAG stack; vLLM / TGI for GPU clusters slot in behind the same interface.
07 — Deployment
One artifact. Three postures.
Managed VM
- One-shot install.sh — full stack via Docker Compose
- Caddy TLS at the edge; Supabase routed through it
- Push-to-main CI/CD — reference deployment on Azure
- Uptime Kuma + /healthz · /readyz health aggregation
- Scheduled backups + a tested DR runbook
On-prem
- The same compose artifact on your hardware
- Version-pinned Supabase CLI stack — zero cloud assumptions
- systemd units for boot-time supervision
- Encryption-at-rest (LUKS) procedure documented
- All access env-driven — no hardcoded endpoints
Air-gapped
- Image + model staging scripts (deploy/airgap)
- Ollama models pre-pulled at install time
- Reserved EGRESS_ALLOWLIST contract
- Central egress enforcement on the roadmap
- GPU serving (vLLM/TGI) behind the LLM seam
Same artifact in all three — posture is configuration, not a fork.
08 — Engineering roadmap
The hard problems, sequenced.
In build
Current sessions- HITL pause/resume — durable suspension of in-flight runs, role-routed approvals
- RAG stack — vector store, ingest / semantic search / cited-answer nodes
- Document intelligence — Arabic & English OCR, classification, structured extraction
- Guardrail nodes — PII masking, injection scan, toxicity filter
Next
Designed- Inter-agent delegation — supervised agent-to-agent handoff
- llm_calls metering — enforced cost ceilings, per-user and per-agent quotas
- Arabic-first i18n with full RTL across every surface
- Trace explorer + approval queue oversight UIs
Horizon
Sequenced- DTS engine — consume ministry-authored decision trees
- Sandboxed Python runtime for custom agent logic
- Red-team harness as a blocking pre-production gate (OWASP-LLM)
- SAML / OIDC / LDAP and UAEPass identity
Source of truth: docs/ENTERPRISE_ROADMAP.md — every item tagged to an RFP capability.
09 — The challenge
Bring your hardest workflow.
A working session, not a sales call: we model one of your real processes in the builder, wire it to your systems, and leave it running in your instance.