CODITECT Development Studio - System Design Document (SDD) v2.0

Version: 2.0.0
Date: 2026-01-31
Status: Draft
Changes: Unified persistent workspace, GCS primary storage, SQLite cluster, in-workspace multi-LLM coordination

1. Executive Summary

1.1 Purpose

This document describes the system design for the CODITECT Development Studio v2.0 - a browser-based thin client with unified persistent workspaces. Unlike v1.0's ephemeral sandboxes, v2.0 uses single persistent containers where multiple LLM agents coordinate on shared codebases, with all state persisted in GCS and SQLite.

1.2 Key Changes from v1.0

Aspect	v1.0	v2.0
Compute	Ephemeral sandboxes (30-min timeout)	Persistent workspaces (8-hour renewable)
LLM Model	External routing, isolated	In-workspace coordination, shared
Storage Primary	R2	GCS (with R2 mirror)
Session State	Durable Objects only	SQLite cluster + JSONL
Cold Start	5-10 seconds	0 seconds
Cost	$4.20/user @ 1K	$6.50/user @ 1K

2. System Overview

2.1 High-Level Architecture

┌─────────────────────────────────────────────────────────────────────────────────┐
│                              CLIENT LAYER (Browser)                              │
│                    ┌─────────────────────────────────────┐                      │
│                    │   CODITECT Development Studio       │                      │
│                    │   ┌──────────┐  ┌────────────────┐  │                      │
│                    │   │  Multi-  │  │  Workspace     │  │                      │
│                    │   │  Agent   │  │  Timeline +    │  │                      │
│                    │   │  Chat    │  │  File Explorer │  │                      │
│                    │   └──────────┘  └────────────────┘  │                      │
│                    └─────────────────────────────────────┘                      │
└──────────────────────────┬──────────────────────────────────────────────────────┘
                           │ WebSocket / HTTPS
┌──────────────────────────▼──────────────────────────────────────────────────────┐
│                           EDGE LAYER (Cloudflare)                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │     CDN     │  │     WAF     │  │   Workers   │  │    Durable Objects      │  │
│  │             │  │             │  │   (API)     │  │  (Workspace Registry)   │  │
│  └─────────────┘  └─────────────┘  └──────┬──────┘  └─────────────────────────┘  │
└───────────────────────────────────────────┼──────────────────────────────────────┘
                                            │
┌───────────────────────────────────────────┼──────────────────────────────────────┐
│                      PERSISTENT COMPUTE LAYER                                    │
│  ┌────────────────────────────────────────▼────────────────────────────────┐    │
│  │                     UNIFIED PERSISTENT WORKSPACE                           │    │
│  │                                                                            │    │
│  │  ┌─────────────────────────────────────────────────────────────────────┐  │    │
│  │  │                    AGENT ORCHESTRATOR (in-workspace)                 │  │    │
│  │  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐            │  │    │
│  │  │  │  Claude  │  │  Gemini  │  │   Kimi   │  │  Codex   │            │  │    │
│  │  │  │  Agent   │  │  Agent   │  │  Agent   │  │  Agent   │            │  │    │
│  │  │  │          │  │          │  │          │  │          │            │  │    │
│  │  │  │  State:  │  │  State:  │  │  State:  │  │  State:  │            │  │    │
│  │  │  │ editing  │  │ waiting  │  │ analyzing│  │ indexing │            │  │    │
│  │  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘            │  │    │
│  │  │                                                                    │  │    │
│  │  │  Shared: task queue, file locks, message bus, context              │  │    │
│  │  └─────────────────────────────────────────────────────────────────────┘  │    │
│  │                                                                            │    │
│  │  ┌─────────────────────────────────────────────────────────────────────┐  │    │
│  │  │                    SQLITE DATABASE CLUSTER                           │  │    │
│  │  │  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐                │  │    │
│  │  │  │  sessions.db │ │  messages.db │ │  artifacts.db│                │  │    │
│  │  │  │  (500MB)     │ │  (2GB)       │ │  (1GB)       │                │  │    │
│  │  │  ├──────────────┤ ├──────────────┤ ├──────────────┤                │  │    │
│  │  │  │  session_id  │ │  message_id  │ │  artifact_id │                │  │    │
│  │  │  │  agent_states│ │  agent_id    │ │  file_path   │                │  │    │
│  │  │  │  file_locks  │ │  content     │ │  vector_embed│                │  │    │
│  │  │  └──────────────┘ └──────────────┘ └──────────────┘                │  │    │
│  │  │  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐                │  │    │
│  │  │  │parsed_session│ │agent_metrics │ │workspace_idx │                │  │    │
│  │  │  │  (5GB)       │ │  (100MB)     │ │  (200MB)     │                │  │    │
│  │  │  └──────────────┘ └──────────────┘ └──────────────┘                │  │    │
│  │  └─────────────────────────────────────────────────────────────────────┘  │    │
│  │                                                                            │    │
│  │  ┌─────────────────────────────────────────────────────────────────────┐  │    │
│  │  │                    PERSISTENT STORAGE                                │  │    │
│  │  │  /home/developer/                                                    │  │    │
│  │  │  ├── projects/           ← GCS FUSE mount (persistent)              │  │    │
│  │  │  │   └── .coditect/                                                   │  │    │
│  │  │  │       ├── session.jsonl   ← Append-only event log                 │  │    │
│  │  │  │       ├── databases/      ← SQLite files                          │  │    │
│  │  │  │       └── checkpoints/    ← Git commits                           │  │    │
│  │  │  └── .cache/              ← Tool caches                             │  │    │
│  │  └─────────────────────────────────────────────────────────────────────┘  │    │
│  │                                                                            │    │
│  └────────────────────────────────────────────────────────────────────────────┘    │
└───────────────────────────────────────────┬──────────────────────────────────────┘
                                            │ gcsfuse (bidirectional sync)
┌───────────────────────────────────────────▼──────────────────────────────────────┐
│                         GCS PRIMARY STORAGE                                      │
│  Bucket: coditect-workspaces-{org-id}                                            │
│  ├── organizations/{org-id}/teams/{team-id}/users/{user-id}/                     │
│  │   └── workspaces/{workspace-id}/                                               │
│  │       ├── projects/              ← Code repositories                           │
│  │       ├── databases/             ← SQLite files (~9GB per 1K users)           │
│  │       ├── sessions/              ← JSONL archives                              │
│  │       └── vector-store/          ← Embeddings                                  │
│  └── [R2 MIRROR - Cross-region hot cache]                                        │
└───────────────────────────────────────────────────────────────────────────────────┘

2.2 Core Design Principles

Principle	v1.0 Implementation	v2.0 Implementation
Thin Client	Browser UI, server compute	Same
Persistent State	R2 snapshots	GCS + SQLite real-time sync
Multi-Agent	External routing	In-workspace coordination
Zero Cold Start	N/A (5-10s start)	Always-warm workspaces
Data Durability	Eventual consistency	Strong consistency (WAL)
Audit Trail	Git checkpoints only	JSONL + Git dual trail

3. System Components

3.1 Thin Client (Browser)

Changes from v1.0:

Added Agent Activity Panel showing real-time status of all 4 LLMs
Added Workspace Timeline for session replay
Enhanced File Explorer with agent lock indicators

Key Modules:

Module	Changes
Chat Interface	Shows multi-agent conversations, agent attribution
Agent Panel	Real-time status: Claude (editing), Gemini (waiting), etc.
File Tree	Lock indicators showing which agent has which file
Timeline	Replay session history from SQLite + JSONL

3.2 CODITECT-CORE Orchestrator

New Responsibilities:

Workspace Lifecycle Management - Provision, schedule, hibernate persistent workspaces
GCS Integration - Mount coordination, sync monitoring
SQLite Backup Orchestration - Automated WAL archiving

API Changes:

// New endpoints for v2.0
POST   /api/v2/workspaces              // Create persistent workspace
GET    /api/v2/workspaces/:id/status   // Get workspace + agent states
POST   /api/v2/workspaces/:id/hibernate // Hibernate after 8h
POST   /api/v2/workspaces/:id/resume   // Resume from hibernation
POST   /api/v2/workspaces/:id/agents/:agent/execute  // Send task to specific agent
GET    /api/v2/workspaces/:id/agents   // Get all agent states
GET    /api/v2/workspaces/:id/timeline // Get session timeline from SQLite

3.3 Persistent Workspace Pool

Workspace Configuration:

Resource	Specification
Compute	2 vCPU, 4GB RAM (sustained)
Lifetime	8 hours (renewable), hibernate after idle
Storage	20GB local SSD + GCS mount
Databases	6 SQLite databases (~9GB @ 1K users)
Agents	Claude, Gemini, Kimi, Codex (all in-container)

Lifecycle States:

Creating → Active → [Renewable] → Hibernating → Hibernated → Resuming → Active
              ↓
         Terminated (user action or max 24h)

3.4 SQLite Database Cluster

Six Specialized Databases:

Database	Purpose	Size (@ 1K users)	Schema
sessions.db	Active session state, file locks	500 MB	session_id, agent_states JSON, file_locks JSON
messages.db	All agent communications	2 GB	message_id, agent_id, content, tokens, cost
artifacts.db	Generated files, embeddings	1 GB	artifact_id, file_path, vector_embedding
parsed_sessions.db	NLP-extracted insights	5 GB	entities, sentiment, topics, decisions
agent_metrics.db	Performance tracking	100 MB	task_type, success, latency, tokens
workspace_idx.db	File search index	200 MB	file_path, content_hash, vector_embedding, git_status

Synchronization Strategy:

WAL Mode: Write-Ahead Logging for durability
Sync to GCS: Every 30 seconds via FUSE
Backup: Hourly full snapshots, continuous WAL archiving

3.5 Session JSONL Archive

Format:

{"ts": "2026-01-31T14:23:01Z", "type": "session_start", "agent": "system", "payload": {"workspace_id": "ws_abc123"}}
{"ts": "2026-01-31T14:23:15Z", "type": "agent_init", "agent": "claude", "payload": {"model": "claude-3-opus-20240229"}}
{"ts": "2026-01-31T14:24:30Z", "type": "user_message", "agent": "user", "payload": {"content": "Refactor auth module"}}
{"ts": "2026-01-31T14:24:31Z", "type": "file_lock_acquire", "agent": "claude", "payload": {"file": "src/auth.ts", "type": "exclusive"}}
{"ts": "2026-01-31T14:25:02Z", "type": "llm_response", "agent": "claude", "payload": {"completion_tokens": 800, "cost": 0.024}}
{"ts": "2026-01-31T14:25:03Z", "type": "file_edit", "agent": "claude", "payload": {"file": "src/auth.ts", "lines_changed": 45}}

Usage:

Real-time append during session
Compressed and archived daily
Used for session replay and audit

3.6 Agent Coordination Protocol

In-Workspace Coordination:

interface AgentCoordinator {
  // Task distribution
  taskQueue: PriorityQueue<AgentTask>;
  
  // File locking
  lockManager: {
    acquire(file: string, agent: AgentId, type: 'shared' | 'exclusive'): Promise<boolean>;
    release(file: string, agent: AgentId): void;
    query(file: string): { locked: boolean; by?: AgentId; type?: LockType };
  };
  
  // Cross-agent messaging
  messageBus: EventEmitter<{
    'file_modified': { file: string; agent: AgentId; diff: string };
    'task_completed': { taskId: string; agent: AgentId; result: any };
    'agent_state_change': { agent: AgentId; from: State; to: State };
  }>;
  
  // Shared context
  sharedContext: Map<string, { value: any; updatedBy: AgentId; updatedAt: Date }>;
}

// Example: Collaborative refactoring
async function collaborativeRefactor(targetFiles: string[], requirements: string) {
  // All agents plan simultaneously
  const [claudePlan, geminiPlan] = await Promise.all([
    agents.claude.plan(requirements, targetFiles),
    agents.gemini.plan(requirements, targetFiles)
  ]);
  
  // Merge plans
  const mergedPlan = coordinator.mergePlans([claudePlan, geminiPlan]);
  
  // Execute with locking
  for (const task of mergedPlan.tasks) {
    const lock = await coordinator.lockManager.acquire(
      task.file, task.agent, 'exclusive'
    );
    
    if (lock) {
      await agents[task.agent].execute(task);
      await coordinator.lockManager.release(task.file, task.agent);
      
      // Notify other agents
      coordinator.messageBus.emit('file_modified', {
        file: task.file,
        agent: task.agent,
        diff: task.result.diff
      });
    }
  }
}

4. Data Flows

4.2 Multi-Agent Task Execution

4.3 Session Persistence & Recovery

5. Security Architecture

5.1 GCS Security

Layer	Implementation
Encryption at Rest	AES-256 (Google-managed)
Encryption in Transit	TLS 1.3
Access Control	IAM + Service Accounts per org
Bucket Policy	Org-scoped buckets, no cross-access
Audit Logging	Cloud Audit Logs → SIEM

5.2 SQLite Security

Measure	Implementation
Encryption	SQLCipher (AES-256) for sensitive databases
Access	Unix permissions, container-only access
Backup Encryption	GCS customer-managed encryption keys (CMEK)
WAL Security	WAL files encrypted before GCS sync

5.3 Agent Isolation

While agents share a workspace, they operate with:

Process isolation: Each agent in separate thread/process
File locking: Exclusive locks prevent concurrent edits
Resource quotas: Per-agent CPU/memory limits
Sandboxed execution: Tool calls run in isolated subprocesses

6. Storage Architecture

6.1 GCS Bucket Structure

coditect-workspaces-{org-id}
│
├── organizations/{org-id}/
│   └── teams/{team-id}/
│       └── users/{user-id}/
│           ├── workspaces/
│           │   └── {workspace-id}/
│           │       ├── projects/              # Code repositories
│           │       │   └── {project-name}/
│           │       │       ├── src/
│           │       │       ├── .git/         # Git repository
│           │       │       └── .coditect/
│           │       │           ├── session.jsonl
│           │       │           └── checkpoints/
│           │       │
│           │       ├── databases/            # SQLite files
│           │       │   ├── sessions.db       # ~500MB per 1K users
│           │       │   ├── messages.db       # ~2GB per 1K users
│           │       │   ├── artifacts.db      # ~1GB per 1K users
│           │       │   ├── parsed_sessions.db # ~5GB per 1K users
│           │       │   ├── agent_metrics.db  # ~100MB per 1K users
│           │       │   └── workspace_idx.db  # ~200MB per 1K users
│           │       │
│           │       ├── sessions/             # JSONL archives
│           │       │   └── 2026/
│           │       │       └── 01/
│           │       │           └── 31/
│           │       │               └── session_*.jsonl.gz
│           │       │
│           │       ├── vector-store/         # Embeddings
│           │       │   └── embeddings.parquet
│           │       │
│           │       └── backups/              # Automated backups
│           │           ├── daily/
│           │           └── hourly/
│           │
│           └── shared/                      # Team resources
│               └── templates/
│
└── system/                                  # Global resources
    └── embeddings/                          # Pre-computed embeddings

[R2 MIRROR]
coditect-mirror-{region}
└── hot-cache/                               # Frequently accessed files
    └── {workspace-id}/
        └── [recent 20% of GCS files]

6.2 Storage Tiers

Tier	Storage Class	Use Case	Retention
Hot	GCS Standard	Active workspaces, recent sessions	30 days
Warm	GCS Nearline	Old sessions, archived data	90 days
Cold	GCS Coldline	Historical JSONL, old backups	1 year
Cache	R2 Standard	Hot file cache	LRU eviction

7. Scalability & Performance

7.1 Scaling Strategy

Component	Scaling Approach
Workspaces	Horizontal pool, auto-hibernate idle
GCS	Automatic (serverless)
SQLite	Vertical per-workspace, shard by user
R2 Mirror	Automatic (serverless)
Durable Objects	Sharding by workspaceId

7.2 Performance Targets

Metric	Target	Measurement
Workspace start	< 30s	First container boot
Workspace resume	< 5s	From hibernation
Agent coordination	< 50ms	In-workspace message
SQLite query	< 10ms	Local database
GCS sync latency	< 1s	WAL flush to GCS
Session restoration	< 3s	Full state restore

8. Cost Model (v2.0)

8.1 Monthly Cost @ 1,000 Users

Category	Cost	% of Total
Persistent Compute	$4,200	65%
GCS Storage	$1,460	22%
Operations	$1,100	17%
R2 Mirror	$355	5%
LLM Providers	$323	5%
Edge Compute	$219	3%
TOTAL	$6,500	100%

8.2 Cost per User

Users	Monthly Cost	Cost/User
100	$650	$6.50
500	$2,800	$5.60
1,000	$6,500	$6.50
5,000	$28,000	$5.60
10,000	$72,000	$7.20

9. Migration from v1.0

9.1 Data Migration

Source (v1.0)	Destination (v2.0)	Method
R2 project files	GCS projects/	gsutil rsync
Durable Object state	SQLite sessions.db	Export → Import
Git backups	GCS + Git	Continue using

9.2 API Compatibility

v1.0 Endpoint	v2.0 Endpoint	Compatibility
POST /sessions	POST /workspaces	Breaking change
GET /sessions/:id	GET /workspaces/:id	Breaking change
POST /chat	POST /workspaces/:id/agents/:agent/execute	Breaking change

Migration Period: 30 days with dual-mode support

10. Appendix

10.1 Glossary Updates

Term	Definition
Persistent Workspace	Long-running container with GCS-mounted storage
Agent Coordinator	In-workspace service managing multi-LLM coordination
SQLite Cluster	Six specialized SQLite databases per workspace
Session JSONL	Append-only log of all workspace events
gcsfuse	FUSE filesystem for mounting GCS buckets
WAL	Write-Ahead Logging for SQLite durability

10.2 References

ADR-XXX: Unified Persistent Workspace Architecture (pending)
MOE-Agents C4 Architecture v2.0
CODITECT Economic Model v2.0
Google Cloud Storage Best Practices
SQLite WAL Mode Documentation

Document Owner: Platform Engineering Team
Version: 2.0.0
Last Updated: 2026-01-31

1. Executive Summary​

1.1 Purpose​

1.2 Key Changes from v1.0​

2. System Overview​

2.1 High-Level Architecture​

2.2 Core Design Principles​

3. System Components​

3.1 Thin Client (Browser)​

3.2 CODITECT-CORE Orchestrator​

3.3 Persistent Workspace Pool​

3.4 SQLite Database Cluster​

3.5 Session JSONL Archive​

3.6 Agent Coordination Protocol​

4. Data Flows​

4.1 User Login & Workspace Initialization​

4.2 Multi-Agent Task Execution​

4.3 Session Persistence & Recovery​

5. Security Architecture​

5.1 GCS Security​

5.2 SQLite Security​

5.3 Agent Isolation​

6. Storage Architecture​

6.1 GCS Bucket Structure​

6.2 Storage Tiers​

7. Scalability & Performance​

7.1 Scaling Strategy​

7.2 Performance Targets​

8. Cost Model (v2.0)​

8.1 Monthly Cost @ 1,000 Users​

8.2 Cost per User​

9. Migration from v1.0​

9.1 Data Migration​

9.2 API Compatibility​

10. Appendix​

10.1 Glossary Updates​

10.2 References​