Coditect AI IDE - Multi-llm Browser IDE

Browser-Based IDE with Local llm Support, Multi-Agent Architecture, and Real-Time Collaboration

🧪 Testing Infrastructure

Latest: 2025-10-28 - Build #18 SUCCESS - Permission Fix Deployed ✅ OPERATIONAL

Status Report: 2025-10-28T00:50:00Z - Complete Project Status 📊

MVP Scaling: 2025-10-27 - Scaling Analysis for 20 Users 📈

📐 Architecture Evolution (2025-10-27)

Comprehensive documentation of design evolution:

✅ ADR-028: theia IDE Integration Evolution

Why we adopted Eclipse theia instead of building a custom IDE
9-10 months time savings, $225K cost savings, 3x more features at MVP
68 theia packages, custom branding, VS Code extension compatibility
Future roadmap: MCP integration, multi-llm chat panel

✅ ADR-029: StatefulSet Persistent Storage Migration

Solved critical data loss problem with persistent volumes
Migration from Deployment → StatefulSet with PVCs
100 GB workspace + 10 GB config per user
Capacity planning for 10-20 → 50-100 → 500+ users

✅ Hybrid Storage Architecture (ADR-028 Part 1, Part 2) (2025-10-28)

Cost Optimization: 96% savings vs NFS ($7/user vs $205/user)
Hybrid Approach: Shared base (Docker layers) + user-specific PVCs (10 GB)
Performance: <1ms latency with GCE Persistent Disk SSD
Scalability: 10 user slots per pod, dynamic assignment
Implementation: 6 phases (30-38 hours), daily backups with 7-day retention
Deployment YAMLs: Current (✅ WORKING) vs Hybrid (🚧 TESTING)

Session Exports:

Build #17 Session 1 - Build #17 deployment readiness
Build #17 Session 2 - Architecture evolution documentation

🚀 Quick Start

# Clone the repository
git clone https://github.com/coditect-ai/Coditect-v5-multiple-llm-IDE.git
cd Coditect-v5-multiple-llm-IDE

# Install dependencies
npm install

# Start both services
./scripts/start-coditect.sh

Access the IDE:

V5 Frontend: http://localhost:5173 (⭐ Main application)
IDE Backend: http://localhost:3000 (Direct IDE access)

Detailed Guide: See quickstart.md for complete instructions.

🧪 Testing & Quality Assurance

Comprehensive testing infrastructure with automated CI/CD

# Run all tests locally
./scripts/test-runner.sh

# Frontend tests with watch mode
npm run test:watch

# Backend tests
cd backend && cargo test

# Coverage reports
npm run test:coverage

Testing Documentation:

📋 Testing Strategy - Complete methodology and framework documentation
🚀 Implementation Guide - Detailed setup and usage instructions
🔒 Branch Protection Setup - Quality gates and repository protection
⚙️ CI/CD Pipeline - Automated testing workflow

Quality Metrics:

✅ 70%+ Test Coverage across frontend and backend
✅ Automated Security Scanning for dependencies
✅ Type Safety Enforcement with TypeScript
✅ Code Quality Gates on all pull requests

📊 Project Status

Current Phase: ✅ BUILD #18 OPERATIONAL - Pods Healthy, Ready for MVP Scaling

Latest Updates (2025-10-28)

✅ Build #18 Deployed Successfully

Fixed CrashLoopBackOff (permission denied errors)
Non-root execution working (coditect user UID 1001)
All pods healthy and serving traffic on GKE
Image: 8449bd02-7a28-4de2-8e26-7618396b3c2f

⚠️ MVP Scaling Requirement

Current: 3 pods (3-6 user capacity)
Required: 10-15 pods for 20 user MVP launch
Cost: $150/month → $500-750/month
Action needed: Scale + deploy HPA before beta testing
Production V5 frontend build ready (dist/ folder, 1.2 MB)

✅ Session Documentation Created

Docker Build Session - Complete V5+theia architecture deep dive, build strategy, testing procedures, troubleshooting guide with ~27 minute build timeline
Quick Reference Card - Fast command reference for Docker build, testing, and deployment
Checkpoint Status - Current deployment status and next steps

✅ Combined Deployment Architecture

Single-container deployment strategy (V5 + theia + NGINX)
9 deployment files created (Dockerfiles, NGINX config, Cloud Build, K8s manifests)
Complete documentation: Architecture diagrams, deployment guides, troubleshooting

Previous Updates (2025-10-08)

✅ Coditect AI Branding Implementation

Custom "Coditect AI Agents" welcome message in theia AI Chat
Custom robot logo (SVG)
Agent instructions: @Coditect-Code-Generator, @Coditect-UI-Designer, @Coditect-Code-Reviewer
Fixed InversifyJS "Ambiguous match" error using rebind() pattern

✅ V5 Frontend Wrapper

React 18 + Vite 5 dev server running on port 5173
Apple-quality design system with 500+ design tokens
28 complete pages (Login, Settings, Documentation, etc.)
Mobile-first design with 56px touch targets
Embeds theia IDE in workspace tab

✅ Startup Scripts

scripts/start-coditect.sh - Start both services (foreground/background)
scripts/stop-coditect.sh - Stop all services cleanly
Comprehensive logging and status reporting

🤖 Claude Code Configuration (READ FIRST!)

📁 .claude/ Directory - Essential Claude Code setup and agent resources:

.claude/CLAUDE.md - Autonomous Development Mode, Context Engineering, Project Configuration
.claude/README.md - Directory structure and quick start guide

🎭 Available Agents & Commands (Updated: 2025-10-14): 3. .claude/agents/ - 6 custom agents (codebase-analyzer, codebase-locator, pattern-finder, thoughts-analyzer, web-search-researcher) 4. .claude/commands/ - 24 workflow commands (create_plan, implement_plan, research_codebase, debug, ci_commit, create_handoff, etc.) 5. .claude/agents-reference/ - 84 community agents (backend-architect, rust-pro, typescript-pro, database-architect, security-auditor, cloud-architect) - Git submodule 6. .claude/commands-reference/ - 42 development tools (security-scan, api-scaffold, db-migrate, monitoring-setup) - Git submodule

📚 Reference Materials (Updated: 2025-10-14): 7. archive/coditect-v4/ - V4 Reference (19 FDB data models, 88 ADRs, agent patterns) - Git submodule

archive/coditect-v4/docs/reference/database-models/ - Complete V4 data model documentation

archive/agents-research-plan-code/ - Agent Research (Multi-llm patterns, human-in-loop) - Git submodule
docs/analysis-human-layer/ - 10 analysis documents (architecture, tech stack, llm integration strategies)

Why read .claude/ first?

🚀 Autonomous Mode: Enables multi-hour coding sessions with state tracking (DELIBERATION, RESEARCH, ACTION modes)
🎯 Context Engineering: Anthropic best practices for efficient token usage and long-horizon tasks
🤖 Specialized Agents: Production-ready agents for Rust, TypeScript, FoundationDB, GCP, and more
🛠️ Development Tools: Security scanning, API generation, database migrations, monitoring setup
📚 Community Knowledge: 15 multi-agent workflows and extensive examples
📖 V4 Patterns: Complete reference for FDB data models and agent architectures
🔬 Research: Multi-llm integration analysis and human-in-the-loop patterns

🎯 Overview

Coditect AI IDE is a next-generation browser-based integrated development environment that combines:

🧠 16+ Local llm Models via LM Studio (no cloud required)
🤖 Multi-Agent System with MCP and A2A protocols
📑 Multi-Session workspaces for parallel project work
💻 VS Code-Like Experience built on Eclipse theia 1.65
🔒 Privacy-First with local-only processing
🌐 Browser-Based with no installation needed

Two-Service Architecture

┌─────────────────────────────────────┐
│  V5 Frontend Wrapper (React + Vite) │  Port 5173
│  ├─ Header & Navigation             │
│  ├─ 28 Complete Pages                │
│  ├─ Settings (8 sections)            │
│  └─ workspace Tab (embeds theia)    │
└─────────────────┬───────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│  theia Backend (Eclipse theia)      │  Port 3000
│  ├─ Monaco editor                    │
│  ├─ File Explorer                    │
│  ├─ terminal (xterm.js)              │
│  └─ AI Chat (Coditect Branding)     │
└─────────────────────────────────────┘

🎨 Key Features

theia Backend (Port 3000)

✅ Eclipse theia 1.65 - Complete IDE framework
✅ Custom Branding - "Coditect AI Agents" with robot logo
✅ Monaco editor - Full VS Code editing experience
✅ AI Chat - Integrated AI assistance with custom agents
✅ File Explorer - Complete file tree navigation
✅ terminal - Integrated xterm.js terminal
✅ Extensions - VS Code extension compatible

V5 Frontend Wrapper (Port 5173)

✅ Apple-Quality Design System - 500+ design tokens, unified theme
✅ Mobile-First - Touch-friendly with 56px tap targets
✅ 28 Complete Pages - Full application flow
- Login, Register, Profile
- Settings (8 sections with TouchFriendlyCard)
- Documentation Hub (18 sub-pages)
- AI Studio Tab (Loveable-style interface)
- workspace Tab (theia iframe)
- FAQ, Support, Status
✅ React 18 + TypeScript - Modern React with full type safety
✅ Vite 5 - Lightning-fast HMR and dev server
✅ Chakra UI 2.8 - Accessible component library

Multi-llm Support

🧠 LM Studio - 16+ local models (Qwen, Llama, DeepSeek, etc.)
🤖 Claude Code - Anthropic's coding assistant
🦙 Ollama - Easy local llm deployment
🌐 OpenAI - Optional cloud API
💎 Gemini - Google's multimodal AI
⚡ Grok - xAI's conversational AI

Agent System

Hierarchical Agents:

Coordinator Agent
├── Code Generation Agent (@Coditect-Code-Generator)
│   ├── TypeScript Sub-Agent
│   ├── Python Sub-Agent
│   └── Rust Sub-Agent
├── UI Design Agent (@Coditect-UI-Designer)
│   ├── React Sub-Agent
│   └── CSS Sub-Agent
└── Code Review Agent (@Coditect-Code-Reviewer)
    ├── Security Review
    ├── Performance Review
    └── Style Review

Protocols:

MCP (Model Context Protocol) - Tool/resource access
A2A (Agent-to-Agent) - Agent collaboration

🚀 Deployment Status

Production Deployment (GCP)

Infrastructure: serene-voltage-464305-n2

✅ GKE Cluster: codi-poc-e2-cluster (us-central1-a)
✅ FoundationDB: 3-node StatefulSet at 10.128.0.8:4500
✅ Domain/SSL: coditect.ai with Google-managed certificate
✅ Container Registry: gcr.io/serene-voltage-464305-n2

Deployment Architecture:

┌─────────────────────────────────────┐
│  Docker Container (Port 80)         │
├─────────────────────────────────────┤
│  NGINX                              │
│  ├─→ / → V5 Frontend (dist/)       │
│  └─→ /theia → theia (localhost:3000)│
│                                     │
│  Node.js (Port 3000)                │
│  └─→ Eclipse theia IDE              │
└─────────────────────────────────────┘

Deployment Files:

deployment/dockerfile.local-test - Production build (uses pre-built dist/)
deployment/nginx-combined.conf - NGINX routing configuration
start-combined.sh - Container startup script
deployment/cloudbuild-combined.yaml - Google Cloud Build config
deployment/k8s/k8s-combined-deployment.yaml - Kubernetes manifests
DEPLOYMENT-architecture.md - Complete architecture docs
deployment-summary.md - Quick reference guide
deploy-combined.md - Step-by-step deployment
checkpoint-docker-setup.md - Current status & next steps

Next Steps:

Install Docker client for local testing
Test build: docker build -f deployment/dockerfile.local-test -t coditect-combined:test .
Deploy to Cloud Build: gcloud builds submit --config deployment/cloudbuild-combined.yaml
Deploy to GKE cluster

🧪 Deployment & Testing Infrastructure

Created: 2025-10-14 Status: ✅ Complete and Operational

Overview

Automated testing suite that catches ALL 9 deployment issues in < 2 minutes, BEFORE wasting 10-20 minutes on Cloud Build.

Impact:

⚡ 79% faster (80-160 min → 17 min per deployment)
💰 $40-80 saved per incident (no failed builds)
✅ Zero failed deployments from config issues
🚨 Catches issues early (< 2 min local test vs 10-20 min Cloud Build)

Testing Infrastructure

testing-infrastructure-complete.md - Complete automated testing suite overview
docs/testing-summary.md - Quick reference guide
docs/testing-guide.md - Complete documentation (558 lines)

Test Scripts

Pre-Deployment Validation:

scripts/test-deployment.sh - Comprehensive validation (403 lines)
- Tests 9 categories: config, source code, build, Docker, NGINX, Cloud Build, K8s
- Runs in < 2 minutes
- Exit code 0 = safe to deploy, 1 = issues found

Live Endpoint Testing:

scripts/test-endpoints.sh - Production endpoint verification (122 lines)
- Tests health, frontend, API paths, old path 404s
- Runs in < 10 seconds
- Usage: ./scripts/test-endpoints.sh https://coditect.ai

Convenient Commands:

Makefile - Easy-to-remember test commands (73 lines)

make test              # Run all pre-deployment tests
make test-config       # Quick config check (< 5 sec)
make test-build        # Test build process
make test-endpoints    # Test live endpoints
make deploy            # Deploy (runs tests first!)
make clean             # Clean build artifacts

Deployment Files

Cloud Build & CI/CD:

deployment/cloudbuild-combined.yaml - GCP Cloud Build with automated validation
- Step 0: Pre-build validation (< 1 min) - catches config issues early
- Step 1: Build + verification (~ 4 min) - validates built files

Docker & Container:

deployment/dockerfile.local-test - Production Docker image
deployment/dockerfile.combined - Multi-stage build
deployment/nginx-combined.conf - NGINX routing configuration
start-combined.sh - Container startup script

Kubernetes:

deployment/k8s/k8s-combined-deployment.yaml - Kubernetes deployment manifests

Critical Configuration Files

⚠️ MUST be correct for successful deployment:

.env.production - Environment variables
- CRITICAL: Must have VITE_API_URL=/api/v5 (NOT /api)
- Gets compiled into JavaScript at build time by Vite
package.json - Build scripts
- CRITICAL: Must have prototype:build script for V5 frontend
- "prototype:build": "tsc && vite build" ✅
- NOT "build": "npm run theia:build" ❌

Issue Tracking

docs/10-execution-plans/api-integration-fixes-complete.md - Complete documentation of all 9 deployment issues and fixes:

Issues #1-5 (Infrastructure):

✅ Frontend auth check missing
✅ Duplicate /v5 API paths
✅ NGINX proxy route missing
✅ Incomplete Kubernetes DNS name
✅ GCP Ingress routing to wrong backend

Issues #6-9 (Build & Config): 6. ✅ Docker layer caching (reused stale dist/) 7. ✅ npm package-lock.json sync issues 8. ✅ Wrong build script (theia:build vs prototype:build) 9. ✅ Wrong environment variable (VITE_API_URL=/api vs /api/v5)

Quick Testing Workflow

# Before every deployment
make test-config        # < 5 seconds - config check
make test               # ~ 2 minutes - full validation

# If tests pass, deploy
make deploy             # Automatic Cloud Build

# After deployment, verify
make test-endpoints     # ~ 10 seconds - live verification

Test Demonstration

Catches Wrong Configuration:

# Simulate wrong config
sed -i 's|/api/v5|/api|' .env.production

# Run test
make test-config
# Output: ✗ .env.production is wrong!
# Result: ✅ Test correctly prevents bad deployment

🔧 Socket.IO Investigation & Troubleshooting

Created: 2025-10-20 Status: ⏳ In Progress - Multiple root causes identified, fixes being applied

Problem Statement

Users accessing theia IDE at https://coditect.ai/theia experience HTTP 400 Bad Request errors when establishing Socket.IO connections. This breaks real-time features including:

terminal sessions
File watching
Live code collaboration
Auto-save functionality

Investigation Findings

TWO Root Causes Identified:

✅ CDN Caching (FIXED) - GCP Cloud CDN was caching Socket.IO requests with stale session IDs
- Solution: Disabled CDN in BackendConfig (k8s/backend-config-no-cdn.yaml)
- Validation: CDN headers removed from responses
⏳ Session Affinity Missing (IN PROGRESS) - GCP backend service shows SESSION_AFFINITY: NONE
- Problem: Service missing BackendConfig annotation (NEG requirement)
- Solution: Annotated Service with BackendConfig reference
- Status: Propagating to GCP load balancer (2-5 minutes)

Additional Fixes Recommended (from reference docs):

P0: WebSocket annotation to Ingress (85% success probability)
P0: Health check endpoint creation (70% success probability)
P1: Increased backend timeout and connection draining optimization

Comprehensive Documentation

Investigation Package (~150 pages of analysis):

socket.io-issue/analysis-troubleshooting-guide.md - START HERE (20KB)
- Complete investigation findings and evidence chain
- Diagnostic commands for each system layer
- Fix procedures with validation tests
- Integration with reference documentation
- Success criteria and monitoring recommendations
socket.io-issue/additional-research-pathways.md (19KB)
- High-value research pathways (P0-P2)
- Quick wins and emergency rollback procedures
- Long-term improvements (monitoring, health checks, regression tests)
- Learning opportunities for team
socket.io-issue/README.md - Investigation package index
- 8 comprehensive documents (~150 pages)
- Quick navigation by role (Executive, Engineer, On-Call)
- Quick start guide for immediate issue resolution
- Implementation checklist
Reference Documentation (from investigation package):
- executive-summary.md - High-level overview with 5 prioritized fixes
- quick-reference.md - Emergency cheat sheet (2 minutes)
- investigation-runbook.md - Step-by-step diagnostic procedures (20 pages)
- diagnostic-decision-tree.md - Structured troubleshooting logic (15 questions)
- fix-implementation-guide.md - Detailed fix procedures with validation tests (30 pages)
- architecture-diagrams.md - Visual representation of system and issues (8 Mermaid diagrams)
- socketio-diagnostics.sh - Automated diagnostic script (400 lines bash)

Quick Testing Workflow

# Test Socket.IO inside cluster
kubectl exec -n coditect-app deployment/coditect-combined -- \
  curl -s -o /dev/null -w "%{http_code}\n" \
  http://localhost/theia/socket.io/?EIO=4\&transport=polling

# Test via Ingress
curl -s -o /dev/null -w "%{http_code}\n" \
  https://coditect.ai/theia/socket.io/?EIO=4\&transport=polling

# Run automated diagnostics
chmod +x socket.io-issue/socketio-diagnostics.sh
./socket.io-issue/socketio-diagnostics.sh --verbose

Next Steps

✅ Validate session affinity propagation (check GCP backend service)
🔄 Apply WebSocket annotation to Ingress
🔄 Create /health endpoint in nginx
🔄 Run automated diagnostic script for comprehensive validation
🔄 Test at https://coditect.ai/theia after all fixes applied
🔄 Monitor Socket.IO connection success rates for 24 hours
🔄 Implement long-term improvements (monitoring dashboard, automated health checks)

Configuration:

k8s/backend-config-no-cdn.yaml - BackendConfig with CDN disabled
nginx-combined.conf - NGINX routing with WebSocket support
docs/fixes/socket-io-cdn-fix.md - Initial CDN fix documentation

See Also:

CLAUDE.md - Complete status and investigation timeline
Testing Infrastructure - Pre-deployment validation (below)

🔍 Deployment Archeology - Finding Previous Successful Builds

When deployment fails, use deployment archeology to find what worked before.

Quick Process

# 1. Get deployment creation date
kubectl get deployment <NAME> -n coditect-app -o jsonpath='{.metadata.creationTimestamp}'

# 2. Find successful builds on that date
gcloud builds list --filter="createTime>='YYYY-MM-DDT00:00:00Z'" --limit=20

# 3. Analyze successful build config
gcloud builds describe <BUILD_ID> --format="yaml(steps,options)"

# 4. Search git history for files
git log --all --full-history -- <FILENAME>

# 5. Restore archived files if needed
cp docs/99-archive/deployment-obsolete/<FILE> ./<FILE>

Real Example: Combined Service Recovery (Oct 18, 2025)

Problem: dockerfile.combined failing to build (npm ci errors, Python missing, wrong build script)

Solution Found:

Deployment created: 2025-10-13T09:58:29Z
Successful build: 6e95a4d9 at 09:50:07Z (8 min before deployment)
Used file: dockerfile.local-test (archived, not dockerfile.combined!)
Machine: E2_HIGHCPU_32 (32 CPUs, NOT 8 CPUs)
Node memory: 8GB heap (NODE_OPTIONS=--max_old_space_size=8192)
Pre-requisite: Build frontend first (npm run build creates dist/)

Key Configuration:

# cloudbuild-combined.yaml
steps:
  - name: 'gcr.io/cloud-builders/docker'
    args: ['-f', 'dockerfile.local-test', ...]  # NOT dockerfile.combined

options:
  machineType: 'E2_HIGHCPU_32'  # 32 CPUs for theia webpack
  env:
    - 'NODE_OPTIONS=--max_old_space_size=8192'  # 8GB heap

Recovery Steps:

# Restore working Dockerfile
cp docs/99-archive/deployment-obsolete/dockerfile.local-test ./

# Update cloudbuild-combined.yaml
# - Change: dockerfile.combined → dockerfile.local-test
# - Change: N1_HIGHCPU_8 → E2_HIGHCPU_32
# - Add: NODE_OPTIONS=--max_old_space_size=8192

# Build frontend first (CRITICAL!)
npm run build  # Creates dist/ folder

# Deploy with proven config
gcloud builds submit --config cloudbuild-combined.yaml .

Automation Script

Location: .claude/skills/deployment-archeology/SKILL.md

#!/bin/bash
# deployment-archeology.sh - Find previous successful build config

DEPLOYMENT=$1
NAMESPACE=${2:-default}

echo "=== Deployment Archeology ==="

# Step 1: Get deployment date
DEPLOY_DATE=$(kubectl get deployment $DEPLOYMENT -n $NAMESPACE -o jsonpath='{.metadata.creationTimestamp}')
SEARCH_DATE=$(date -d $DEPLOY_DATE '+%Y-%m-%d')

echo "Deployment created: $DEPLOY_DATE"
echo "Searching builds on: $SEARCH_DATE"

# Step 2: Find builds on that date
gcloud builds list \
  --filter="createTime>='${SEARCH_DATE}T00:00:00Z' AND createTime<='${SEARCH_DATE}T23:59:59Z'" \
  --format="table(id,status,createTime)" \
  --limit=20

# Step 3: Show git commits around that date
git log --since="$SEARCH_DATE" --until="$(date -d "$SEARCH_DATE + 1 day" '+%Y-%m-%d')" --oneline --all | head -20

echo ""
echo "Next steps:"
echo "1. Identify successful build ID (STATUS=SUCCESS)"
echo "2. Run: gcloud builds describe <BUILD_ID> --format='yaml(steps,options)'"
echo "3. Check for archived files: find . -name 'Dockerfile*' | grep archive"
echo "4. Compare current config vs successful build config"

Common Gotchas

❌ Assuming current files match deployed version
❌ Not checking environment variables in Cloud Build options
❌ Forgetting to check for archived/moved files
❌ Using wrong Dockerfile (may have multiple variants)
❌ Missing build prerequisites (like pre-built dist/ directory)

📁 Project Structure

/workspace/PROJECTS/t2/
├── quickstart.md                    # ⭐ Quick start guide
├── README.md                        # This file
├── CLAUDE.md                        # Claude Code instructions
├── checkpoint-docker-setup.md      # ⭐ Current deployment status
├── start-coditect.sh               # Start both services
├── stop-coditect.sh                # Stop all services
│
├── dockerfile.local-test           # 🚀 Production Docker build
├── dockerfile.combined             # Alternative build (has Python issue)
├── nginx-combined.conf             # NGINX routing config
├── start-combined.sh               # Container startup script
├── cloudbuild-combined.yaml        # Google Cloud Build config
├── k8s-combined-deployment.yaml    # Kubernetes manifests
├── DEPLOYMENT-architecture.md      # Architecture documentation
├── deployment-summary.md           # Quick reference
├── deploy-combined.md              # Deployment guide
│
├── .claude/                        # 🤖 CLAUDE CODE CONFIGURATION (READ THIS!)
│   ├── CLAUDE.md                   # Autonomous mode, context engineering, project config
│   ├── README.md                   # Directory structure and quick start
│   ├── CLAUDE-GLOBAL-REFERENCE.md  # Reference from global .claude repo
│   ├── settings.local.json         # Auto-approved commands, MCP servers
│   ├── agents/                     # 8 custom project-specific agents
│   │   ├── orchestrator.md         # 🎯 Multi-agent orchestrator (production workflows)
│   │   ├── codebase-analyzer.md
│   │   ├── codebase-locator.md
│   │   ├── codebase-pattern-finder.md
│   │   ├── project-organizer.md
│   │   ├── thoughts-analyzer.md
│   │   ├── thoughts-locator.md
│   │   └── web-search-researcher.md
│   ├── skills/                     # ⚡ 15 AUTOMATION SKILLS (CHECK FIRST!)
│   │   ├── REGISTRY.json           # 🔍 Fast skill lookup index
│   │   ├── README.md               # Skill discovery documentation
│   │   ├── build-deploy-workflow/  # Build + Deploy + Document (saves 40 min)
│   │   ├── gcp-resource-cleanup/   # Clean legacy GCP (saves 28 min, $50-100/mo)
│   │   ├── git-workflow-automation/ # Git operations (saves 8 min)
│   │   ├── cross-file-documentation-update/ # Sync 4 docs (saves 13 min)
│   │   ├── deployment-archeology/  # Find previous successful deployments
│   │   ├── foundationdb-queries/   # FDB patterns + tenant isolation
│   │   ├── rust-backend-patterns/  # Actix-web patterns
│   │   ├── search-strategies/      # Grep/Glob optimization
│   │   ├── framework-patterns/     # Event-driven, FSM patterns
│   │   ├── evaluation-framework/   # llm-as-judge patterns
│   │   ├── production-patterns/    # Circuit breakers, error handling
│   │   ├── communication-protocols/ # Multi-agent handoff
│   │   ├── google-cloud-build/     # Cloud Build optimization
│   │   ├── internal-comms/         # Team communication
│   │   └── multi-agent-workflow/   # Token management, orchestration
│   ├── scripts/                    # 🛠️ Automation scripts
│   │   └── build-skill-registry.py # Generate REGISTRY.json
│   ├── commands/                   # 52 workflow commands (24 custom + 28 reference)
│   │   ├── create_plan.md, implement_plan.md, research_codebase.md
│   │   ├── ci_commit.md, debug.md, local_review.md
│   │   ├── create_handoff.md, resume_handoff.md
│   │   └── ... (52 total commands)
│   ├── hooks/                      # Pre/post execution hooks
│   │   └── README.md
│   ├── agents-reference/           # Git submodule: 84 specialized agents
│   │   ├── agents/                 # backend-architect, rust-pro, typescript-pro, etc.
│   │   ├── workflows/              # Multi-agent orchestration (15 workflows)
│   │   └── tools/                  # Development utilities
│   └── commands-reference/         # Git submodule: 42 development tools
│       ├── tools/                  # security-scan, api-scaffold, db-migrate, etc.
│       ├── workflows/              # Command coordination patterns
│       └── examples/               # Usage examples
│
├── theia-app/                      # theia Backend (Port 3000)
│   ├── coditect-branding-solution.md   # Branding implementation guide
│   ├── src/browser/
│   │   ├── coditect-branding-frontend-module.ts  # Custom branding
│   │   └── coditect-chat-welcome-provider.tsx    # Custom AI Chat
│   ├── src-gen/frontend/           # Generated theia code
│   ├── lib/                         # Compiled JavaScript
│   └── package.json                 # theia dependencies
│
├── src/                            # V5 Frontend Source (Port 5173)
│   ├── components/                  # React components
│   │   ├── theia/                   # theia widget wrappers
│   │   ├── ai-studio/                # AI Studio Tab
│   │   └── workspace/               # workspace Tab
│   ├── pages/                       # 28 complete pages
│   ├── theme/                       # Apple-quality design system
│   ├── services/                    # API integration
│   ├── stores/                      # Zustand state management
│   ├── agents/                      # Custom agent definitions
│   ├── app.tsx                      # Main app with 28 routes
│   └── main.tsx                     # Entry point
│
├── docs/                           # Documentation
│   ├── DEFINITIVE-V5-architecture.md        # ⭐ Complete V5 design
│   ├── apple-quality-design-system.md       # Design principles
│   ├── v5-frontend-build-verification.md    # Build status
│   ├── theia-ai-research-findings.md        # theia 1.65 capabilities
│   ├── 01-getting-started/          # Quick start guides
│   ├── 02-architecture/             # SDD, TDD, architecture
│   ├── 03-infrastructure/           # GCP, FoundationDB
│   ├── 04-security/                 # Security hardening
│   ├── 07-adr/                      # Architecture decisions
│   ├── 08-v4-reference/             # V4 reference materials
│   ├── 10-execution-plans/          # Deployment tracking
│   ├── 11-analysis/                 # System analysis & provisioning strategies
│   │   └── monitor-codi-container-provisioning-strategy.md  # 🚀 File monitoring & agent coordination (HYBRID approach)
│   └── analysis-human-layer/        # 📚 Multi-llm integration analysis (NEW)
│       ├── 01-executive-summary.md
│       ├── 02-architectural-deep-dive.md
│       ├── 08-multi-llm-technical-implementation-details.md
│       └── llm-implementations/     # Claude, Gemini, Grok, OpenAI patterns
│
├── archive/                        # 📦 Reference Materials & Research (NEW)
│   ├── coditect-v4/                # Git submodule: V4 reference
│   │   ├── docs/reference/database-models/  # 19 FDB data models
│   │   ├── docs/07-adr/            # 88 ADRs from V4
│   │   └── agents/                 # V4 agent system patterns
│   └── agents-research-plan-code/  # Git submodule: Agent research
│       ├── .claude/                # Agent and command templates
│       └── docs/                   # Research documentation
│
├── backend/                        # Rust Backend (GCP Deployment)
│   ├── src/                         # Actix-web API
│   ├── Dockerfile                   # Production Docker image
│   └── cloudbuild.yaml              # GCP Cloud Build config
│
├── scripts/                        # Utility scripts
│   └── fix-doc-links.sh             # Fix documentation links
│
├── .backup/                        # Backup files
├── package.json                    # Root dependencies
├── vite.config.ts                  # Vite configuration
└── tsconfig.json                   # TypeScript configuration

🚀 Getting Started

Prerequisites

Node.js 20+ (LTS recommended)
npm or yarn
LM Studio (optional, for local llm support)
Git for version control

Installation

# 1. Clone repository
git clone https://github.com/coditect-ai/Coditect-v5-multiple-llm-IDE.git
cd Coditect-v5-multiple-llm-IDE

# 2. Install dependencies
npm install

# 3. Install theia dependencies
cd theia-app
npm install
cd ..

Running the Application

Option 1: Use Convenience Scripts (Recommended)

# Start both services in background
./scripts/start-coditect.sh

# OR start in foreground (Ctrl+C stops both)
./scripts/start-coditect.sh --foreground

# Stop all services
./scripts/stop-coditect.sh

Option 2: Manual Start

# terminal 1: Start theia backend
cd theia-app
npm start
# Runs on http://localhost:3000

# terminal 2: Start V5 frontend wrapper
cd ..
npm run prototype:dev
# Runs on http://localhost:5173

Accessing the IDE

⭐ V5 Frontend (Main): http://localhost:5173
- Complete Coditect UI with all pages
- workspace tab embeds theia IDE
theia Direct: http://localhost:3000
- Direct access to Eclipse theia
- AI Chat with Coditect branding
- Useful for testing theia features

🛠️ Development

Build Commands

# V5 Frontend (Vite has HMR - auto-reload on changes)
npm run prototype:dev           # Start dev server
npm run prototype:build         # Production build
npm run prototype:preview       # Preview production build

# theia Backend (requires manual rebuild)
cd theia-app
npm run theia:build            # Build theia
npm run theia:watch            # Watch mode
npm run theia:start            # Start server

Rebuilding theia After Changes

If you modify theia source files (branding, extensions):

cd theia-app/src/browser
npx tsc                                      # Compile TypeScript

cd ../..
npx webpack --config gen-webpack.config.js  # Rebuild bundle

npm start                                    # Restart theia

Type Checking

# V5 Frontend
npm run type-check

# theia
cd theia-app && npm run type-check

🐳 Development Modes

Coditect AI IDE supports multiple deployment modes for different development scenarios:

Mode	Best For	terminal	Git Integration
Container-Only	Production, Cloud (GKE)	Container OS (Debian)	Manual setup required
Volume Mount	Local development	Container + Host files	Host config (automatic)
Remote SSH (Future)	Remote dev servers	Remote machine	Native on remote
Native Desktop	Single-user local	Host OS native	Native

Quick Start by Mode

Production Mode (Container-Only)

# Build Docker image
docker build -f deployment/dockerfile.local-test -t coditect-combined:prod .

# Run container
docker run -d -p 8080:80 --name coditect-prod coditect-combined:prod

# Access:
# - V5 Frontend: http://localhost:8080/
# - theia IDE: http://localhost:8080/theia/

Git Setup:

# Enter container
docker exec -it coditect-prod bash

# Configure git
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Local Development Mode (Volume Mount)

Windows (PowerShell):

docker run -d `
  -p 8080:80 `
  -v C:\Users\YourUser\Projects:/workspace `
  -v C:\Users\YourUser\.gitconfig:/root/.gitconfig:ro `
  -v C:\Users\YourUser\.ssh:/root/.ssh:ro `
  --name coditect-dev `
  coditect-combined:test

Mac/Linux (Bash):

docker run -d \
  -p 8080:80 \
  -v ~/projects:/workspace \
  -v ~/.gitconfig:/root/.gitconfig:ro \
  -v ~/.ssh:/root/.ssh:ro \
  --name coditect-dev \
  coditect-combined:test

Benefits:

✅ Edit files on your machine
✅ Git works automatically (uses host config)
✅ Files persist after container restart
✅ Fast development iteration

terminal & workspace Connectivity

Where does the theia terminal connect?

Container-Only: terminal runs inside Docker container (Debian Linux)
- Isolated from host system
- Complete security isolation
- Best for production/multi-tenant
Volume Mount: terminal runs in container but accesses host files
- Edit local files while using container runtime
- Git automatically uses host SSH keys
- Best for local development
Remote SSH (Future): terminal connects to remote machine via SSH
- Access powerful remote dev servers
- Run commands on production-like environments
- Requires theia SSH extension
Native Desktop: terminal runs on host OS (Windows/Mac/Linux)
- Direct OS integration
- Best for single-user local installs

Documentation

For detailed configuration, troubleshooting, and platform-specific instructions:

📘 User Guide: docs/01-getting-started/development-modes.md
🔧 Technical Reference: docs/01-getting-started/docker-volume-configuration.md
📋 Architecture Decision: docs/07-adr/adr-025-terminal-workspace-connectivity-options.md
🎭 theia Integration: docs/V5-THEIA-WRAPPER-architecture.md

📚 Documentation

Essential Reading

quickstart.md - Get started in 5 minutes
CLAUDE.md - Instructions for Claude Code
docs/DEFINITIVE-V5-architecture.md - Complete V5 design
docs/apple-quality-design-system.md - Design principles
theia-app/coditect-branding-solution.md - Branding implementation

Documentation Index

Architecture: docs/02-architecture/ - SDD, TDD, system design
Infrastructure: docs/03-infrastructure/ - GCP, FoundationDB, deployment
Security: docs/04-security/ - Security hardening plans
ADRs: docs/07-adr/ - Architecture Decision Records (ADR-001 to ADR-024)
V4 Reference: docs/08-v4-reference/ - V4 patterns (reference only)
Execution Plans: docs/10-execution-plans/ - Deployment tracking

Full documentation index: docs/DOCUMENTATION-index.md

🏗️ Architecture

Technology Stack

Layer	Technology	Version	Purpose
Frontend	React	18.3	UI framework
	TypeScript	5.3	Type safety
	Vite	5.4	Dev server & build
	Chakra UI	2.8	Component library
IDE	Eclipse theia	1.65	IDE framework
	Monaco editor	0.45	Code editor
	xterm.js	5.3	terminal
Backend	Rust (Actix-web)	Latest	API server
	FoundationDB	7.1+	Database
llm	LM Studio	Latest	Local llm inference
	Claude Code	Latest	AI assistance
State	Zustand	4.4	State management

Infrastructure (GCP)

Project: serene-voltage-464305-n2

Component	Status	Details
GKE Cluster	✅ Live	`codi-poc-e2-cluster` (us-central1-a)
FoundationDB	✅ Live	3-node StatefulSet at `10.128.0.8:4500`
Domain/SSL	✅ Active	`coditect.ai` (Google-managed cert)
Container Registry	✅ Ready	`gcr.io/serene-voltage-464305-n2`
CI/CD	✅ Ready	Cloud Build pipelines

🤖 llm Workflows

Supported Modes

Single Mode - One llm at a time
Parallel Mode - Side-by-side comparison
Sequential Mode - Chained processing (LM Studio → Claude)
Consensus Mode - Synthesized best answer from multiple llms

Recommended Models (LM Studio)

For AMD Ryzen AI Max+ 395 (128GB RAM):

Model	Size	RAM	Best For
Meta Llama 3.3 70B	Q4_K_M	~40GB	General coding, reasoning
Qwen2.5 72B	Q4_K_M	~40GB	Multilingual, math
DeepSeek-Coder-V2	Q4_K_M	~40GB	Code generation
Mixtral 8x22B	Q4_K_M	~35GB	Fast inference, MoE

🔐 Security

JWT Authentication - Secure session management
RBAC - Role-based access control
Audit Logging - Comprehensive event tracking
Local-First - No data leaves your machine (except optional cloud providers)
GDPR/SOC2 Ready - Compliance-ready architecture

📊 Current Status

Completed Features ✅

Development (Local):

✅ Coditect AI branding in theia AI Chat
✅ Custom robot logo and agent instructions
✅ V5 Frontend wrapper with 28 pages
✅ Apple-quality design system (500+ tokens)
✅ Mobile-first design (56px touch targets)
✅ Startup/shutdown scripts
✅ Two-service architecture working (ports 5173 + 3000)

Deployment (GCP):

✅ V5 Frontend production build (dist/ folder ready)
✅ Combined deployment architecture designed
✅ 9 deployment files created (Dockerfiles, configs, manifests)
✅ Complete documentation (architecture, guides, troubleshooting)
✅ GKE infrastructure ready (codi-poc-e2-cluster)
✅ FoundationDB ready (3-node StatefulSet)
✅ Domain/SSL configured (coditect.ai)

In Progress 🔄

⏸️ Docker Installation: Need Docker client for local testing
🔄 Local Docker Build Test: Test dockerfile.local-test (~27 min build)
🔄 Cloud Build Deployment: Deploy to GCP after local test succeeds
🔄 GKE Deployment: Deploy to Kubernetes cluster
🔄 WebSocket integration: Test theia terminal in production
🔄 Agent system implementation: Custom agents for code generation

Roadmap 🚧

🚧 Auth Backend: JWT + FoundationDB sessions (Phase 3)
🚧 WebSocket Sidecar: Real-time communication layer (Phase 4)
🚧 Pod auto-provisioning: User workspace isolation (Phase 5)
🚧 Full Integration: End-to-end testing (Phase 6)
🚧 Blue-green rollout: Zero-downtime deployment (Phase 7)
🚧 Production monitoring: Prometheus + Grafana dashboards

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'feat: Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

This project is licensed under the Eclipse Public License 2.0 (EPL-2.0).

Eclipse theia is EPL-2.0 licensed, which allows free commercial use without licensing fees.

See LICENSE for details.

🔗 Links

GitHub: https://github.com/coditect-ai/Coditect-v5-multiple-llm-IDE
Website: https://coditect.ai
Documentation: https://coditect.ai/docs
Issues: https://github.com/coditect-ai/Coditect-v5-multiple-llm-IDE/issues

📞 Support

Discord: Join our community
Email: support@coditect.ai
Documentation: See docs/ folder

🎉 Acknowledgments

Eclipse theia Team - Amazing IDE framework
Anthropic - Claude Code and MCP protocol
LM Studio - Local llm inference
Contributors - Everyone who helped build this

Made with ❤️ by the Coditect AI Team

Last Updated: 2025-10-12 | Status: Deployment architecture ready, awaiting Docker installation

🧪 Testing Infrastructure​

📐 Architecture Evolution (2025-10-27)​

🚀 Quick Start​

🧪 Testing & Quality Assurance​

📊 Project Status​

Latest Updates (2025-10-28)​

Previous Updates (2025-10-08)​

🤖 Claude Code Configuration (READ FIRST!)​

🎯 Overview​

Two-Service Architecture​

🎨 Key Features​

theia Backend (Port 3000)​

V5 Frontend Wrapper (Port 5173)​

Multi-llm Support​

Agent System​

🚀 Deployment Status​

Production Deployment (GCP)​

🧪 Deployment & Testing Infrastructure​

Overview​

Testing Infrastructure​

Test Scripts​

Deployment Files​

Critical Configuration Files​

Issue Tracking​

Quick Testing Workflow​

Test Demonstration​

🔧 Socket.IO Investigation & Troubleshooting​

Problem Statement​

Investigation Findings​

Comprehensive Documentation​

Quick Testing Workflow​

Next Steps​

Related Files​

🔍 Deployment Archeology - Finding Previous Successful Builds​

Quick Process​

Real Example: Combined Service Recovery (Oct 18, 2025)​

Automation Script​

Common Gotchas​

See Also​

📁 Project Structure​

🚀 Getting Started​

Prerequisites​

Installation​

Running the Application​

Option 1: Use Convenience Scripts (Recommended)​

Option 2: Manual Start​

Accessing the IDE​

🛠️ Development​

Build Commands​

Rebuilding theia After Changes​

Type Checking​

🐳 Development Modes​

Quick Start by Mode​

Production Mode (Container-Only)​

Local Development Mode (Volume Mount)​

terminal & workspace Connectivity​

Documentation​

📚 Documentation​

Essential Reading​

Documentation Index​

🏗️ Architecture​

Technology Stack​

Infrastructure (GCP)​

🤖 llm Workflows​

Supported Modes​

Recommended Models (LM Studio)​

🔐 Security​

📊 Current Status​

Completed Features ✅​

In Progress 🔄​

Roadmap 🚧​

🤝 Contributing​

Development Workflow​

📝 License​

🔗 Links​

📞 Support​

🎉 Acknowledgments​

🧪 Testing Infrastructure

📐 Architecture Evolution (2025-10-27)

🚀 Quick Start

🧪 Testing & Quality Assurance

📊 Project Status

Latest Updates (2025-10-28)

Previous Updates (2025-10-08)

🤖 Claude Code Configuration (READ FIRST!)

🎯 Overview

Two-Service Architecture

🎨 Key Features

theia Backend (Port 3000)

V5 Frontend Wrapper (Port 5173)

Multi-llm Support

Agent System

🚀 Deployment Status

Production Deployment (GCP)

🧪 Deployment & Testing Infrastructure

Overview

Testing Infrastructure

Test Scripts

Deployment Files

Critical Configuration Files

Issue Tracking

Quick Testing Workflow

Test Demonstration

🔧 Socket.IO Investigation & Troubleshooting

Problem Statement

Investigation Findings

Comprehensive Documentation

Quick Testing Workflow

Next Steps

Related Files

🔍 Deployment Archeology - Finding Previous Successful Builds

Quick Process

Real Example: Combined Service Recovery (Oct 18, 2025)

Automation Script

Common Gotchas

See Also

📁 Project Structure

🚀 Getting Started

Prerequisites

Installation

Running the Application

Option 1: Use Convenience Scripts (Recommended)

Option 2: Manual Start

Accessing the IDE

🛠️ Development

Build Commands

Rebuilding theia After Changes

Type Checking

🐳 Development Modes

Quick Start by Mode

Production Mode (Container-Only)

Local Development Mode (Volume Mount)

terminal & workspace Connectivity

Documentation

📚 Documentation

Essential Reading

Documentation Index

🏗️ Architecture

Technology Stack

Infrastructure (GCP)

🤖 llm Workflows

Supported Modes

Recommended Models (LM Studio)

🔐 Security

📊 Current Status

Completed Features ✅

In Progress 🔄

Roadmap 🚧

🤝 Contributing

Development Workflow

📝 License

🔗 Links

📞 Support

🎉 Acknowledgments