Skip to main content

CODITECT v4

AI-powered platform that transforms Architecture Decision Records into working software.

📌 New ORCHESTRATOR? Start here: CLAUDE.md § ORCHESTRATOR First Steps

📂 Directory Organization: See DIRECTORY-ORGANIZATION-GUIDE.md for file placement rules

What is CODITECT?​

CODITECT enables autonomous software development through AI agents. You write ADRs (Architecture Decision Records) describing what you want, and AI agents build it automatically with production-ready code, tests, and deployment.

🚀 Current Production URLs​

Core Components​

CODITECT Architecture

Primary Components​

  1. Frontend - React UI for project management and AI interaction
  2. API Server - Rust backend handling authentication and data
  3. FoundationDB - Distributed database for multi-tenant storage
  4. AI Agents - 21 specialized agents for autonomous development
  5. CODI2 - Primary user interaction system and monitoring platform
  6. WebSocket Gateway - Live terminal and agent communication

New Infrastructure Components (v4.1)​

  1. CODITECT Server Hub - Centralized server infrastructure providing:

    • Unified logging and monitoring across all services
    • Real-time log streaming with WebSocket connections
    • Dual storage (local + cloud) for resilience
    • Admin dashboard for system-wide visibility
    • RBAC-based access control for logs
    • See ADR-029

  2. Document Server & KBaaS - Knowledge Base as a Service providing:

    • Centralized compliance and standards documentation
    • AI agent access to regulatory knowledge
    • Industry-specific compliance packs (ISO, GDPR, etc.)
    • Real-time document updates and version control
    • Global CDN distribution for sub-second access
    • See ADR-030

Enhanced Architecture (v4.1)​

System Architecture with New Components​

Data Flow Architecture​

CODI2 - The Heart of CODITECT​

CODI2 (CODItect Intelligence v2) is the central nervous system that connects developers and AI agents to the platform. It replaces all traditional bash scripts with a unified command-line interface, providing guaranteed consistency and race-free operations.

Why CODI2? Traditional bash scripts and file-based logging fail in multi-agent environments due to:

  • Race conditions when multiple agents write to the same log
  • Data loss from file system crashes
  • No coordination between concurrent sessions
  • Difficult to query and analyze logs

CODI2 solves all these issues with FoundationDB-backed storage and a comprehensive CLI.

CODI2 Command Categories​

1. Logging & Audit Trail (Replaces echo, tee, and log scripts)

# Basic logging
codi2 log "Build started" --action BUILD

# AI-attributed logging (replaces codi-log-ai.sh)
codi2 log-ai "Completed task" --action SUCCESS

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

# View recent logs (replaces tail -f)
codi2 tail -n 50

2. Session Management (Replaces set-session-identity.sh)

# Start a new session
codi2 session start --identity "DEVELOPER-001"

# Show current session info
codi2 whoami

# Stop session
codi2 session stop

# View session info
codi2 session info

3. File Monitoring (Replaces inotify-tools, fswatch)

# Monitor directory with all features
codi2 monitor /workspace --recursive --track-moves --report-duplicates

# Monitor with filters
codi2 monitor --exclude "*.tmp" --include "*.rs" --include-hidden

# Background monitoring
codi2 monitor --daemon --output monitor.log

4. Agent Coordination (New capabilities)

# Agent heartbeat (replaces manual tracking)
codi2 heartbeat send --agent-id "RUST-DEV"
codi2 heartbeat start --interval 3600

# Agent management
codi2 agent register --type orchestrator
codi2 agent status
codi2 agent sync

5. Issue Tracking (Built-in, no external tools)

# Create and manage issues
codi2 issue create --title "Fix auth bug" --priority high
codi2 issue list --status open
codi2 issue update 123 --status resolved

6. Build & Deployment (Replaces build scripts)

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

7. Metrics & Analysis (Replaces log parsing scripts)

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

# Log analysis
codi2 log-analysis patterns --since "1h ago"
codi2 log-analysis anomalies

8. Export & Configuration

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

# Configuration management
codi2 config get
codi2 config set log.retention 90

9. Server Components (Production features)

# WebSocket server for real-time updates
codi2 websocket --bind 0.0.0.0:8765

# MCP server for AI tool integration
codi2 mcp --bind 0.0.0.0:3000 --tools codi2,monitor,query

# Web dashboard
codi2 web --port 8080 --open

10. System Management

# Start all services
codi2 start --daemon

# Check system status
codi2 status --format json

# Stop all services
codi2 stop

Migration from Bash Scripts​

Old Bash ScriptCODI2 Command
.codi/scripts/codi-log.shcodi2 log
.codi/scripts/codi-log-ai.shcodi2 log-ai
.codi/scripts/set-session-identity.shcodi2 session start
.codi/scripts/session-start-hook.shcodi2 start
tail -f logs/codi-ps.logcodi2 tail
grep "ERROR" logs/*.logcodi2 log-analysis patterns
Manual file watchingcodi2 monitor
echo "status" >> status.logcodi2 log "status"

🔴 CRITICAL STATUS UPDATE (2025-09-30)​

PRODUCTION SYSTEM NON-FUNCTIONAL

User authentication broken due to FoundationDB connectivity failure. All /api/v2/auth/* endpoints return 502 errors.

Root Cause: External FDB cluster at 10.0.1.3/4/5 unreachable from GKE. Internal Load Balancer at 10.128.0.8 never deployed.

Decision: Deploy FoundationDB StatefulSet directly in GKE cluster (2-3 hours to resolution)

Analysis:

Deployment Plans:

Timeline: Estimated completion 2025-09-30 16:00 UTC

Current Component Status​

✅ Working:

  • Frontend deployed and accessible (all 20 documentation pages)
  • GKE infrastructure (pods, ingress, SSL certificates)
  • API health checks responding
  • DNS configuration correct

🔴 BROKEN (Blocks MVP Launch):

  • User Registration: 502 errors (FDB unreachable)
  • User Login: 502 errors (FDB unreachable)
  • All Authentication: Non-functional

❌ Cannot Test (Blocked by Auth):

  • WebSocket connections (requires authenticated session)
  • Pod orchestration (requires user registration)
  • File API operations (requires authentication)
  • terminal functionality (requires pod + auth)

🚧 In Progress:

  • FoundationDB GKE Deployment - Phase 1 complete (StatefulSet deployed with 3 nodes)
    • Cluster Sizing: 3 nodes with double redundancy (tolerates 1 failure)
    • Storage: 150GB total (3 × 50GB PersistentVolumes)
    • Scaling: Can add nodes dynamically with zero downtime
    • Next: HAProxy deployment + API connectivity testing
  • CODITECT Server Hub deployment
  • Document Server implementation

⚠️ Known Issues (Non-Blocking):

☸️ Kubernetes (GKE) Deployment​

Production Infrastructure​

  • Cluster: codi-poc-e2-cluster (us-central1-a)
  • Namespace: coditect-app
  • Load Balancer: 34.46.212.40
  • Domain: coditect.ai (34.8.51.57)

Quick Deployment Commands​

# Deploy updated frontend
cd /home/halcasteel/v4/src/frontend
gcloud builds submit --config=cloudbuild.yaml --project=serene-voltage-464305-n2
kubectl set image deployment/coditect-frontend frontend=gcr.io/serene-voltage-464305-n2/coditect-frontend:latest -n coditect-app

# Deploy updated API
cd /home/halcasteel/v4/src/api-v2
gcloud builds submit --config=cloudbuild.yaml --project=serene-voltage-464305-n2
kubectl set image deployment/coditect-api-v2 api=gcr.io/serene-voltage-464305-n2/coditect-api-v2:latest -n coditect-app

# Check deployment status
kubectl get pods -n coditect-app
kubectl get svc -n coditect-app
kubectl get ingress -n coditect-app

Common Operations​

OperationCommand
View deploymentskubectl get deploy -n coditect-app
View podskubectl get pods -n coditect-app
Pod logskubectl logs <pod-name> -n coditect-app
Rollbackkubectl rollout undo deployment/<name> -n coditect-app
Scalekubectl scale deployment/<name> --replicas=N -n coditect-app
Eventskubectl get events -n coditect-app --sort-by='.lastTimestamp'

Network & SSL Troubleshooting​

OperationCommand
Test HTTPScurl -I https://coditect.ai
Check SSL certopenssl s_client -connect coditect.ai:443 -servername coditect.ai </dev/null 2>/dev/null | openssl x509 -noout -dates
DNS lookupdig coditect.ai +short
Test with timingcurl -s -o /dev/null -w "Status: %{http_code}, Time: %{time_total}s\n" https://coditect.ai
Check ingresskubectl get ingress -n coditect-app
Check certificateskubectl describe managedcertificate coditect-ai-ssl -n coditect-app

Complete Guides:

Quick Start​

# 1. Set up Google Cloud Project
gcloud config set project serene-voltage-464305-n2

# 2. Start monitoring and development environment
cd /home/halcasteel/v4
source .codi/scripts/infrastructure/session-start-hook.sh

# 3. Initialize session identity (for agents)
export SESSION_ID="DEVELOPER-SESSION-$(date +%Y-%m-%d)-01"
source /home/halcasteel/v4/.codi/scripts/session-management/identity/set-session-identity.sh "$SESSION_ID"

# 4. View agent activity
tail -f .codi/logs/codi-ps.log | jq '.'

# 5. Access web tools
echo "Dashboard: http://localhost:8080"
echo "Logs: http://localhost:8080/log-viewer.html"

Project Structure​

v4/
├── src/                      # Application source code
│   ├── api-v2/              # Rust API server v2 (Actix-web, FoundationDB)
│   │   ├── src/             # Rust source code
│   │   │   ├── auth/        # JWT authentication & authorization
│   │   │   ├── handlers/    # HTTP request handlers
│   │   │   ├── models/      # Data models & schemas
│   │   │   ├── services/    # Business logic services
│   │   │   └── websocket/   # WebSocket connections
│   │   └── Dockerfile       # Container image definition
│   ├── frontend/            # React 18 + TypeScript UI
│   │   ├── src/             # React components & pages
│   │   │   ├── components/  # Reusable UI components
│   │   │   ├── pages/       # Route pages (20+ docs pages)
│   │   │   ├── stores/      # Zustand state management
│   │   │   └── utils/       # Helper utilities
│   │   ├── public/          # Static assets
│   │   └── package.json     # Dependencies & scripts
│   ├── websocket-gateway/   # Real-time communication gateway
│   ├── terminal-core/       # terminal emulation (xterm.js)
│   └── graph-rag/           # Graph RAG for AI context
├── agents/                  # AI agent system (21 agents)
│   ├── coditect/            # 10 primary CODITECT agents
│   │   ├── orchestrator.md  # Multi-agent coordination
│   │   ├── rust-developer.md
│   │   ├── frontend-developer.md
│   │   └── claude-subagents/ # 11 specialist sub-agents
│   ├── quick-start-guides/  # Agent onboarding guides
│   └── tools/               # Agent coordination scripts
├── codi2/                   # CODI2 Rust implementation
│   ├── src/                 # Unified CLI replacing bash scripts
│   ├── config/              # Configuration & templates
│   ├── scripts/             # Build & deployment automation
│   ├── web/                 # Web dashboard (log viewer, metrics)
│   └── binaries/            # Compiled CODI2 binaries
├── docs/                    # Documentation (214 files)
│   ├── architecture/        # System design & ADRs
│   │   ├── adrs/            # 31 Architecture Decision Records
│   │   ├── CODITECT-SDD-CURRENT.md  # Software Design Document
│   │   └── CODITECT-TDD-CURRENT.md  # Technical Design Document
│   ├── guides/              # Setup & configuration guides
│   ├── implementation/      # Implementation details
│   ├── kbaas/               # Knowledge Base as a Service docs
│   ├── operations/          # Production operations
│   ├── reference/           # API & data model references
│   ├── testing/             # Test plans & results
│   └── workflows/           # Development workflows
├── k8s/                     # Kubernetes manifests
│   ├── production/          # Production configs (ingress, HPA, SSL)
│   ├── infrastructure/      # Infrastructure components
│   └── status-page/         # Status page deployment
├── scripts/                 # Operational scripts
│   ├── deployment/          # Deployment automation
│   ├── infrastructure/      # Infrastructure setup
│   ├── kbaas/               # KBaaS utilities
│   ├── mvp/                 # MVP deployment scripts
│   └── testing/             # Test automation
├── projects/                # Time-stamped project directories
│   └── YYYYMMDD-HHMMSS-TaskName-UUID/  # ISO-dated projects
├── .codi/                   # CODI monitoring & coordination
│   ├── scripts/             # Essential operations & hooks
│   │   ├── infrastructure/  # Session start, monitoring
│   │   ├── logging/         # Log management scripts
│   │   └── file-monitoring/ # File watchers & export handlers
│   ├── logs/                # Activity tracking (codi-ps.log)
│   ├── session/             # Session management
│   │   └── conversations/   # Exported conversation logs (100+)
│   └── tools/               # Web dashboard & utilities
├── standards/               # Development standards
│   └── foundation/          # Foundation standards (logging, testing, errors)
├── tests/                   # Test suites
│   ├── integration/         # Integration tests
│   └── unit/                # Unit tests
├── config/                  # Configuration files
│   └── infrastructure.yaml  # Infrastructure configuration
└── infrastructure/          # Deployment configurations
    ├── deployment/          # Deployment manifests
    └── kubernetes/          # Kubernetes configs

Key Directories:

  • src/api-v2/ - Production API server with FoundationDB
  • src/frontend/ - React UI with 27 documentation pages
  • agents/ - 21 AI agents for autonomous development
  • codi2/ - Unified CLI replacing 50+ bash scripts
  • docs/architecture/adrs/ - 31 Architecture Decision Records
  • .codi/session/conversations/ - 100+ conversation exports (GitHub backed up)
  • k8s/production/ - Production Kubernetes manifests

Application Modules​

API Server (src/api/)​

  • Authentication: JWT-based multi-tenant auth system
  • Models: User, Project, Agent, terminal, Memory schemas
  • Services: Container orchestration, AI routing, storage
  • Gateway: WebSocket terminal bridge, real-time events

Frontend (src/frontend/)​

  • UI Framework: React 18 with Chakra UI components
  • State: Zustand for global state management
  • editor: Monaco editor for code editing
  • terminal: xterm.js for terminal emulation

Infrastructure (infrastructure/)​

  • Kubernetes: GKE StatefulSets for containers
  • Docker: Container definitions and builds
  • Terraform: Infrastructure as Code

AI Agent Development​

CODITECT uses 21 specialized AI agents for autonomous development:

Agent Types​

  • 10 CODITECT Agents: Strategic decision-makers (orchestrator, rust-developer, etc.)
  • 11 Claude Sub-Agents: Tactical specialists for deep analysis

Recent Agent Activities​

  • terminal Fix: Root cause identified as vite.config.ts excluding WASM files
  • Server Hub Design: ADR-029 completed for centralized logging infrastructure
  • KBaaS Architecture: ADR-030 completed for compliance document management
  • FDB Connectivity: Resolved using Internal Load Balancer (10.128.0.8)

Multi-Session Development​

# Start multiple agent sessions in parallel
export SESSION_ID="ORCHESTRATOR-SESSION-$(date +%Y-%m-%d)-01"
export SESSION_ID="RUST-DEVELOPER-SESSION-$(date +%Y-%m-%d)-API"
export SESSION_ID="FRONTEND-DEVELOPER-SESSION-$(date +%Y-%m-%d)-UI"

Learn More: Multi-Session Guide | Agent List

Architecture Documentation​

System Design Documents​

Essential Documentation​

For ORCHESTRATORS (Read First!)​

New Infrastructure Documentation (v4.1)​

Project Management​

Development Resources​

Architecture & Standards​

CODI2 Integration Analysis​

  • CODI Scripts Comprehensive Analysis - Complete inventory of 259 bash scripts
    • 17 critical scripts identified (6.6% of total)
    • 10 functional categories documented
    • Technical details for each script
  • CODI2 Gap Analysis - Feature parity assessment
    • Current coverage: 35% (12/45 features)
    • 8 gap categories with priorities
    • 3-phase implementation roadmap
    • Critical gaps in service orchestration and log maintenance

Live Deployments​

Scripts and Tools​

Deployment Scripts​

Testing Scripts​

Latest Updates (v4.1)​

September 2025 Release​

New Features​

  1. CODITECT Server Hub (ADR-029)

    • Centralized logging infrastructure
    • Real-time monitoring dashboard
    • Dual storage (local + cloud) for resilience
    • WebSocket log streaming
    • RBAC-based access control

  2. Knowledge Base as a Service (ADR-030)

    • Centralized compliance documentation
    • AI agents can access regulatory knowledge
    • Industry-specific compliance packs
    • Automatic standard updates
    • Global CDN distribution

  3. CODI2 Enhancements

    • Replaced bash scripts with unified CLI
    • FoundationDB-backed logging
    • Race condition elimination
    • Enhanced monitoring capabilities
    • Status: 16MB binary compiled, 35% feature parity
    • Analysis: CODI Scripts Analysis
    • Gap Report: CODI2 Gap Analysis

Critical Fixes​

  • terminal WASM Loading: Root cause identified in vite.config.ts
  • file-explorer Authentication: Fixed Bearer token headers
  • Frontend Crash Protection: Added ErrorBoundary components
  • CODI2 Binary Compilation: Fixed build configuration issues

Roadmap​

Q4 2025​

  • Deploy CODITECT Server Hub to production
  • Launch Document Server with initial compliance packs
  • Complete CODI2 feature parity (currently 35%)
    • Phase 1: Service orchestration, log maintenance (Critical)
    • Phase 2: Actor-specific loggers, export supervisor (High)
    • Phase 3: Web dashboard, advanced monitoring (Medium)
  • Fix WASM terminal input handling
  • Deploy workspace pod v2 with CODI2 integration

Q1 2026​

  • Expand KBaaS with 50+ industry packs
  • Implement predictive log analytics
  • Launch enterprise compliance automation
  • Scale to 1M+ logs/minute capacity

Long-term Vision​

  • Become the standard platform for AI-driven compliant software development
  • Support all major regulatory frameworks globally
  • Enable fully autonomous development with compliance guardrails
  • Achieve 99.99% uptime with global distribution

Production Deployment & WebSocket Documentation​

WebSocket & GKE Integration​

Production Deployment​

Documentation Moved​

Testing Documentation​

Architecture & Integration​

Workflow Documentation​

Implementation Guides​

CODI2 Build & Binary Management​

Building CODI2 from Source​

# Navigate to CODI2 directory
cd /home/halcasteel/v4/codi2

# Build locally (development)
cargo build

# Build locally (release)
cargo build --release

# Submit to Google Cloud Build
gcloud config set project serene-voltage-464305-n2
gcloud builds submit --config=cloudbuild.yaml

Cloud Build Process​

  1. cloudbuild.yaml: Configures the build steps

    • Installs FoundationDB client libraries
    • Builds CODI2 in release mode
    • Uploads binary to Google Cloud Storage

  2. Build Output: Binary stored at gs://serene-voltage-464305-n2-builds/codi2/codi2-

    • Note: SHORT_SHA substitution not working, binaries named codi2- without hash

  3. Build Monitoring:

    # View build status in console
    # https://console.cloud.google.com/cloud-build/builds?project=1059494892139

    # Or via CLI
    gcloud builds list --limit=5 --project=serene-voltage-464305-n2

Downloading Built Binaries​

Binary Naming Convention: Date-stamped binaries help track when they were built

  • Format: codi2-YYYY-MM-DD-HHMM (e.g., codi2-2025-10-02-1134)
  • Always create a codi2-latest symlink for convenience
# Create binaries directory
mkdir -p /home/halcasteel/v4/codi2/binaries

# List available binaries (sorted by date)
gsutil ls -l gs://serene-voltage-464305-n2-builds/codi2/ | grep -v "/$" | sort -k2 -r | head -10

# Download latest binary with date stamp
gsutil cp gs://serene-voltage-464305-n2-builds/codi2/codi2- /home/halcasteel/v4/codi2/binaries/codi2-$(date +%Y-%m-%d-%H%M)

# Make executable
chmod +x /home/halcasteel/v4/codi2/binaries/codi2-*

# Create symlink to latest (for easy access)
cd /home/halcasteel/v4/codi2/binaries
ln -sf codi2-$(date +%Y-%m-%d-%H%M) codi2-latest

# Verify version
./codi2-latest --version
# Output: codi2 0.2.0

# Test functionality
./codi2-latest test                        # ✅ Successfully connected to FoundationDB
./codi2-latest whoami                      # Shows session info and AI tool detection
./codi2-latest log-ai "Test" --action TEST # Logs to FoundationDB

Common CODI2 Build Issues & Solutions​

Compilation Errors​

  1. Missing imports: Add use crate::errors::Codi2Error;
  2. Moved values: Add .clone() or change to borrowing with &
  3. Feature gates: Add #[cfg(feature = "websocket")] for optional features
  4. Type conversions: Update enum usage to struct pattern (e.g., AuditEvent)

Cloud Build Failures​

  1. Path issues: Use /workspace/ not /workspace/codi2/
  2. Binary not found: Check target/release/codi2 exists
  3. Upload failures: Verify GCS bucket permissions

Binary Download Issues​

  1. Authentication: Run gcloud auth login if needed
  2. Missing binary: Check exact name with gsutil ls
  3. Wrong path: Binary is at codi2- not codi2-<hash>

Quick Reference​

TaskCommand
Build locallycargo build --release
Submit to Cloud Buildgcloud builds submit --config=cloudbuild.yaml
List Cloud Buildsgcloud builds list --limit=5
List binaries in GCSgsutil ls -l gs://serene-voltage-464305-n2-builds/codi2/
Download latest binarygsutil cp gs://serene-voltage-464305-n2-builds/codi2/codi2- ./binaries/codi2-latest
Check version./binaries/codi2-latest --version

CODI2 Self-Documenting Features​

CODI2 is designed to be self-explanatory and discoverable:

Built-in Help System​

# Global help - shows all commands
./codi2-latest --help

# Command-specific help
./codi2-latest monitor --help    # Detailed monitoring options
./codi2-latest log-ai --help     # AI logging options
./codi2-latest session --help    # Session management

AI Environment Detection​

# Automatically detect AI development tools
./codi2-latest detect
# Detects: Claude Code, Cursor, VS Code with AI, Ollama, etc.

# List all supported AI tools (20+)
./codi2-latest list-ai-tools

# Show current session information
./codi2-latest whoami

Progressive Feature Discovery​

  1. Simple commands work immediately:

    ./codi2-latest test              # Test FDB connection
    ./codi2-latest log-ai "message"  # Log with AI attribution
    ./codi2-latest monitor .         # Monitor current directory

  2. Advanced features discoverable through help:

    • Multiple output formats (json, human, compact, fdb, coditect, codi)
    • File monitoring with cross-directory move detection
    • Hash algorithms (SHA256, SHA1, MD5, BLAKE3, XXH3)
    • Pattern filtering and hidden file detection
    • Session management and agent coordination

Replaces Multiple Scripts​

CODI2 unifies functionality from many bash scripts:

  • log-ai → replaces codi-log-ai.sh
  • log-system → replaces codi-log-system.sh
  • session init → replaces session-start-hook.sh
  • session identity → replaces set-session-identity.sh
  • export-manager → replaces export file handling

Testing CODI2 Functionality​

# Run comprehensive test suite
cd /home/halcasteel/v4/codi2
./scripts/test/comprehensive-test-suite.sh ./binaries/codi2-latest

# Run format tests
./scripts/test/test-all-formats.sh ./binaries/codi2-latest

# Test monitoring features
./scripts/test/test-enhanced-monitor.sh ./binaries/codi2-latest

Built with Rust, React, FoundationDB, and AI agents for autonomous development.