Architecture

Overview

Conduct v0.2.0 uses a client-server architecture with three main components:

Backend - Self-hosted API service
CLI - Lightweight client tool
Database - Persistent storage layer

System Architecture

┌─────────────────────┐
│     AI Agent        │
│  (Claude, GPT, etc) │
└──────────┬──────────┘
           │ Local file operations
           │ CLI commands
           ▼
┌─────────────────────┐
│   Conduct CLI       │
│  ┌───────────────┐  │
│  │ HTTP Client   │  │
│  │ Local Cache   │  │
│  │ File Utils    │  │
│  └───────────────┘  │
└──────────┬──────────┘
           │ REST API (HTTPS)
           │ JSON payloads
           ▼
┌─────────────────────────┐
│   Conduct Backend       │
│  ┌───────────────────┐  │
│  │ Express Router    │  │
│  │ Authentication    │  │
│  │ Rate Limiting     │  │
│  │ Request Validator │  │
│  └─────────┬─────────┘  │
│            │             │
│  ┌─────────▼─────────┐  │
│  │   Drizzle ORM     │  │
│  │  (DB Abstraction) │  │
│  └─────────┬─────────┘  │
│            │             │
│  ┌─────────▼─────────┐  │
│  │  File Storage     │  │
│  │ (Local/S3/GCS)    │  │
│  └───────────────────┘  │
└──────────┬──────────────┘
           │
           ▼
┌─────────────────────┐
│     Database        │
│  ┌───────────────┐  │
│  │ PostgreSQL    │  │
│  │     or        │  │
│  │    MySQL      │  │
│  │     or        │  │
│  │   SQLite      │  │
│  └───────────────┘  │
└─────────────────────┘

Component Details

CLI (Client)

Purpose: Provide interface for AI agents and developers

Key Responsibilities:

Parse commands and arguments
Authenticate with backend
Cache responses locally
Handle file operations
Format output

Technology Stack:

Node.js
Commander.js for CLI framework
Axios for HTTP requests
File-based caching

Backend (Server)

Purpose: Centralized API and data management

Key Responsibilities:

Expose REST API endpoints
Authenticate and authorize requests
Manage database operations
Store and serve files
Rate limit requests

Technology Stack:

Node.js + Express
Drizzle ORM
JWT for auth tokens
File system or cloud storage

API Design:

RESTful endpoints
JSON request/response
Cursor-based pagination
Versioned API (/v1/)

Database

Purpose: Persistent data storage

Supported Databases:

PostgreSQL (recommended for production)
MySQL (compatible alternative)
SQLite (development only)

Schema:

specs - Specifications
runs - Implementation logs
checks - Verification results
features - Discovered features
api_keys - Authentication keys

Data Flow

Creating a Spec

1. Agent writes spec.md locally
2. Agent runs: conduct spec create spec.md
3. CLI reads spec.md content
4. CLI sends POST /v1/specs with content
5. Backend validates request
6. Backend stores spec in database
7. Backend stores file in storage
8. Backend returns spec ID
9. CLI displays success message
10. CLI caches the new spec

Reading Memory

1. Agent runs: conduct list
2. CLI checks local cache
3. If cache valid, return cached data
4. If cache stale, request from backend
5. Backend queries database
6. Backend returns paginated results
7. CLI caches results
8. CLI displays formatted output

Authentication Flow

1. User runs: conduct profile add
2. CLI prompts for backend URL and API key
3. CLI stores credentials in ~/.conduct/credentials.json
4. For each request:
   a. CLI reads API key from credentials
   b. CLI adds Authorization header
   c. Backend validates API key
   d. Backend checks permissions
   e. Backend processes request or returns 401/403

Storage Architecture

File Storage

Specs, runs, and checks are stored as files:

storage/
├── specs/
│   ├── SPEC-001.md
│   ├── SPEC-002.md
│   └── ...
├── runs/
│   ├── RUN-001.md
│   ├── RUN-002.md
│   └── ...
└── checks/
    ├── CHECK-001.md
    ├── CHECK-002.md
    └── ...

Database Storage

Metadata and relationships stored in database:

-- specs table
id, spec_id, title, status, created_at, updated_at
 
-- runs table
id, run_id, spec_id, status, created_at, updated_at
 
-- checks table
id, check_id, run_id, result, created_at, updated_at
 
-- features table
id, feature_id, name, description, created_at, updated_at

Scaling Considerations

Horizontal Scaling

Backend can be scaled horizontally:

┌─────┐  ┌─────┐  ┌─────┐
│ CLI │  │ CLI │  │ CLI │
└──┬──┘  └──┬──┘  └──┬──┘
   │        │        │
   └────────┼────────┘
            │
      ┌─────▼─────┐
      │   Load    │
      │  Balancer │
      └─────┬─────┘
            │
   ┌────────┼────────┐
   │        │        │
┌──▼──┐  ┌──▼──┐  ┌──▼──┐
│ BE1 │  │ BE2 │  │ BE3 │
└──┬──┘  └──┬──┘  └──┬──┘
   │        │        │
   └────────┼────────┘
            │
        ┌───▼───┐
        │  DB   │
        └───────┘

Caching Strategy

Multi-level caching:

CLI Cache: Local file cache (TTL: 5 min)
Backend Cache: Redis/Memcached (TTL: 1 min)
Database: Query result cache

Database Optimization

Indexed columns: spec_id, run_id, status, created_at
Soft deletes: deleted_at column
Pagination: Cursor-based for efficiency
Connection pooling: Reuse database connections

Security Architecture

API Key Management

API Key Format: sk_{env}_{random}

Examples:
- sk_admin_abc123...
- sk_prod_def456...
- sk_dev_ghi789...

Permission Model

Permissions:
- read: View specs, runs, checks
- write: Create and update
- delete: Remove entities
- admin: Manage API keys, full access

Request Validation

All requests validated:

Authentication (API key)
Authorization (permissions)
Rate limiting (100 req/min)
Input validation (schema check)
Sanitization (XSS prevention)

Deployment Models

Single Server

Simple deployment for small teams:

One server running:
- Backend (Node.js)
- Database (PostgreSQL)
- File storage (local disk)

Cloud Deployment

Production-ready setup:

- Backend: Multiple instances (K8s/ECS)
- Database: Managed service (RDS/Cloud SQL)
- Storage: Object storage (S3/GCS)
- Cache: Redis cluster
- Load balancer: ALB/Cloud Load Balancer

Edge Deployment

Distributed for global teams:

- Backend: Regional deployments
- Database: Multi-region replication
- Storage: CDN + regional buckets
- Cache: Regional Redis