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.
What You Will Build
Section titled “What You Will Build”| Feature | Capabilities |
|---|---|
| Contacts | contacts_list, contacts_create, contacts_delete |
| Deals | deals_list, deals_create, deals_update_stage |
| Notes | notes_add, notes_list |
email_send | |
| Analytics | analytics_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
Step 1: Project Setup
Section titled “Step 1: Project Setup”mkdir zakardo-crm && cd zakardo-crmpnpm initpnpm add @zakardo/core hono @hono/node-server better-sqlite3 ajv ajv-formats semverpnpm add -D typescript @types/node @types/better-sqlite3 @types/semver tsx vitestSet "type": "module" in package.json and create a TypeScript config with "strict": true.
Step 2: Define Contact Capabilities
Section titled “Step 2: Define Contact Capabilities”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_deleteusesDESTRUCTIVE— this automatically triggers an approval gate in productioncontacts_createusesWRITE_INTERNAL— data stays within the application boundarycontacts_listusesREAD— no governance overhead for read operations
Step 3: Define Deal Capabilities
Section titled “Step 3: Define Deal Capabilities”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;Step 4: Define the Email Capability
Section titled “Step 4: Define the Email Capability”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
Step 5: Add Governance Policies
Section titled “Step 5: Add Governance Policies”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,];Step 6: Wire Up the Server
Section titled “Step 6: Wire Up the Server”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);Step 7: Create a Training Dataset
Section titled “Step 7: Create a Training Dataset”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', expectation: { outcome: 'COMPLETED', plan: { must_include_capabilities: ['contacts_create'] }, }, }, ], metadata: { created_at: '2026-01-01T00:00:00Z', author: 'zakardo-crm' },};Step 8: Test with the Client SDK
Section titled “Step 8: Test with the Client SDK”import { ZakardoClient } from '@zakardo/client';
const client = new ZakardoClient({ baseUrl: 'http://localhost:3000/zakardo/v1' });
// List capabilitiesconst caps = await client.capabilities.list();console.log(`${caps.length} capabilities registered`);
// Submit an intentconst result = await client.intent.submit({ intent: { expressed: 'Show me all contacts tagged VIP' },});console.log('Mode:', result.mode);Step 9: Explore with Studio
Section titled “Step 9: Explore with Studio”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
Next Steps
Section titled “Next Steps”- Add more capabilities with interaction specs and anchored views
- Write custom policies for fine-grained access control
- Set up training for automated regression testing
- Deploy to production with the full REST + SSE API