Skip to content

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.

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)

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
}
interface ExecutionStore {
saveCheckpoint(checkpoint: StoredCheckpoint): void;
getCheckpoint(executionId: string): StoredCheckpoint | undefined;
listCheckpoints(options?: ListOptions): StoredCheckpoint[];
}
interface EventStore {
appendEvent(event: StoredEvent): void;
getEvents(executionId: string): StoredEvent[];
getEventsSince(executionId: string, afterSequence: number): StoredEvent[];
}
interface TraceStore {
saveTrace(trace: StoredTrace): void;
getTrace(traceId: string): StoredTrace | undefined;
appendEntry(traceId: string, entry: StoredTraceEntry): void;
getEntries(traceId: string, filter?: TraceEntryFilter): StoredTraceEntry[];
}

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.

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;
}

The DataAdapter provides different database connections based on execution mode:

ModeConnection Behavior
SIMULATEDNo database access (all reads return mock data)
DRY_RUNRead-only connection (writes silently succeed but don’t persist)
LIVEFull read-write connection
TRAININGFull read-write with detailed logging

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 };
};