Skip to content

Architecture Overview

This guide explains how Zakardo’s components fit together, how data flows through the system, and the architectural decisions that shape the framework.

Zakardo operates as a runtime layer inside your application server. It does not own your HTTP server, database, or frontend — it integrates with them:

flowchart TB
subgraph app [Your Application]
subgraph hono [Hono HTTP Server]
FL[Foundation Layer]
ZR[Zakardo Runtime]
end
DB[(Your Database)]
FE[Frontend App]
end
FE -->|REST + SSE| hono
FL -->|CRUD, Auth| DB
ZR -->|DataAdapter| DB

The backend has two distinct layers mounted on the same Hono server:

Standard backend functionality that does not go through the Zakardo execution model:

  • Authentication — user sessions, OAuth, tokens (Better Auth or custom)
  • Authorization — role-based access control
  • CRUD endpoints — standard data operations
  • Webhooks — external event handlers
  • Background jobs — scheduled tasks
  • Billing — subscription management

The agent execution model — everything that involves intents, plans, and capabilities:

  • Planner — translates intents into plans
  • Enrichment Pipeline — converts drafts to full IR
  • Validator — verifies plans are safe
  • Execution Engine — runs validated plans
  • Policy Engine — governs capability execution
  • Trace System — records execution history
  • Plan Library — stores and promotes plans
  • Training System — validates plans against datasets
const app = new Hono();
// Foundation Layer — your standard backend routes
app.get('/api/users', getUsers);
app.post('/api/auth/login', login);
// Zakardo Runtime — agent execution routes
app.route('/zakardo', zakardoApp);

Every intent flows through a fixed pipeline:

flowchart LR
I[Intent] --> P[Planner]
P -->|GENERATE| D[Plan Draft]
P -->|CLARIFY| C[Clarification]
P -->|CONVERSE| R[Conversation]
D --> E[Enrichment]
E --> IR[Full Plan IR]
IR --> V[Validator]
V -->|Pass| EE[Execution Engine]
V -->|Fail| ERR[Validation Error]
EE --> T[Trace]
EE --> A2[A2UI Response]

The user submits an intent via REST API. The Planner classifies it.

For actionable intents, the Planner uses backward chaining: start from the goal, find capabilities that produce the desired output, check if their inputs are available, and recursively fill gaps.

The deterministic Enrichment Pipeline converts the Planner’s minimal draft into a fully typed Plan IR:

  1. Capability Resolution — resolve names from registry
  2. Schema Inference — infer input/output schemas
  3. Binding Conversion — convert draft bindings to path expressions
  4. Condition Conversion — structure conditional logic
  5. Dependency Analysis — compute depends_on from data flow
  6. Index Assignment — assign step indices and output keys
  7. Metadata Generation — plan ID, version, name
  8. Default Policies — error handling, retry, constraints

All 10 checks run regardless of earlier failures:

  1. Plan structure, 2. Capability availability, 3. Version validity, 4. Schema compatibility, 5. Binding validity, 6. Dependency graph (DAG), 7. Effect mode compatibility, 8. Policy compliance, 9. Constraint satisfaction, 10. Sub-plan depth

The Execution Engine is a durable state machine:

  • Checkpoints after every state transition — survives process restarts
  • Sequential execution in v1 (parallel is computed but deferred)
  • Retry for transient failures with exponential backoff
  • Gates pause for human approval on governed operations
  • Outbox stages external side effects, commits only on full success

Every execution event is written to an immutable, append-only trace.

Zakardo does not own your business data. The DataAdapter contract provides a thin bridge:

flowchart LR
CE[Capability Execution] -->|Your ORM| DB[(Your Database)]
CE -->|Output| EC[Execution Context]
EC -->|Binding| NS[Next Step Input]
EE[Execution Engine] -->|Checkpoint| ZS[(ZakardoStore)]
EE -->|Trace Entry| ZS
  • Business data: Capabilities access your database through your ORM (Prisma, Drizzle, etc.)
  • Runtime data: Execution checkpoints, traces, policies, and outbox entries are stored in ZakardoStore (SQLite by default)

The Execution Context is the runtime accumulator that holds all data flowing through a plan:

$context.plan.inputs.* → Plan-level inputs
$context.steps.step_0.output.* → Step 0 output
$context.steps.step_1.output.* → Step 1 output
$context.interaction.step_2.* → User interaction responses
$context.system.* → System metadata (timestamp, user, mode)

Steps reference data from previous steps using path expressions in their bindings. The Enrichment Pipeline infers the dependency graph from these references.

Zakardo supports four execution modes:

ModeBehavior
SIMULATEDNo capabilities actually execute — inputs/outputs are simulated
DRY_RUNREAD capabilities execute, writes are logged but not committed
LIVEFull execution with real side effects
TRAININGLike LIVE but with detailed traces for validation
  1. Plans are the unit of execution, not individual tool calls
  2. LLM produces minimal drafts — all type inference is deterministic
  3. Sequential execution in v1 — parallelism is computed but not yet used
  4. Deferred outbox commit — external effects only fire on full success
  5. Zakardo does not own business data — developers bring their own DB
  6. Two-layer backend — not everything goes through intents