Data Layer
Zakardo’s data layer follows a key principle: Zakardo does not own your business data. Your application uses its own database and ORM (Prisma, Drizzle, etc.) for business data. Zakardo stores only its own runtime data (checkpoints, traces, events, outbox entries) in a separate ZakardoStore.
Architecture
Section titled “Architecture”Your Application Data Zakardo Runtime Data━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━Your Database (Postgres, etc.) ZakardoStore (SQLite)├── users ├── executions (checkpoints)├── contacts ├── events (execution events)├── deals ├── traces (trace entries)├── invoices ├── outbox (staged effects)└── ... └── policies (loaded policies)
Accessed via your ORM Accessed via ZakardoStore interface(Prisma, Drizzle, etc.) (SQLiteZakardoStore)ZakardoStore Interface
Section titled “ZakardoStore Interface”The ZakardoStore interface defines 5 sub-stores for Zakardo’s runtime data:
import type { ZakardoStore, ExecutionStore, EventStore, TraceStore, OutboxStore, PolicyStore } from '@zakardo/core';
interface ZakardoStore { execution: ExecutionStore; // Execution checkpoints events: EventStore; // Execution events traces: TraceStore; // Trace entries outbox: OutboxStore; // Staged external effects policies: PolicyStore; // Loaded policy documents}ExecutionStore
Section titled “ExecutionStore”interface ExecutionStore { saveCheckpoint(checkpoint: StoredCheckpoint): void; getCheckpoint(executionId: string): StoredCheckpoint | undefined; listCheckpoints(options?: ListOptions): StoredCheckpoint[];}EventStore
Section titled “EventStore”interface EventStore { appendEvent(event: StoredEvent): void; getEvents(executionId: string): StoredEvent[]; getEventsSince(executionId: string, afterSequence: number): StoredEvent[];}TraceStore
Section titled “TraceStore”interface TraceStore { saveTrace(trace: StoredTrace): void; getTrace(traceId: string): StoredTrace | undefined; appendEntry(traceId: string, entry: StoredTraceEntry): void; getEntries(traceId: string, filter?: TraceEntryFilter): StoredTraceEntry[];}SQLiteZakardoStore
Section titled “SQLiteZakardoStore”The built-in implementation uses SQLite via better-sqlite3:
import { SQLiteZakardoStore } from '@zakardo/core';
// File-based (persistent)const store = new SQLiteZakardoStore({ path: './data/zakardo.db' });
// In-memory (for testing)const testStore = new SQLiteZakardoStore({ path: ':memory:' });SQLite is chosen for simplicity — it requires no external database server and provides ACID transactions. For production deployments with multiple server instances, implement a custom ZakardoStore backed by your preferred database.
DataAdapter Interface
Section titled “DataAdapter Interface”The DataAdapter interface is the contract between Zakardo and your application’s database. It provides schema metadata and mode-aware connection configuration:
import type { DataAdapter, DataAdapterConfig } from '@zakardo/core';
interface DataAdapter { getSchemaMetadata(): Promise<SchemaMetadata>; getModeConfig(mode: ExecutionMode): ModeConfig;}Mode-Aware Connections
Section titled “Mode-Aware Connections”The DataAdapter provides different database connections based on execution mode:
| Mode | Connection Behavior |
|---|---|
SIMULATED | No database access (all reads return mock data) |
DRY_RUN | Read-only connection (writes silently succeed but don’t persist) |
LIVE | Full read-write connection |
TRAINING | Full read-write with detailed logging |
Bringing Your Own Database
Section titled “Bringing Your Own Database”Capabilities access your business data through your ORM — Zakardo does not intercept or proxy these calls:
import type { CapabilityFn } from '@zakardo/core';import { prisma } from '../db/client.js';
const listContacts: CapabilityFn = async (inputs) => { // Direct database access through your ORM const contacts = await prisma.contact.findMany({ where: { tag: inputs['tag'] as string }, }); return { contacts, total: contacts.length };};Further Reading
Section titled “Further Reading”- Architecture Overview — how the data layer fits into the system
- Data Layer Specification — full specification