CODITECT Software Design Document (SDD)

Version: 3.0
Status: Current Implementation

Executive Summary

CODITECT is a specification-driven development platform that orchestrates AI agents to automate software development. The system consists of a minimal API (v2), a robust monitoring system (CODI2), and foundational infrastructure deployed on Google Cloud Platform.

System Architecture

High-Level Architecture

Component Architecture

1. API v2 (Minimal Core)

Purpose: Provides basic authentication and WebSocket support as foundation for future development.

Technology Stack:

Rust with Actix-web framework
JWT authentication (HS256)
Argon2 password hashing
FoundationDB for persistence

Current Endpoints:

GET  /api/v2/health       - Health check
GET  /api/v2/ready        - Readiness check
POST /api/auth/register   - User registration
POST /api/auth/login      - User login
POST /api/auth/logout     - User logout (planned)
GET  /api/profile/me      - Get profile (planned)
PUT  /api/profile/me      - Update profile (planned)
GET  /ws                  - WebSocket endpoint

Module Structure:

src/api-v2/
├── db/                   # FoundationDB integration
│   ├── models.rs        # User data model
│   └── repositories.rs  # CRUD operations
├── handlers/            # Request handlers
│   ├── auth.rs         # Authentication
│   ├── health.rs       # Health checks
│   └── profile.rs      # User profile
├── middleware/          # Request processing
│   ├── auth.rs         # JWT validation
│   └── json_*.rs       # JSON handling
├── state.rs            # Application state
└── websocket/          # WebSocket handler

2. CODI2 (CODItect Intelligence v2) - Primary User Interaction System

Purpose: CODI2 is the central nervous system of CODITECT, providing race-free monitoring, coordination, and the primary interface for developers and AI agents to interact with the platform. It replaces traditional logging with a comprehensive event-driven architecture.

Why CODI2 is Essential:

Unified Interface: Single point of interaction for all platform operations
Real-time Tracking: Every file change, command, and action is captured
Multi-Agent Coordination: Prevents conflicts between concurrent AI sessions
Audit Trail: Complete history of all development activities
Session Management: Tracks and manages developer and AI agent sessions

Architecture:

CODI2 Replaces All Bash Scripts:

CODI2 provides a unified CLI that completely replaces traditional bash scripts, solving race conditions and providing guaranteed consistency. Here's the complete command structure:

1. Logging Commands (Replace echo, tee, and all log scripts):

# Basic logging - replaces: echo "message" >> log.file
codi2 log "Build started" --action BUILD

# AI-attributed logging - replaces: codi-log-ai.sh
codi2 log-ai "Task completed" --action SUCCESS --session "RUST-DEV-001"

# System logging - replaces: codi-log-system.sh
codi2 log-system "Service started" --action START --system-id api

# View logs - replaces: tail -f, grep, awk
codi2 tail -n 50 --format json
codi2 log-analysis patterns --since "1h ago"

2. Session Management (Replace session scripts):

# Session lifecycle - replaces: set-session-identity.sh, session-start-hook.sh
codi2 session start --identity "DEVELOPER-001"
codi2 session info
codi2 session stop
codi2 whoami  # Show current session and AI tool

3. File Monitoring (Replace inotify-tools, fswatch):

# Advanced monitoring - no bash equivalent
codi2 monitor /workspace --recursive --track-moves --report-duplicates
codi2 monitor --include "*.rs" --exclude "target/*" --include-hidden
codi2 monitor --daemon --output changes.log

4. Agent Coordination (New capabilities):

# Heartbeat management - replaces manual tracking
codi2 heartbeat send --agent-id "RUST-DEV"
codi2 heartbeat start --interval 3600

# Agent registry - no bash equivalent
codi2 agent register --type orchestrator
codi2 agent status
codi2 agent sync

5. Issue Tracking (Built-in):

# Issue management - replaces external tools
codi2 issue create --title "Auth bug" --priority high
codi2 issue list --status open --assignee "RUST-DEV"
codi2 issue update 123 --status resolved

6. Build & Deployment (Replace CI/CD scripts):

# Build automation
codi2 build start --project api
codi2 build status
codi2 build deploy --environment production

7. Metrics & Analysis:

# Performance metrics
codi2 metrics collect --component api
codi2 metrics export --format prometheus

# Log analysis - replaces grep, awk, sed pipelines
codi2 log-analysis patterns --action ERROR
codi2 log-analysis anomalies --threshold 3-sigma

8. System Management:

# Service control - replaces systemd scripts
codi2 start --daemon        # Start all services
codi2 status --format json  # Check status
codi2 stop                  # Stop services

# Export and backup
codi2 export --output backup.json --since "2024-01-01"

9. Server Components:

# Production servers
codi2 websocket --bind 0.0.0.0:8765    # Real-time updates
codi2 mcp --bind 0.0.0.0:3000          # AI tool protocol
codi2 web --port 8080 --open           # Dashboard

Migration Table:

Old Method	CODI2 Replacement	Benefits
`echo >> log`	`codi2 log`	No race conditions
`codi-log-ai.sh`	`codi2 log-ai`	Automatic AI detection
`tail -f log`	`codi2 tail`	Structured queries
`grep ERROR`	`codi2 log-analysis`	Pattern detection
`inotifywait`	`codi2 monitor`	Cross-platform
Manual tracking	`codi2 agent/session`	Automated coordination

Programmatic API (Rust):

use codi2::{Codi2System, AuditLogger, FileMonitor};

// Initialize - replaces multiple script calls
let codi2 = Codi2System::new("config/fdb.cluster").await?;

// All operations through unified API
codi2.log_event("session-123", "Build started", "BUILD").await?;
codi2.monitor_path("/workspace", MonitorConfig::default()).await?;
codi2.create_session("DEV-001", "Feature development").await?;

Key Modules in Detail:

1. Audit Logger (100% Complete):

Purpose: Replaces traditional file-based logging with FDB-backed structured events
Features:
- Guaranteed write consistency (no race conditions)
- Sub-millisecond write performance
- Structured JSON events with full context
- Time-range queries for analysis
- Actor attribution (human/AI/system)
Usage: Every action in the platform goes through audit logger

2. File Monitor (100% Complete):

Purpose: Tracks all file system changes in real-time
Features:
- Native OS integration (FSEvents on macOS, inotify on Linux)
- Pattern-based filtering (.gitignore style)
- Duplicate file detection (content hashing)
- Move/rename tracking
- Bulk operation handling
Usage: Automatically started, captures all workspace changes

3. Session Manager (60% Complete):

Purpose: Manages developer and AI agent sessions
Features:
- Session lifecycle (start/pause/resume/stop)
- Identity management
- Session state persistence
- Multi-session coordination
- Conflict prevention
Usage: Required for all interactive work

4. Agent Coordination:

Purpose: Manages multiple AI agents working concurrently
Features:
- Agent registration and discovery
- Heartbeat monitoring (4-hour timeout)
- Task assignment tracking
- Resource locking (prevents file conflicts)
- Coordination protocols
Data Model:

pub struct AgentInstance {
    pub id: String,              // e.g., "RUST-DEVELOPER-SESSION18"
    pub agent_type: AgentType,   // Orchestrator, Developer, QA, etc.
    pub session_id: String,      
    pub status: AgentStatus,     // Active, Idle, Busy
    pub claimed_files: Vec<String>,
    pub current_task: Option<Task>,
    pub last_heartbeat: DateTime<Utc>,
}

5. Issue Tracking:

Purpose: Built-in issue management for development tasks
Features:
- Create/update/close issues
- Link issues to code changes
- Track issue history
- Query by status/assignee/project

6. Real-time Communication:

WebSocket Server: Push notifications for events
MCP Server: AI tool integration protocol
Message Bus: In-memory event routing

CODI2 vs Traditional Approaches:

Use Case	Traditional Method	CODI2 Command	Benefits
Logging
Basic log	`echo "msg" >> log.txt`	`codi2 log "msg"`	No file locks, no race conditions
AI logging	`./codi-log-ai.sh`	`codi2 log-ai`	Auto AI detection, session tracking
System log	`logger -t system`	`codi2 log-system`	Structured, queryable
Monitoring
Watch files	`inotifywait -r .`	`codi2 monitor`	Cross-platform, advanced features
Tail logs	`tail -f *.log`	`codi2 tail`	Multi-source aggregation
Find patterns	`grep -r "ERROR"`	`codi2 log-analysis patterns`	Semantic analysis
Session Management
Set identity	`export SESSION_ID=...`	`codi2 session start`	Persistent, coordinated
Check session	`echo $SESSION_ID`	`codi2 whoami`	Full context info
Process Control
Start services	`./start.sh &`	`codi2 start --daemon`	Managed lifecycle
Check status	`ps aux \| grep`	`codi2 status`	Structured output
Stop services	`kill $(pidof)`	`codi2 stop`	Graceful shutdown
Data Management
Backup logs	`tar -czf logs.tgz`	`codi2 export`	Consistent snapshots
Parse logs	`awk/sed pipelines`	`codi2 log-analysis`	Built-in analytics
Problems Solved
Race conditions	Common	Impossible	FDB ACID guarantees
Data loss	Buffer not flushed	Never	Immediate persistence
Log rotation	Complex setup	Not needed	Unlimited in FDB
Multi-agent conflicts	Manual coordination	Automatic	Built-in locking

Implementation Status:

Core: 100% complete (audit, monitor, CLI)
Session Management: 60% complete
Agent Features: 100% complete
Issue Tracking: 100% complete
WebSocket/MCP: 100% complete
Metrics: 80% complete
Web Dashboard: 0% (planned)

3. Containerization & workspace Architecture

GKE StatefulSet Architecture:

workspace Persistence Model:

StatefulSet Configuration:
  Naming: ws-{user_id}-{workspace_id}
  Storage:
    Type: SSD PersistentDisk
    Size: 10GB per workspace
    Mount: /workspace
    Retention: Until explicitly deleted
  
  Resources:
    CPU: 2-8 cores (burstable)
    Memory: 4-16GB
    Instance: Spot (84% cost savings)
    
  Lifecycle:
    Creation: On-demand
    Suspension: Scale to 0 after idle
    Persistence: Indefinite (volumes retained)
    Recovery: Automatic with state preserved

Container State Management:

4. Data Architecture

FoundationDB Schema:

# Multi-tenant structure
{tenant_id}/users/{user_id}                    → User JSON
{tenant_id}/users/by_email/{email}             → user_id
{tenant_id}/projects/{project_id}              → Project JSON
{tenant_id}/tasks/{task_id}                    → Task JSON
{tenant_id}/agents/{agent_id}/{session_id}     → Agent state
{tenant_id}/audit_log/{timestamp}:{uuid}       → Audit entry
{tenant_id}/sessions/{session_id}/state        → Session data
{tenant_id}/issues/{project_id}/{issue_number} → Issue JSON
{tenant_id}/workspaces/{workspace_id}/state    → workspace metadata

Core Models:

pub struct User {
    pub id: Uuid,
    pub email: String,
    pub password_hash: String,
    pub tenant_id: String,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}

pub struct workspace {
    pub id: Uuid,
    pub user_id: Uuid,
    pub project_id: Uuid,
    pub statefulset_name: String,
    pub pvc_name: String,
    pub state: workspaceState,
    pub last_accessed: DateTime<Utc>,
}

pub struct Project {
    pub id: Uuid,
    pub name: String,
    pub tenant_id: String,
    pub workspace_id: Uuid,
    pub created_by: Uuid,
    pub status: ProjectStatus,
}

pub struct Task {
    pub id: Uuid,
    pub project_id: Uuid,
    pub assigned_to: Option<String>,
    pub task_type: TaskType,
    pub status: TaskStatus,
    pub specification: TaskSpec,
}

pub struct AuditEntry {
    pub id: Uuid,
    pub timestamp: DateTime<Utc>,
    pub actor: String,
    pub action: String,
    pub resource_type: String,
    pub resource_id: String,
}

5. Infrastructure

Google Cloud Platform:

Project: serene-voltage-464305-n2
Region: us-central1
Services:
- Cloud Run (API deployment)
- GKE Autopilot (Container orchestration)
- Cloud Storage (artifacts)
- Cloud Build (CI/CD)
- Persistent Disks (workspace storage)

Deployment Architecture:

Security Architecture

Authentication:

JWT tokens with 24-hour expiry
Argon2id password hashing
Session-based tracking

Authorization (Planned):

Role-Based Access Control (RBAC)
Tenant isolation
Resource-level permissions

Container Security:

Non-root containers
Read-only root filesystem
Network policies for pod isolation
Secret management via GCP Secret Manager

Current Security Features:

CORS enabled (all origins - development)
TLS 1.3 in production
FoundationDB encryption at rest
Pod security policies enforced

Current Status

Working Features:

✅ Basic authentication (register/login)
✅ Health check endpoints
✅ WebSocket connections
✅ FoundationDB integration
✅ CODI2 monitoring (70% complete)
✅ File monitoring with FSEvents
✅ Audit logging to FDB
✅ Multi-agent coordination basics
✅ GKE StatefulSet deployment model
✅ Persistent workspace volumes

Missing Features:

❌ Multi-tenancy implementation
❌ Project/Task management
❌ AI provider integration
❌ Advanced authorization
❌ Frontend application
❌ Browser-based terminals
❌ Code generation
❌ Real-time collaboration

Module Interactions

Build & Deployment

CI/CD Pipeline:

GitHub push triggers Cloud Build
Cloud Build runs tests and builds Docker image
Artifact Registry stores container images
Cloud Run deploys API automatically
GKE updates workspace pods as needed
CODI2 monitors all operations

Build Optimization:

Multi-stage Docker builds
cargo-chef for dependency caching
Upload size: 95MB → 1.3MB (98% reduction)
Build time: 15min → 2-4min (80% reduction)

Testing Strategy

Test Coverage:

Unit tests: 89 tests (100% passing)
Integration tests: 50+ tests
Current coverage: 89%
Target coverage: 95%

Test Categories:

Build & Deploy validation
Audit Logger verification
File Monitor functionality
Message Bus communication
State Store consistency
CLI command testing
FDB integration tests
Performance benchmarks
Security validation
Recovery scenarios
Container lifecycle tests
Persistent volume tests

Roadmap

Phase 1 - Foundation:

Enable auth middleware
Implement multi-tenancy
Add project CRUD operations
Create React frontend
Finalize workspace persistence

Phase 2 - Core Features:

Task management system
File storage integration
WebSocket functionality
terminal support
workspace collaboration

Phase 3 - AI Integration:

AI provider integration
Code generation engine
Intelligent task routing
Automated testing

Phase 4 - Enterprise:

Advanced security features
Compliance certifications
High availability setup
Multi-region deployment

Conclusion

CODITECT provides a minimal but functional foundation with robust monitoring capabilities and persistent workspace infrastructure. The architecture leverages GKE StatefulSets for cost-effective, persistent development environments while maintaining clean separation of concerns and high performance standards. The system is designed for gradual expansion from its current MVP state to a full-featured development platform.

Executive Summary​

System Architecture​

High-Level Architecture​

Component Architecture​

1. API v2 (Minimal Core)​

2. CODI2 (CODItect Intelligence v2) - Primary User Interaction System​

3. Containerization & workspace Architecture​

4. Data Architecture​

5. Infrastructure​

Security Architecture​

Current Status​

Module Interactions​

Build & Deployment​

Testing Strategy​

Roadmap​

Conclusion​