CODITECT Development Studio - Unified Persistent Architecture v2.0
Version: 2.0.0
Date: 2026-01-31
Status: Draft
Changes: Single persistent sandbox, multi-LLM coordination, GCS primary storage, SQLite session databases
Architecture Changes Summary
| Aspect | v1.0 (Previous) | v2.0 (Revised) |
|---|---|---|
| Sandbox Model | Ephemeral, per-LLM | Persistent, unified |
| Compute | 4 separate sandboxes | 1 shared workspace |
| Storage Primary | R2 | GCS (with R2 mirror) |
| Session State | Durable Objects only | SQLite + JSONL |
| LLM Coordination | External routing | In-sandbox orchestrator |
| Cost Model | $4.20/user @ 1K | $6.50/user @ 1K |
Revised System Architecture
┌─────────────────────────────────────────────────────────────────────────────────┐
│ CLIENT LAYER (Browser) │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ CODITECT Development Studio UI │ │
│ │ ┌──────────────┐ ┌────────────────────────────────────────────────┐ │ │
│ │ │ Chat Panel │ │ Visualization Panel │ │ │
│ │ │ │ │ ┌────────────┐ ┌────────────┐ ┌──────────┐ │ │ │
│ │ │ Multi-Agent │ │ │ Session │ │ Code │ │ Agent │ │ │ │
│ │ │ Chat (All │ │ │ Timeline │ │ Editor │ │ Status │ │ │ │
│ │ │ LLMs) │ │ └────────────┘ └────────────┘ └──────────┘ │ │ │
│ │ │ │ │ │ │ │
│ │ │ ┌────────┐ │ │ Agent Activity: │ │ │
│ │ │ │Claude │ │ │ ● Claude (editing) ○ Gemini (waiting) │ │ │
│ │ │ │Gemini │ │ │ ○ Kimi (idle) ○ Codex (indexing) │ │ │
│ │ │ │Kimi │ │ │ │ │ │
│ │ │ │Codex │ │ │ │ │ │
│ │ │ └────────┘ │ │ │ │ │
│ │ └──────────────┘ └─────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────┬──────────────────────────────────────────────────────┘
│ WebSocket / HTTPS (Real-time sync)
┌──────────────────────────▼──────────────────────────────────────────────────────┐
│ EDGE LAYER (Cloudflare) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ CDN │ │ WAF │ │ Workers │ │ Durable Objects │ │
│ │ (Cache) │ │ (Security) │ │ (API) │ │ (Session Coordination │ │
│ │ │ │ │ │ Gateway │ │ & Lock Management) │ │
│ └─────────────┘ └─────────────┘ └──────┬──────┘ └─────────────────────────┘ │
└───────────────────────────────────────────┼──────────────────────────────────────┘
│
┌───────────────────────────────────────────┼──────────────────────────────────────┐
│ SERVICE LAYER │ │
│ ┌────────────────────────────────────────▼────────────────────────────────┐ │
│ │ CODITECT-CORE Orchestrator │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ │
│ │ │ Auth │ │ Tenant │ │ Agent │ │ Session │ │ Workspace │ │ │
│ │ │ Service │ │ Resolver │ │Scheduler │ │ State │ │ Manager │ │ │
│ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └──────┬───────┘ │ │
│ │ └─────────────┴─────────────┴─────────────┴─────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ LLM Provider APIs (External) │ │ │
│ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │
│ │ │ │ Anthropic│ │ Google │ │ Moonshot │ │ OpenAI │ │ │ │
│ │ │ │ Claude │ │ Gemini │ │ Kimi │ │ Codex │ │ │ │
│ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────┬──────────────────────────────────────┘
│
┌───────────────────────────────────────────┼──────────────────────────────────────┐
│ PERSISTENT COMPUTE LAYER │
│ ┌────────────────────────────────────────▼────────────────────────────────┐ │
│ │ UNIFIED PERSISTENT WORKSPACE │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ CODITECT Agent Orchestrator │ │ │
│ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │
│ │ │ │ Agent │ │ Agent │ │ Agent │ │ │ │
│ │ │ │ Claude │ │ Gemini │ │ Kimi │ │ │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ │ │ State: │ │ State: │ │ State: │ │ │ │
│ │ │ │ editing │ │ waiting │ │ analyzing │ │ │ │
│ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │
│ │ │ │ │ │
│ │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │
│ │ │ │ Shared Context Manager │ │ │ │
│ │ │ │ • Active file locks │ │ │ │
│ │ │ │ • Agent task queue │ │ │ │
│ │ │ │ • Cross-agent message bus │ │ │ │
│ │ │ └──────────────────────────────────────────────────────────────┘ │ │ │
│ │ └─────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ SQLITE DATABASE CLUSTER │ │ │
│ │ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │ │
│ │ │ │ sessions.db │ │ messages.db │ │ artifacts.db │ │ │ │
│ │ │ │ ───────────── │ │ ───────────── │ │ ───────────── │ │ │ │
│ │ │ │ session_id │ │ message_id │ │ artifact_id │ │ │ │
│ │ │ │ agent_states │ │ session_id FK │ │ session_id FK │ │ │ │
│ │ │ │ context_json │ │ agent_id │ │ file_path │ │ │ │
│ │ │ │ checkpoint_ref │ │ content │ │ content_hash │ │ │ │
│ │ │ │ created_at │ │ tokens │ │ vector_embed │ │ │ │
│ │ │ └────────────────┘ └────────────────┘ └────────────────┘ │ │ │
│ │ │ │ │ │
│ │ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │ │
│ │ │ │ parsed_sessions│ │ agent_metrics │ │ workspace_idx │ │ │ │
│ │ │ │ ───────────── │ │ ───────────── │ │ ───────────── │ │ │ │
│ │ │ │ session_id │ │ agent_id │ │ file_path │ │ │ │
│ │ │ │ parsed_content │ │ task_count │ │ last_modified │ │ │ │
│ │ │ │ entity_extrac │ │ success_rate │ │ agent_locks │ │ │ │
│ │ │ │ sentiment │ │ latency_avg │ │ git_status │ │ │ │
│ │ │ └────────────────┘ └────────────────┘ └────────────────┘ │ │ │
│ │ └─────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ SESSION JSONL ARCHIVE │ │ │
│ │ │ /workspace/.coditect/sessions/ │ │ │
│ │ │ ├── session_2026-01-31_abc123.jsonl │ │ │
│ │ │ │ {"timestamp": "...", "agent": "claude", "event": "file_edit", │ │ │
│ │ │ │ "file": "src/main.ts", "diff": "..."} │ │ │
│ │ │ │ {"timestamp": "...", "agent": "gemini", "event": "analysis", │ │ │
│ │ │ │ "result": "..."} │ │ │
│ │ │ └── session_2026-01-31_def456.jsonl │ │ │
│ │ └─────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ WORKSPACE FILESYSTEM │ │ │
│ │ │ /home/developer/ │ │ │
│ │ │ ├── projects/ ← Mounted from GCS (persistent) │ │ │
│ │ │ │ └── current-project/ │ │ │
│ │ │ │ ├── .git/ │ │ │
│ │ │ │ ├── src/ │ │ │
│ │ │ │ └── .coditect/ │ │ │
│ │ │ │ ├── session.jsonl ← Real-time session log │ │ │
│ │ │ │ ├── checkpoints/ ← Git commits │ │ │
│ │ │ │ └── vector_store/ ← Embeddings cache │ │ │
│ │ │ ├── .coditect/ │ │ │
│ │ │ │ ├── databases/ ← SQLite files (6 databases) │ │ │
│ │ │ │ │ ├── sessions.db │ │ │
│ │ │ │ │ ├── messages.db │ │ │
│ │ │ │ │ ├── artifacts.db │ │ │
│ │ │ │ │ ├── parsed_sessions.db │ │ │
│ │ │ │ │ ├── agent_metrics.db │ │ │
│ │ │ │ │ └── workspace_idx.db │ │ │
│ │ │ │ └── config/ │ │ │
│ │ │ └── .cache/ ← Tool caches (npm, pip, cargo) │ │ │
│ │ └─────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────┬──────────────────────────────────────┘
│ gcsfuse mount (bidirectional sync)
┌───────────────────────────────────────────▼──────────────────────────────────────┐
│ GCS PRIMARY STORAGE (Persistent) │
│ │
│ Bucket: coditect-workspaces-{org-id} │
│ │ │
│ ├── organizations/{org-id}/ │
│ │ └── teams/{team-id}/ │
│ │ └── users/{user-id}/ │
│ │ ├── workspaces/{workspace-id}/ │
│ │ │ ├── projects/ ← Code repositories │
│ │ │ ├── databases/ ← SQLite files (automated backup) │
│ │ │ │ ├── sessions.db ← ~500MB per 1000 sessions │
│ │ │ │ ├── messages.db ← ~2GB per 1000 sessions │
│ │ │ │ ├── artifacts.db ← ~1GB per 1000 sessions │
│ │ │ │ ├── parsed_sessions.db ← ~5GB per 1000 sessions │
│ │ │ │ ├── agent_metrics.db ← ~100MB per 1000 sessions │
│ │ │ │ └── workspace_idx.db ← ~200MB per 1000 sessions │
│ │ │ ├── sessions/ ← JSONL archives │
│ │ │ │ └── 2026/01/31/*.jsonl ← ~10MB per session │
│ │ │ ├── vector-store/ ← Embeddings for RAG │
│ │ │ └── checkpoints/ ← Git bundles │
│ │ │ │
│ │ └── shared/ ← Team templates, assets │
│ │ │
│ └── system/ ← Global caches, models │
│ └── embeddings/ ← Pre-computed embeddings │
│ │
│ [R2 MIRROR - Cross-region replication for latency optimization] │
│ Bucket: coditect-mirror-{region} │
│ │ │
│ └── hot-cache/ ← Frequently accessed files │
│ │
└───────────────────────────────────────────────────────────────────────────────────┘
Key Architectural Decisions v2.0
1. Unified Persistent Workspace (vs Ephemeral Sandboxes)
| Aspect | v1.0 Ephemeral | v2.0 Persistent |
|---|---|---|
| Lifetime | 30-min idle timeout | 8-hour max (renewable) |
| Cold Start | 5-10 seconds | 0 (always warm) |
| State | Lost on termination | Preserved in GCS + SQLite |
| Multi-LLM | External routing | In-container coordination |
| Cost/Hour | $0.12 (2 vCPU) | $0.08 (sustained use) |
| Storage | R2 mount | GCS native + local SQLite |
2. SQLite Database Cluster
Six specialized databases for different data types:
-- sessions.db: Active session state
CREATE TABLE active_sessions (
session_id TEXT PRIMARY KEY,
workspace_id TEXT NOT NULL,
agent_states JSON, -- {"claude": "editing", "gemini": "waiting"}
current_task JSON,
file_locks JSON, -- ["src/main.ts", "README.md"]
context_snapshot JSON,
last_activity TIMESTAMP,
checkpoint_ref TEXT
);
-- messages.db: All agent communications
CREATE TABLE agent_messages (
message_id TEXT PRIMARY KEY,
session_id TEXT,
agent_id TEXT, -- claude, gemini, kimi, codex
message_type TEXT, -- chat, tool_call, system
content TEXT,
tokens_input INT,
tokens_output INT,
latency_ms INT,
cost DECIMAL(10,6),
timestamp TIMESTAMP,
parent_message_id TEXT,
FOREIGN KEY (session_id) REFERENCES active_sessions(session_id)
);
-- artifacts.db: Generated files and outputs
CREATE TABLE artifacts (
artifact_id TEXT PRIMARY KEY,
session_id TEXT,
agent_id TEXT,
artifact_type TEXT, -- code, document, image, data
file_path TEXT,
content_hash TEXT, -- For deduplication
vector_embedding BLOB, -- For semantic search
created_at TIMESTAMP,
git_commit_ref TEXT
);
-- parsed_sessions.db: Extracted session insights
CREATE TABLE parsed_sessions (
session_id TEXT PRIMARY KEY,
parsed_content JSON, -- NLP-extracted entities
entities JSON, -- People, orgs, technologies
sentiment_score FLOAT, -- -1 to 1
topics JSON, -- Extracted topics
code_changes JSON, -- Summary of edits
decisions JSON, -- Key decisions made
created_at TIMESTAMP
);
-- agent_metrics.db: Performance tracking
CREATE TABLE agent_metrics (
metric_id INTEGER PRIMARY KEY,
agent_id TEXT,
session_id TEXT,
task_type TEXT,
success BOOLEAN,
latency_ms INT,
tokens_used INT,
cost DECIMAL(10,6),
timestamp TIMESTAMP
);
-- workspace_idx.db: File index and search
CREATE TABLE workspace_files (
file_id TEXT PRIMARY KEY,
session_id TEXT,
file_path TEXT,
content_hash TEXT,
last_modified TIMESTAMP,
vector_embedding BLOB, -- For semantic code search
language TEXT,
agent_lock TEXT, -- Which agent has lock
git_status TEXT -- modified, staged, clean
);
3. Session JSONL Format
Append-only log for complete audit trail:
{"ts": "2026-01-31T14:23:01Z", "type": "session_start", "agent": "system", "payload": {"workspace_id": "ws_abc123", "agents": ["claude", "gemini"]}}
{"ts": "2026-01-31T14:23:15Z", "type": "agent_init", "agent": "claude", "payload": {"model": "claude-3-opus-20240229", "context_window": 200000}}
{"ts": "2026-01-31T14:23:16Z", "type": "agent_init", "agent": "gemini", "payload": {"model": "gemini-1.5-pro", "context_window": 1000000}}
{"ts": "2026-01-31T14:24:30Z", "type": "user_message", "agent": "user", "payload": {"content": "Refactor the auth module", "target_agents": ["claude", "gemini"]}}
{"ts": "2026-01-31T14:24:31Z", "type": "file_lock_acquire", "agent": "claude", "payload": {"file": "src/auth.ts", "lock_type": "exclusive"}}
{"ts": "2026-01-31T14:24:45Z", "type": "llm_request", "agent": "claude", "payload": {"prompt_tokens": 1500, "estimated_cost": 0.045}}
{"ts": "2026-01-31T14:25:02Z", "type": "llm_response", "agent": "claude", "payload": {"completion_tokens": 800, "actual_cost": 0.024, "latency_ms": 17000}}
{"ts": "2026-01-31T14:25:03Z", "type": "file_edit", "agent": "claude", "payload": {"file": "src/auth.ts", "diff_hash": "a1b2c3", "lines_changed": 45}}
{"ts": "2026-01-31T14:25:10Z", "type": "tool_call", "agent": "claude", "payload": {"tool": "git_diff", "args": ["src/auth.ts"]}}
{"ts": "2026-01-31T14:25:11Z", "type": "tool_result", "agent": "system", "payload": {"stdout": "+45 -23 lines changed", "exit_code": 0}}
{"ts": "2026-01-31T14:25:30Z", "type": "file_lock_release", "agent": "claude", "payload": {"file": "src/auth.ts"}}
{"ts": "2026-01-31T14:25:31Z", "type": "agent_complete", "agent": "claude", "payload": {"summary": "Refactored auth module with improved error handling"}}
{"ts": "2026-01-31T14:25:32Z", "type": "sync_to_gcs", "agent": "system", "payload": {"files_synced": 3, "bytes_synced": 12400}}
4. Multi-Agent Coordination Protocol
// Agent coordination within the persistent workspace
interface AgentCoordinator {
// Task queue with priorities
taskQueue: PriorityQueue<AgentTask>;
// File locking mechanism
lockManager: {
acquire(file: string, agent: AgentId, type: 'shared' | 'exclusive'): Promise<boolean>;
release(file: string, agent: AgentId): void;
query(file: string): LockState;
};
// Message bus for cross-agent communication
messageBus: {
publish(agent: AgentId, message: AgentMessage): void;
subscribe(agent: AgentId, handler: MessageHandler): void;
};
// Context sharing
sharedContext: {
get(key: string): any;
set(key: string, value: any, agent: AgentId): void;
subscribe(key: string, handler: ContextHandler): void;
};
}
// Example coordination flow
async function coordinateRefactoring(
targetFiles: string[],
requirements: string
) {
// 1. Planning phase - all agents contribute
const plans = await Promise.all([
claudeAgent.plan(requirements, targetFiles),
geminiAgent.plan(requirements, targetFiles),
kimiAgent.plan(requirements, targetFiles)
]);
// 2. Merge plans
const mergedPlan = await mergePlans(plans);
// 3. Execute with file locking
for (const task of mergedPlan.tasks) {
const lock = await coordinator.lockManager.acquire(
task.file,
task.assignedAgent,
'exclusive'
);
if (lock) {
await executeTask(task);
coordinator.lockManager.release(task.file, task.assignedAgent);
// 4. Notify other agents
coordinator.messageBus.publish('system', {
type: 'file_modified',
file: task.file,
agent: task.assignedAgent
});
}
}
// 5. Sync to GCS
await syncToGCS();
}
Data Flow: Session Persistence
Storage Specifications
GCS Bucket Structure
coditect-workspaces-{org-id}
│
├── organizations/{org-id}/
│ └── teams/{team-id}/
│ └── users/{user-id}/
│ ├── workspaces/
│ │ └── {workspace-id}/
│ │ ├──
## Related Documents
- [ADR-XXX-unified-persistent-architecture.md](./ADR-XXX-unified-persistent-architecture.md) - Architecture decision
- [CODITECT-THIN-CLIENT-SDD-v2.md](./CODITECT-THIN-CLIENT-SDD-v2.md) - System design
- [CODITECT-THIN-CLIENT-TDD-v2.md](./CODITECT-THIN-CLIENT-TDD-v2.md) - Technical design
- [CODITECT-REVISED-ECONOMIC-MODEL.md](./CODITECT-REVISED-ECONOMIC-MODEL.md) - Cost analysis
---
**Document Status:** Complete
**Last Updated:** 2026-01-31
**Version:** 2.0.0