System Architecture

Technical deep-dive into ChaozCode's infrastructure, service architecture, data flow, and scaling strategies. Designed for high availability, security, and performance.

High-Level Architecture

ChaozCode is built on a microservices architecture with 20+ services running across a distributed infrastructure. The system is designed for horizontal scaling, fault tolerance, and sub-100ms response times.

┌─────────────────────────────────────────────────────────────────────────────┐
│                              CLIENT LAYER                                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐      │
│  │  Web App │  │   CLI    │  │  VS Code │  │   SDK    │  │ Webhooks │      │
│  │  React   │  │  Node.js │  │Extension │  │  JS/Py   │  │  Events  │      │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘      │
└───────┼─────────────┼─────────────┼─────────────┼─────────────┼────────────┘
        │             │             │             │             │
        └─────────────┴──────┬──────┴─────────────┴─────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                            API GATEWAY (Nginx)                               │
│  • SSL/TLS Termination  • Rate Limiting  • Load Balancing  • Auth Routing   │
│  • Request Validation   • CORS Handling  • Compression     • Caching        │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           CORE SERVICES LAYER                                │
│                                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│  │  API Server  │  │ Memory Spine │  │   Zearch     │  │ Solas Engine │    │
│  │  Port 8090   │  │  Port 8788   │  │  Port 5001   │  │  Port 8799   │    │
│  │  REST/WS     │  │  62 MCP Tools│  │  300 Endpoints│ │  AI Guardian │    │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘    │
│                                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│  │    Nexus     │  │   ZEmail     │  │   AgentZ     │  │  THERO Hub   │    │
│  │  Port 8099   │  │  Port 8899   │  │  Port 8001   │  │  tmux-hero   │    │
│  │ Orchestrator │  │Email Service │  │ 43 AI Tools  │  │Session Mgmt  │    │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘    │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                        REPOSITORY SERVICES LAYER                             │
│                                                                              │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐   │
│  │  AUIE   │ │AgentEco │ │ AgentZ  │ │ZamidaFS │ │  ZChat  │ │  Zagex  │   │
│  │  8850   │ │  8851   │ │  8852   │ │  8853   │ │  8855   │ │  8856   │   │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘   │
│                                                                              │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐   │
│  │PromptMZ │ │ThirdEye │ │CtxMgr   │ │ZDownload│ │ Z-Core  │ │ Zomega  │   │
│  │  8857   │ │  8858   │ │  8859   │ │  8860   │ │  8861   │ │  8863   │   │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘   │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           DATA LAYER                                         │
│                                                                              │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐          │
│  │  Vector Database │  │   SQLite/Redis   │  │   File Storage   │          │
│  │  (Memory Spine)  │  │  (Session/Cache) │  │   (Uploads/Logs) │          │
│  │  50K+ vectors    │  │  Fast lookups    │  │   Persistent     │          │
│  └──────────────────┘  └──────────────────┘  └──────────────────┘          │
└─────────────────────────────────────────────────────────────────────────────┘

Core Services (7)

Mission-critical services that power the ChaozCode platform.

ServicePortPurposeTechnologyStatus
Memory Spine 8788 Persistent vector memory, 62 MCP tools Python, SQLite, Vector DB Healthy
Zearch 5001 AI search, 300 endpoints Python, FastAPI Healthy
Solas API 8799 AI conscience, state management Python, Flask Healthy
ProBridgeZ 8090 API gateway, monitoring Node.js, Express Healthy
Nexus 8099 System orchestration Python Healthy
ZEmail 8899 Email platform, 8 MCP tools Python Healthy
AgentZ MCP 8001 43 AI tools + 23 skills Node.js Healthy

Memory Spine Architecture

Memory Spine is the central nervous system of ChaozCode, providing persistent memory across all AI interactions.

┌─────────────────────────────────────────────────────────────────┐
│                      MEMORY SPINE v0.4.0                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌───────────────┐    ┌───────────────┐    ┌───────────────┐   │
│  │   HTTP API    │    │   MCP Server  │    │  stdio Bridge │   │
│  │   Port 8788   │    │   Port 8789   │    │   for Copilot │   │
│  └───────┬───────┘    └───────┬───────┘    └───────┬───────┘   │
│          │                    │                    │            │
│          └────────────────────┼────────────────────┘            │
│                               ▼                                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                    Core Engine                           │   │
│  │  • Vector Embeddings (sentence-transformers)            │   │
│  │  • Semantic Search (~8ms avg)                           │   │
│  │  • Knowledge Graph Builder                              │   │
│  │  • Context Window Optimizer                             │   │
│  │  • Deduplication Engine                                 │   │
│  └─────────────────────────────────────────────────────────┘   │
│                               │                                  │
│                               ▼                                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                    Storage Layer                         │   │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐        │   │
│  │  │  Vector DB │  │  SQLite    │  │  Pin Store │        │   │
│  │  │  50K cap   │  │  Metadata  │  │  Critical  │        │   │
│  │  └────────────┘  └────────────┘  └────────────┘        │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

Tool Categories (62 total):
├── Core Operations (6): store, search, retrieve, recent, update, delete
├── Context & Intelligence (6): context_window, summarize, insights, analytics
├── Pinned Context (3): pin, get_pin, unpin
├── Knowledge Graphs (3): graph_build, graph_query, link
├── Codebase Analysis (6): analyze, context, suggest, generate, symbols, deps
├── Conversations (5): start, add_turn, get_context, save, agent_handoff
├── Batch Operations (3): batch_store, batch_tag, batch_delete
├── Advanced Search (8): query_dsl, advanced_search, find_similar, timeline, cluster
├── Tagging & Organization (5): auto_tag, importance_boost, semantic_merge
├── Version Control (4): version_history, revert, compress, archive
├── Maintenance (9): stats, health_check, consolidate, run_maintenance
└── Export & Lifecycle (4): export, forget, lifecycle_rules, benchmark

Performance Characteristics

⚡ Speed

  • Search: ~8ms average
  • Store: ~15ms average
  • Context build: ~25ms
  • Batch ops: 1000+/sec

📊 Capacity

  • Vector capacity: 50,000
  • Storage: ~2.8GB at full
  • Embedding model: all-MiniLM-L6-v2
  • Dimension: 384

Request Flow

How a typical API request flows through the system:

Client Request
      │
      ▼
┌─────────────┐
│   Nginx     │ ← SSL termination, rate limiting
│   Gateway   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│    Auth     │ ← API key validation, JWT decode
│   Service   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  ProBridgeZ │ ← Route to appropriate service
│   Router    │
└──────┬──────┘
       │
       ├─────────────────┬─────────────────┬─────────────────┐
       ▼                 ▼                 ▼                 ▼
┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│    Query    │   │   Memory    │   │  Codebase   │   │   Agent     │
│   Handler   │   │   Handler   │   │   Handler   │   │   Handler   │
└──────┬──────┘   └──────┬──────┘   └──────┬──────┘   └──────┬──────┘
       │                 │                 │                 │
       │                 ▼                 │                 │
       │          ┌─────────────┐          │                 │
       │          │Memory Spine │          │                 │
       │          │  Context    │          │                 │
       │          └─────────────┘          │                 │
       │                 │                 │                 │
       └─────────────────┴─────────────────┴─────────────────┘
                                   │
                                   ▼
                          ┌─────────────────┐
                          │   LLM Provider  │
                          │ OpenAI/Anthropic│
                          └────────┬────────┘
                                   │
                                   ▼
                          ┌─────────────────┐
                          │ Response + Cache│
                          └─────────────────┘

Repository Services (13)

Specialized services for extended functionality.

ServicePortPurpose
AUIE8850UI generation, 100 capabilities
Agent-Economy8851Multi-agent framework, 5 agent types
AgentZ8852Agent mesh, discovery, clustering
Zamida-FS8853Context graph, file system analysis
ZChat8855Multi-agent chat interface
Zagex8856Workflow orchestrator v2.9.1
PromptMasterZ8857Prompt engineering toolkit
ThirdEye8858World events monitoring
Context-Mgr8859Session context management
ZDownload8860Download manager
Z-Core88617 agent types
ASCII Art8862ASCII art generation
Zomega8863Module loader

Data Flow & Storage

Memory Spine Data Flow

User Input → Embedding → Vector Store → Index Update
                                              ↓
                                         Knowledge Graph Update
                                              ↓
                                         Deduplication Check
                                              ↓
                                         Persistence (SQLite)

Storage Systems

🧠 Vector Database

Memory Spine's vector storage for semantic search. Uses sentence-transformers for embeddings.

  • Capacity: 50,000 vectors
  • Model: all-MiniLM-L6-v2
  • Similarity: Cosine

📄 SQLite

Metadata storage for memories, sessions, and configuration.

  • Location: /var/lib/memory-spine/
  • Backup: Daily automated
  • WAL mode enabled

⚡ Redis (Optional)

High-speed cache for sessions and frequently accessed data.

  • Session cache: 24h TTL
  • Rate limit counters
  • Pub/sub for events

Security Architecture

🔐 Authentication

  • API key authentication (Bearer tokens)
  • JWT for session management
  • OAuth2 integration (GitHub)
  • Key rotation support

🛡️ Network Security

  • TLS 1.3 everywhere
  • UFW firewall rules
  • Fail2ban protection
  • DDoS mitigation

📝 Data Security

  • Encryption at rest
  • API key hashing (SHA256)
  • Memory isolation per user
  • GDPR compliance tools

🔍 Monitoring

  • Real-time health dashboard
  • Automated security scans
  • Audit logging
  • Anomaly detection

Scaling Strategy

Current Infrastructure

Running on VPS3 (primary) with optional VPS1/VPS2 workers:

Horizontal Scaling

                    ┌─────────────┐
                    │Load Balancer│
                    └──────┬──────┘
                           │
          ┌────────────────┼────────────────┐
          ▼                ▼                ▼
   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
   │   VPS3      │  │   Worker 1  │  │   Worker 2  │
   │   Primary   │  │   (VPS1)    │  │   (VPS2)    │
   │   32GB RAM  │  │   2GB RAM   │  │   8GB RAM   │
   └─────────────┘  └─────────────┘  └─────────────┘
          │
          ▼
   ┌─────────────────────────────────────────┐
   │         Shared Memory Spine             │
   │         (Central State)                 │
   └─────────────────────────────────────────┘

THERO Orchestration

THERO (tmux-hero) manages agent scaling and distribution:

# Auto-scale based on load
thero adaptive start

# Manual scaling
thero swarm 5           # Spawn 5 agents
thero scaler up 3       # Add 3 workers
thero cluster           # View cluster status