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.
System Boundary
Section titled “System Boundary”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| DBTwo-Layer Backend
Section titled “Two-Layer Backend”The backend has two distinct layers mounted on the same Hono server:
Foundation Layer (Non-Agentic)
Section titled “Foundation Layer (Non-Agentic)”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
Zakardo Runtime (Agentic)
Section titled “Zakardo Runtime (Agentic)”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 routesapp.get('/api/users', getUsers);app.post('/api/auth/login', login);
// Zakardo Runtime — agent execution routesapp.route('/zakardo', zakardoApp);The Execution Loop
Section titled “The Execution Loop”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]1. Intent Submission
Section titled “1. Intent Submission”The user submits an intent via REST API. The Planner classifies it.
2. Plan Generation
Section titled “2. Plan Generation”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.
3. Enrichment (8 Steps)
Section titled “3. Enrichment (8 Steps)”The deterministic Enrichment Pipeline converts the Planner’s minimal draft into a fully typed Plan IR:
- Capability Resolution — resolve names from registry
- Schema Inference — infer input/output schemas
- Binding Conversion — convert draft bindings to path expressions
- Condition Conversion — structure conditional logic
- Dependency Analysis — compute
depends_onfrom data flow - Index Assignment — assign step indices and output keys
- Metadata Generation — plan ID, version, name
- Default Policies — error handling, retry, constraints
4. Validation (10 Checks)
Section titled “4. Validation (10 Checks)”All 10 checks run regardless of earlier failures:
- 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
5. Execution
Section titled “5. Execution”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
6. Trace Recording
Section titled “6. Trace Recording”Every execution event is written to an immutable, append-only trace.
Data Flow
Section titled “Data Flow”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)
Execution Context
Section titled “Execution Context”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.
Execution Modes
Section titled “Execution Modes”Zakardo supports four execution modes:
| Mode | Behavior |
|---|---|
SIMULATED | No capabilities actually execute — inputs/outputs are simulated |
DRY_RUN | READ capabilities execute, writes are logged but not committed |
LIVE | Full execution with real side effects |
TRAINING | Like LIVE but with detailed traces for validation |
Key Architectural Decisions
Section titled “Key Architectural Decisions”- Plans are the unit of execution, not individual tool calls
- LLM produces minimal drafts — all type inference is deterministic
- Sequential execution in v1 — parallelism is computed but not yet used
- Deferred outbox commit — external effects only fire on full success
- Zakardo does not own business data — developers bring their own DB
- Two-layer backend — not everything goes through intents
Further Reading
Section titled “Further Reading”- System Architecture Specification — full 1,145-line architecture document
- Execution Engine API — engine interface and state transitions
- Data Layer API — DataAdapter contract and ZakardoStore