Backend Setup

What is Conduct Backend?

Conduct v0.2 backend is an SDK/library (like better-auth or Auth.js) that you install via npm and integrate into your application. It provides:

• ✅ API routes for specs, plans, and runs (stored in your database as mdJson)
• ✅ Works with any HTTP framework (Express, Hono, Next.js, Fastify)
• ✅ Works with any database via adapters (PostgreSQL, MySQL, SQLite)
• ✅ No separate backend to deploy - it's part of YOUR app

Important: Conduct is NOT a standalone service. It's a package you integrate.

---

Quick Start (5 minutes)

Step 1: Install Packages

# Core packages
npm install conduct-backend @superfunctions/db @superfunctions/http
 
# Your framework (choose one)
npm install @superfunctions/http-express
 
# Your database + ORM (choose one)
npm install drizzle-orm postgres

Step 2: Setup Database Connection

// db.ts
import { drizzle } from 'drizzle-orm/postgres-js';
import postgres from 'postgres';
 
const client = postgres(process.env.DATABASE_URL!);
export const db = drizzle(client);

Step 3: Initialize Conduct

// conduct.ts
import { createConductBackend } from 'conduct-backend';
import { drizzleAdapter } from '@superfunctions/db/adapters';
import { db } from './db';
 
const adapter = drizzleAdapter({ db, dialect: 'postgres' });
 
export const conduct = createConductBackend({
  database: adapter, // Stores mdJson in YOUR database
  auth: {
    apiKeys: async (key) => {
      // Your API key validation
      return { apiKeyId: 'user', projectIds: ['proj_123'] };
    },
  },
});

Step 4: Mount in Your App

// server.ts (Express example)
import express from 'express';
import { toExpressRouter } from '@superfunctions/http-express';
import { conduct } from './conduct';
 
const app = express();
app.use(express.json());
 
// Mount Conduct routes
app.use('/api/conduct', toExpressRouter(conduct.router));
 
app.listen(3000);

Step 5: Generate Migrations with @superfunctions/cli

Conduct exports its schema for automatic migration generation:

# Install the CLI tool
npm install -D @superfunctions/cli

Create superfunctions.config.js:

// superfunctions.config.js
import { defineConfig } from '@superfunctions/cli';
 
export default defineConfig({
  adapter: {
    type: 'drizzle',
    drizzle: {
      dialect: 'postgres',
      connectionString: process.env.DATABASE_URL,
    },
  },
  libraries: ['./src/conduct.ts'], // Points to YOUR conduct setup
  migrationsDir: './migrations',
});

Generate and apply migrations:

# Generate migrations (reads your conduct.ts and extracts schema)
npx superfunctions generate
 
# Output:
# 🔍 Parsing library initialization files...
#    ✅ ./src/conduct.ts: Found createConductBackend
# 📖 Processing conduct schema...
#    ✅ Generated schema (v1, 6 tables: projects, specs, plans, tasks, runs)
# 💾 Writing migration files...
#    ✅ ./migrations/20231216_conduct_v1.sql
 
# Apply migrations with your ORM
npx drizzle-kit push

Done! Conduct tables are now in YOUR database, and /api/conduct/* routes are live.

---

How It Works

What Gets Stored in Your Database

Conduct creates these tables in YOUR database:

• projects - Your projects
• specs - Specifications with mdJson (Markdown AST) and requirements
• requirements - Individual requirements with mdJson
• tasks - Execution tasks with mdJson
• tasksRequirements - Links tasks to requirements
• runs - Agent run tracking

Everything is stored as mdJson (Markdown AST in JSON format) in your database. No file storage.

How AI Agents Use It

1. AI agent (Claude, Factory, etc.) uses Conduct CLI
2. CLI sends JSON to YOUR backend's Conduct routes
3. Conduct SDK stores mdJson in YOUR database
4. Your app exposes /api/conduct/* endpoints

AI Agent → Conduct CLI → YOUR App (/api/conduct/*) → YOUR Database

---

Integration Examples

See Integration Guide for complete examples with:

• Express
• Hono
• Next.js (App Router & Pages Router)
• Fastify
• Cloudflare Workers

---

Database Setup

PostgreSQL (Recommended)

import { drizzle } from 'drizzle-orm/postgres-js';
import postgres from 'postgres';
 
const client = postgres(process.env.DATABASE_URL!);
export const db = drizzle(client);
 
const adapter = drizzleAdapter({ db, dialect: 'postgres' });

MySQL

import { drizzle } from 'drizzle-orm/mysql2';
import mysql from 'mysql2/promise';
 
const connection = await mysql.createConnection(process.env.DATABASE_URL!);
export const db = drizzle(connection);
 
const adapter = drizzleAdapter({ db, dialect: 'mysql' });

SQLite

import { drizzle } from 'drizzle-orm/better-sqlite3';
import Database from 'better-sqlite3';
 
const sqlite = new Database('conduct.db');
export const db = drizzle(sqlite);
 
const adapter = drizzleAdapter({ db, dialect: 'sqlite' });

---

Authentication

const conduct = createConductBackend({
  database: adapter,
  auth: {
    apiKeys: async (key) => {
      // Validate API key and return project access
      // Example: check against your database
      const validKey = await validateKey(key);
      if (!validKey) return null;
      
      return {
        apiKeyId: validKey.id,
        projectIds: validKey.projectIds,
      };
    },
  },
});

---

What About Deployment?

Conduct doesn't care about deployment. Your app handles that.

Conduct is just routes mounted in YOUR app:

app.use('/api/conduct', toExpressRouter(conduct.router));

Deploy YOUR app however you want:

• Docker
• Vercel/Netlify
• AWS/GCP/Azure
• VPS
• Kubernetes

Conduct routes deploy with your app automatically.

---

Next Steps

1. Integration Guide - Framework-specific examples
2. CLI Setup - Setup CLI for your team/agents
3. API Reference - API endpoint documentation

---

FAQ

Q: Do I need to clone a Conduct backend repo?
A: No! Just npm install conduct-backend and integrate.

Q: Where does Conduct store data?
A: In YOUR database as mdJson. No file storage.

Q: Do I deploy Conduct separately?
A: No! It's part of YOUR app. Deploy your app normally.

Q: Can I use my existing database?
A: Yes! Conduct creates its own tables alongside yours.

Q: What if I already have an Express/Next.js app?
A: Perfect! Just add Conduct routes to your existing app.