CODITECT Development Studio - System Design Document (SDD)

Version: 1.0.0
Date: 2026-01-31
Status: Draft
Classification: Internal

1. Executive Summary

1.1 Purpose

This document describes the system design for the CODITECT Development Studio - a unified, multi-tenant web-based thin client that provides access to the CODITECT agent orchestration platform. The system enables organizations, teams, and individual users to interact with multiple LLM providers (Claude, Gemini, Codex, Kimi) through a browser-based interface.

1.2 Scope

In Scope: Browser-based thin client, real-time collaboration, multi-LLM orchestration, session management, project workspaces
Out of Scope: Native desktop applications, mobile apps (Phase 2), on-premises deployment (Phase 3)

1.3 Key Stakeholders

Role	Responsibility
Platform Engineering	CODITECT-CORE orchestrator, infrastructure
Frontend Team	Thin client UI/UX
DevOps	Deployment, monitoring, scaling
Security	Authentication, authorization, compliance

2. System Overview

2.1 High-Level Architecture

┌─────────────────────────────────────────────────────────────────────────────────┐
│                              CLIENT LAYER (Browser)                              │
│  ┌─────────────────────────────────────────────────────────────────────────┐    │
│  │                    CODITECT Development Studio UI                        │    │
│  │  ┌──────────────┐  ┌────────────────────────────────────────────────┐   │    │
│  │  │   Chat Panel │  │         Visualization Panel                     │   │    │
│  │  │  ┌────────┐  │  │  ┌────────────┐  ┌────────────┐  ┌──────────┐  │   │    │
│  │  │  │ Agent  │  │  │  │  Workflow  │  │  Pitch     │  │  Market  │  │   │    │
│  │  │  │ Chat   │  │  │  │  Diagram   │  │  Deck      │  │  Analysis│  │   │    │
│  │  │  └────────┘  │  │  └────────────┘  └────────────┘  └──────────┘  │   │    │
│  │  │  ┌────────┐  │  │                                                 │   │    │
│  │  │  │Session │  │  │  Tabs: lims | pitch-deck | dev-tools | agents  │   │    │
│  │  │  │History │  │  │                                                 │   │    │
│  │  │  └────────┘  │  └─────────────────────────────────────────────────┘   │    │
│  │  └──────────────┘                                                          │    │
│  └─────────────────────────────────────────────────────────────────────────┘    │
│         ▲                                                                       │
│         │ WebSocket / HTTPS                                                     │
└─────────┼───────────────────────────────────────────────────────────────────────┘
          │
┌─────────▼───────────────────────────────────────────────────────────────────────┐
│                           EDGE LAYER (Cloudflare)                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │     CDN     │  │     WAF     │  │   Workers   │  │    Durable Objects      │  │
│  │   (Cache)   │  │  (Security) │  │    (API)    │  │  (Session Coordination) │  │
│  └─────────────┘  └─────────────┘  └──────┬──────┘  └─────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────────┘
                                             │
┌────────────────────────────────────────────┼────────────────────────────────────┐
│                         SERVICE LAYER       │                                   │
│  ┌──────────────────────────────────────────▼────────────────────────────────┐  │
│  │                        CODITECT-CORE Orchestrator                          │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐  │  │
│  │  │   Auth   │ │  Tenant  │ │   LLM    │ │ Session  │ │     State        │  │  │
│  │  │  Service │ │ Resolver │ │  Router  │ │  Manager │ │   Manager        │  │  │
│  │  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────────┬─────────┘  │  │
│  │       └─────────────┴─────────────┴─────────────┴─────────────────┘         │  │
│  │                                                                             │  │
│  │  ┌─────────────────────────────────────────────────────────────────────┐   │  │
│  │  │              Provider Adapters (Claude | Gemini | Codex | Kimi)      │   │  │
│  │  └─────────────────────────────────────────────────────────────────────┘   │  │
│  └────────────────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────────────┘
                                             │
┌────────────────────────────────────────────┼────────────────────────────────────┐
│                         COMPUTE LAYER       │                                   │
│  ┌──────────────────────────────────────────▼────────────────────────────────┐  │
│  │                     Ephemeral Sandbox Pool                                   │  │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │  │
│  │  │   Sandbox 1  │  │   Sandbox 2  │  │   Sandbox N  │  │  Sandbox     │    │  │
│  │  │  (Claude)    │  │  (Gemini)    │  │   (Kimi)     │  │  (Codex)     │    │  │
│  │  │              │  │              │  │              │  │              │    │  │
│  │  │ /home/dev    │  │ /home/dev    │  │ /home/dev    │  │ /home/dev    │    │  │
│  │  │   mounted    │  │   mounted    │  │   mounted    │  │   mounted    │    │  │
│  │  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘    │  │
│  │         └─────────────────┴─────────────────┴─────────────────┘            │  │
│  └────────────────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────────────┘
                                             │
┌────────────────────────────────────────────▼─────────────────────────────────────┐
│                           STORAGE LAYER                                           │
│  ┌─────────────────────┐  ┌─────────────────────┐  ┌──────────────────────────┐  │
│  │   R2 / GCS Buckets  │  │   Durable Objects   │  │   Git Remote (Backup)    │  │
│  │  (Project Files)    │  │  (Session State)    │  │   (Version Control)      │  │
│  │                     │  │                     │  │                          │  │
│  │ /{org}/{team}/      │  │ /sessions/{id}      │  │ github.com/...           │  │
│  │   {user}/{project}  │  │                     │  │                          │  │
│  └─────────────────────┘  └─────────────────────┘  └──────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────────────┘

2.2 Core Design Principles

Principle	Description	Implementation
Thin Client	Browser renders UI; all compute on server	Next.js SPA, WebSocket streams
Stateless Sessions	Ephemeral containers; state in R2/GCS	Mount home dirs from object storage
Multi-Tenant Isolation	Strict org/team/user/project boundaries	Path-based isolation, RBAC
LLM Agnostic	Route to best available provider	Adapter pattern with circuit breaker
Git-Native	Every session backed by version control	Auto-commit on checkpoint

3. System Components

3.1 Thin Client (Browser Application)

Technology Stack:

Framework: Next.js 14 (App Router)
Language: TypeScript 5.x
Styling: Tailwind CSS with custom design system
State: Zustand (client) + Server-sent events
Real-time: WebSocket (Socket.io)

Key Modules:

Module	Purpose	Key Files
Chat Interface	Agent communication	`chat-panel.tsx`, `message-list.tsx`
Visualization	Workflow/pitch/market views	`viz-panel.tsx`, `workflow-diagram.tsx`
Session Manager	Active session list, resume	`session-list.tsx`, `session-card.tsx`
Project Explorer	File tree, navigation	`file-tree.tsx`, `project-nav.tsx`
Command Palette	Quick actions, shortcuts	`command-palette.tsx`

3.2 CODITECT-CORE Orchestrator

Responsibilities:

Authentication & Authorization - JWT validation, API key management
Tenant Resolution - Map requests to org/team/user/project context
LLM Routing - Select provider based on task type, cost, availability
Session Lifecycle - Spawn, monitor, terminate ephemeral sandboxes
State Management - Coordinate between ephemeral compute and persistent storage

API Surface:

// Core API Routes
POST   /api/v1/sessions              // Create new session
GET    /api/v1/sessions/:id          // Get session status
DELETE /api/v1/sessions/:id          // Terminate session
POST   /api/v1/sessions/:id/exec     // Execute command
GET    /api/v1/sessions/:id/files    // List files
POST   /api/v1/chat                  // Send chat message
GET    /api/v1/chat/:session/stream  // Stream responses

// Management APIs
GET    /api/v1/teams                 // List teams
GET    /api/v1/projects              // List projects
POST   /api/v1/checkpoint           // Create checkpoint
POST   /api/v1/restore              // Restore from checkpoint

3.3 Ephemeral Sandbox Pool

Sandbox Types:

Type	Use Case	Lifecycle
Interactive	Live coding, chat sessions	30-min idle timeout
Batch	Background jobs, builds	Task completion
Persistent	Long-running services	24-hour max

Resource Limits per Sandbox:

CPU: 2 vCPU (burst to 4)
Memory: 4GB (burst to 8GB)
Disk: 10GB ephemeral + mounted R2
Network: Outbound only, filtered

3.4 Storage Architecture

R2/GCS Bucket Structure:

bucket: coditect-{org-id}
│
├── teams/{team-id}/
│   ├── users/{user-id}/
│   │   ├── home/              # $HOME mount
│   │   │   ├── .coditect/     # CLI config
│   │   │   ├── .ssh/          # Git keys
│   │   │   └── .cache/        # Tool caches
│   │   │
│   │   └── projects/
│   │       ├── {project-id}/
│   │       │   ├── .git/      # Git repository
│   │       │   ├── src/       # Source code
│   │       │   └── .coditect/ # Project state
│   │
│   └── shared/                # Team resources
│       ├── templates/
│       └── assets/
│
├── sessions/
│   └── {session-id}/
│       ├── checkpoints/       # Session snapshots
│       └── logs/              # Execution logs
│
└── system/
    └── cache/                 # Shared tool cache

4. Data Flows

4.2 Chat with Multi-LLM Routing

4.3 File Edit with Git Backup

5. Security Architecture

5.1 Authentication

Method	Use Case	Implementation
SSO	Enterprise users	SAML 2.0, OIDC
API Keys	Service accounts	HMAC-SHA256, rotation
OAuth	Third-party integrations	GitHub, Google
Session JWT	Browser sessions	RS256, 1-hour expiry

5.2 Authorization (RBAC)

Role Hierarchy:

Organization Admin
├── Team Admin
│   ├── Project Lead
│   │   └── Developer
│   └── Analyst
└── Billing Admin

Permissions:

Resource	Create	Read	Update	Delete
Sessions	developer	all	owner	admin
Projects	lead	team	lead	admin
Teams	admin	org	admin	admin
API Keys	admin	owner	-	owner

5.3 Data Isolation

Network: Sandboxes have no inter-container networking
Storage: Path-based isolation with strict prefix validation
Compute: VM-level isolation via Cloudflare Sandboxes
Memory: Encrypted at rest, TLS in transit

6. Scalability & Performance

6.1 Scaling Strategy

Component	Scaling Method	Trigger
CDN	Auto	Global edge
Workers	Auto	Request rate
Sandboxes	Pool-based	Queue depth
R2	N/A (serverless)	N/A
Durable Objects	Sharding	Per-object limits

6.2 Performance Targets

Metric	Target	Measurement
Page Load	< 2s	Lighthouse
Session Start	< 5s	API latency
Chat Response	< 1s TTFB	LLM adapter
File List	< 500ms	R2 LIST
Checkpoint	< 3s	Git commit + push

7. Deployment Architecture

7.1 Environments

Environment	Purpose	Sandbox Pool
Production	Live users	Isolated, monitored
Staging	Pre-release	Shared, limited
Development	Feature dev	Local, ephemeral

7.2 CI/CD Pipeline

Developer Push
    │
    ▼
┌─────────────┐
│   Build     │ → Next.js static export
└──────┬──────┘
       │
       ▼
┌─────────────┐
│    Test     │ → Unit, integration, e2e
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Deploy    │ → Cloudflare Pages (UI)
│             │ → Workers (API)
└─────────────┘

8. Appendix

8.1 Glossary

Term	Definition
Thin Client	Browser-based UI with server-side compute
Sandbox	Ephemeral isolated execution environment
Checkpoint	Versioned snapshot of session state
MOE	Mixture-of-Experts (multi-LLM routing)
FUSE	Filesystem in Userspace (R2/GCS mounting)

8.2 References

ADR-141: Pitch Deck Studio Architecture
ADR-143: IN-PLACE Document Translation
MOE-Agents C4 Architecture
Cloudflare Workers Documentation
FAU Runway 11-Slide Framework

Document Owner: Platform Engineering Team
Review Cycle: Quarterly
Next Review: 2026-04-30

1. Executive Summary​

1.1 Purpose​

1.2 Scope​

1.3 Key Stakeholders​

2. System Overview​

2.1 High-Level Architecture​

2.2 Core Design Principles​

3. System Components​

3.1 Thin Client (Browser Application)​

3.2 CODITECT-CORE Orchestrator​

3.3 Ephemeral Sandbox Pool​

3.4 Storage Architecture​

4. Data Flows​

4.1 User Login & Session Initialization​

4.2 Chat with Multi-LLM Routing​

4.3 File Edit with Git Backup​

5. Security Architecture​

5.1 Authentication​

5.2 Authorization (RBAC)​

5.3 Data Isolation​

6. Scalability & Performance​

6.1 Scaling Strategy​

6.2 Performance Targets​

7. Deployment Architecture​

7.1 Environments​

7.2 CI/CD Pipeline​

8. Appendix​

8.1 Glossary​

8.2 References​