Skip to content

Building a CRM

This guide walks you through building a CRM application using Zakardo. By the end, you will have a working server with capabilities for managing contacts, deals, notes, and email — plus governance policies and a training dataset.

The complete source code is available in the examples/crm/ directory.

FeatureCapabilities
Contactscontacts_list, contacts_create, contacts_delete
Dealsdeals_list, deals_create, deals_update_stage
Notesnotes_add, notes_list
Emailemail_send
Analyticsanalytics_pipeline_summary

Plus:

  • 2 governance policies — destructive operations require approval, external writes are audited
  • Training dataset — 3 test scenarios for regression testing
  • Hono server with Zakardo Runtime and Studio
Terminal window
mkdir zakardo-crm && cd zakardo-crm
pnpm init
pnpm add @zakardo/core hono @hono/node-server better-sqlite3 ajv ajv-formats semver
pnpm add -D typescript @types/node @types/better-sqlite3 @types/semver tsx vitest

Set "type": "module" in package.json and create a TypeScript config with "strict": true.

Create src/capabilities/contacts.ts. Each capability needs a definition and an implementation:

import type { CapabilityDefinition, CapabilityFn } from '@zakardo/core';
const contacts = new Map<string, { id: string; name: string; email: string; company: string; tags: string[] }>();
export const listContactsCapability: CapabilityDefinition = {
name: 'contacts_list',
version: '1.0.0',
description: 'List all contacts, optionally filtered by tag or company.',
effect_class: 'READ',
boundary: 'LOCAL',
input_schema: {
type: 'object',
properties: {
tag: { type: 'string', description: 'Filter by tag' },
company: { type: 'string', description: 'Filter by company name' },
limit: { type: 'number', description: 'Max results to return' },
},
'x-zakardo': { kind: 'capability-input', version: '1.0.0' },
},
output_schema: {
type: 'object',
properties: {
contacts: {
type: 'array',
items: { type: 'object', properties: {
id: { type: 'string' }, name: { type: 'string' },
email: { type: 'string' }, company: { type: 'string' },
}},
description: 'List of contacts',
},
total: { type: 'number', description: 'Total matching contacts' },
},
'x-zakardo': { kind: 'capability-output', version: '1.0.0' },
},
interaction_spec: null,
anchored_view: null,
tags: ['contacts', 'read'],
metadata: { author: 'zakardo-crm', created_at: '2026-01-01T00:00:00Z', deprecated: false },
} as CapabilityDefinition;
export const listContactsImpl: CapabilityFn = async (inputs) => {
let results = [...contacts.values()];
const tag = inputs['tag'] as string | undefined;
if (tag) results = results.filter((c) => c.tags.includes(tag));
return { contacts: results, total: results.length };
};

Follow the same pattern for contacts_create (WRITE_INTERNAL) and contacts_delete (DESTRUCTIVE).

Key decisions:

  • contacts_delete uses DESTRUCTIVE — this automatically triggers an approval gate in production
  • contacts_create uses WRITE_INTERNAL — data stays within the application boundary
  • contacts_list uses READ — no governance overhead for read operations

Deals have a pipeline with stages. The deals_update_stage capability moves deals between stages:

export const updateDealStageCapability: CapabilityDefinition = {
name: 'deals_update_stage',
version: '1.0.0',
description: 'Update the pipeline stage of a deal.',
effect_class: 'WRITE_INTERNAL',
boundary: 'LOCAL',
input_schema: {
type: 'object',
required: ['deal_id', 'new_stage'],
properties: {
deal_id: { type: 'string', description: 'Deal ID' },
new_stage: { type: 'string', description: 'New pipeline stage' },
},
'x-zakardo': { kind: 'capability-input', version: '1.0.0' },
},
// ... output_schema
} as CapabilityDefinition;

Email sending crosses the system boundary — it has an external side effect:

export const sendEmailCapability: CapabilityDefinition = {
name: 'email_send',
version: '1.0.0',
description: 'Send an email to a contact.',
effect_class: 'WRITE_EXTERNAL', // Crosses system boundary
boundary: 'REMOTE', // Calls external service
// ...
} as CapabilityDefinition;

With WRITE_EXTERNAL effect class:

  • The email is staged in the outbox during execution, not sent immediately
  • If any subsequent plan step fails, the email is never sent
  • Only when all steps succeed is the outbox committed and the email actually sent

Create src/policies/index.ts:

import type { PolicyDocument } from '@zakardo/core';
export const CRM_POLICIES: readonly PolicyDocument[] = [
{
policy_id: 'crm_destructive_approval',
name: 'Destructive Operations Require Approval',
description: 'Any destructive operation requires explicit human approval.',
version: '1.0.0',
rules: [
{
rule_id: 'require_admin_for_destructive',
condition: { field: 'effect_class', operator: 'equals', value: 'DESTRUCTIVE' },
action: 'GATE',
message: 'Destructive operations require admin approval.',
},
],
scope: {
environments: ['production', 'staging'],
effect_classes: ['DESTRUCTIVE'],
},
metadata: { author: 'zakardo-crm', created_at: '2026-01-01T00:00:00Z', enabled: true, priority: 100 },
} as PolicyDocument,
{
policy_id: 'crm_external_audit',
name: 'External Writes Audit Trail',
description: 'All external write operations must be fully traced.',
version: '1.0.0',
rules: [
{
rule_id: 'trace_external_writes',
condition: { field: 'effect_class', operator: 'equals', value: 'WRITE_EXTERNAL' },
action: 'ALLOW',
message: 'External writes are allowed but fully traced.',
},
],
scope: {
environments: ['production', 'staging', 'development'],
effect_classes: ['WRITE_EXTERNAL'],
},
metadata: { author: 'zakardo-crm', created_at: '2026-01-01T00:00:00Z', enabled: true, priority: 50 },
} as PolicyDocument,
];

Create src/server.ts:

import { Hono } from 'hono';
import { serve } from '@hono/node-server';
import { createZakardoApp, mountStudio, type ZakardoConfig } from '@zakardo/core';
import { CRM_CAPABILITIES, CRM_IMPLEMENTATIONS } from './capabilities/index.js';
import { CRM_POLICIES } from './policies/index.js';
const config: ZakardoConfig = {
name: 'zakardo-crm',
version: '0.0.1',
llm: {
providers: [{ name: 'mock', type: 'mock' as const, models: ['mock-model'] }],
default_model: 'mock-model',
routing: {},
},
execution: { timeout_ms: 60_000, step_timeout_ms: 10_000 },
trace: { level: 'full' },
auth: { required: false },
};
async function main() {
const { app: zakardoApp, runtime } = await createZakardoApp({
config,
capabilities: CRM_CAPABILITIES,
implementations: CRM_IMPLEMENTATIONS,
policies: CRM_POLICIES,
});
const app = new Hono();
app.route('/zakardo', zakardoApp);
mountStudio(app, { basePath: '/studio' });
serve({ fetch: app.fetch, port: 3000 });
console.log('CRM running at http://localhost:3000');
}
main().catch(console.error);

Training datasets validate that your capabilities and plans work correctly:

import type { TrainingDataset } from '@zakardo/core';
export const CRM_TRAINING_DATASET: TrainingDataset = {
id: 'crm-core-v1',
name: 'CRM Core Test Suite',
version: '1.0.0',
cases: [
{
id: 'list-contacts',
name: 'List all contacts',
intent: { type: 'expressed', text: 'Show me all contacts' },
expectation: {
outcome: 'COMPLETED',
plan: { must_include_capabilities: ['contacts_list'] },
},
},
{
id: 'create-contact',
name: 'Create a new contact',
intent: { type: 'expressed', text: 'Add a contact named Alice at [email protected]' },
expectation: {
outcome: 'COMPLETED',
plan: { must_include_capabilities: ['contacts_create'] },
},
},
],
metadata: { created_at: '2026-01-01T00:00:00Z', author: 'zakardo-crm' },
};
import { ZakardoClient } from '@zakardo/client';
const client = new ZakardoClient({ baseUrl: 'http://localhost:3000/zakardo/v1' });
// List capabilities
const caps = await client.capabilities.list();
console.log(`${caps.length} capabilities registered`);
// Submit an intent
const result = await client.intent.submit({
intent: { expressed: 'Show me all contacts tagged VIP' },
});
console.log('Mode:', result.mode);

Start the server and open http://localhost:3000/studio:

  • Capability Browser — see all 10 capabilities with schemas and effect classes
  • Intent Playground — test intents against your capabilities
  • Policy Inspector — verify governance rules are loaded