ADR-142: Unified Development Studio Architecture

Status

Proposed | January 30, 2026

Context

Related ADRs

• ADR-017-v4: Unified Workspace Architecture (original cloud IDE)
• ADR-027-v4: Skills Container Integration
• ADR-028-v4: Hybrid Storage Architecture

Background

The CODITECT platform has evolved into multiple successful products:

1. coditect-cloud-ide (production at https://coditect.ai)

   • Eclipse Theia-based cloud IDE
   • Three modalities: IDE, AI Studio, Workspace
   • Deployed on GCP GKE

2. coditect-dev-ui (in development)

   • Next.js 14 + Tailwind
   • Split-view chat + visualization
   • ADR-141 Pitch Deck integration

3. pitch-deck-mastery (skill)

   • PptxGenJS presentation generation
   • 11-step wizard workflow

4. coditect-compliance (LIMS module)

   • GxP compliance tracking
   • Document management

Problem Statement

Users currently face fragmentation:

• Switching between separate applications
• Inconsistent UI/UX patterns
• Duplicate authentication flows
• No shared terminal or session management

Decision

We will create a Unified Development Studio that:

1. Integrates all products as modules in a single interface
2. Uses Next.js 14 + Tailwind as the core framework
3. Embeds Theia IDE as one module option (not as the wrapper)
4. Provides unified terminal accessible from any module
5. Shares session state across all modules
6. Maintains CODITECT branding consistently

Architecture

Module System

┌─────────────────────────────────────────────────────────────────┐
│  CODITECT Unified Development Studio                             │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  Dev Studio | IDE | AI Studio | Pitch | LIMS   │
│  │             ├───────────────────────────────────────────────┤
│  │  Module     │                                               │
│  │  Sidebar    │   ┌───────────────────────────────────────┐   │
│  │             │   │                                       │   │
│  │  • Dev      │   │     ACTIVE MODULE CONTENT             │   │
│  │    Studio   │   │                                       │   │
│  │  • IDE      │   │  ┌─────────┐  ┌───────────────────┐   │   │
│  │  • AI       │   │  │ Chat    │  │   Visualization   │   │   │
│  │    Studio   │   │  │ Panel   │  │      Panel        │   │   │
│  │  • Pitch    │   │  └─────────┘  └───────────────────┘   │   │
│  │    Deck     │   │                                       │   │
│  │  • LIMS     │   │  [Terminal Drawer - Slide Up]         │   │
│  │  • Agents   │   │  ┌─────────────────────────────────┐  │   │
│  │             │   │  │ $ /session-log --filter dev     │  │   │
│  └─────────────┘   │  │ $ /agent switch coditect-v5     │  │   │
│                    │  └─────────────────────────────────┘  │   │
│                    │                                       │   │
│                    └───────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────────┤
│  Status Bar: Session: active | User: hal@coditect.ai | ⚡ Ready │
└─────────────────────────────────────────────────────────────────┘

Module Registry

interface ModuleConfig {
  id: string;              // Unique identifier
  name: string;            // Display name
  icon: LucideIcon;        // Module icon
  component: LazyComponent;
  requiresAuth: boolean;
  theiaIntegration?: 'full' | 'partial' | 'none';
}

const modules: ModuleConfig[] = [
  {
    id: 'dev-studio',
    name: 'Dev Studio',
    icon: Terminal,
    component: lazy(() => import('./modules/dev-studio')),
    requiresAuth: true,
    theiaIntegration: 'none',      // Pure custom implementation
  },
  {
    id: 'theia',
    name: 'IDE',
    icon: Code,
    component: lazy(() => import('./modules/theia-ide')),
    requiresAuth: true,
    theiaIntegration: 'full',      // Full Theia via iframe or library
  },
  {
    id: 'ai-studio',
    name: 'AI Studio',
    icon: Sparkles,
    component: lazy(() => import('./modules/ai-studio')),
    requiresAuth: true,
    theiaIntegration: 'partial',   // Theia chat widget only
  },
  {
    id: 'pitch-deck',
    name: 'Pitch Deck',
    icon: Presentation,
    component: lazy(() => import('./modules/pitch-deck')),
    requiresAuth: true,
    theiaIntegration: 'none',
  },
  {
    id: 'lims',
    name: 'LIMS',
    icon: FlaskConical,
    component: lazy(() => import('./modules/lims')),
    requiresAuth: true,
    theiaIntegration: 'none',
  },
];

Theia Integration Strategy

Phase 1: Iframe Embed (Current)

// modules/theia-ide/theia-iframe-module.tsx
export function TheiaIframeModule() {
  return (
    <iframe
      src="/theia"
      className="w-full h-full border-0"
      allow="clipboard-read; clipboard-write"
      sandbox="allow-same-origin allow-scripts allow-forms"
    />
  );
}

Phase 2: Library Integration (Future)

// modules/theia-ide/theia-library-module.tsx
import { FileNavigator } from '@theia/navigator/lib/browser';
import { MonacoEditor } from '@theia/monaco/lib/browser';
import { TerminalWidget } from '@theia/terminal/lib/browser';

export function TheiaLibraryModule() {
  return (
    <TheiaContainerProvider>
      <div className="theia-layout">
        <FileNavigator />
        <MonacoEditor />
        <TerminalWidget />
      </div>
    </TheiaContainerProvider>
  );
}

Terminal Integration

Unified terminal accessible from any module:

// components/terminal-drawer.tsx
interface TerminalDrawerProps {
  isOpen: boolean;
  sessionId: string;
  onCommand: (command: string) => void;
}

// Supported commands:
// /session-log [filter]  - View session history
// /agent <name>          - Switch active agent
// /module <name>         - Switch module
// /terminal              - Toggle terminal
// /help                  - Show commands

State Management

// lib/store.ts
interface UnifiedState {
  // Module state
  activeModuleId: string;
  moduleHistory: string[];
  
  // Session state (shared across modules)
  currentSession: Session;
  
  // Terminal state
  terminalOpen: boolean;
  terminalHistory: CommandEntry[];
  
  // Theme
  theme: 'light' | 'dark';
}

Consequences

Positive

• Unified UX: Single interface for all CODITECT tools
• Shared Sessions: Context preserved across modules
• Consistent Branding: CODITECT identity throughout
• Easier Onboarding: One login, multiple capabilities
• Cross-Module Features: Terminal works everywhere

Negative

• Increased Complexity: Module coordination required
• Theia Integration: iframe limitations or library complexity
• Bundle Size: Lazy loading essential
• State Management: Shared state needs careful design

Neutral

• Technology Stack: Next.js 14 + Tailwind (consistent with dev-ui)
• Authentication: JWT-based (existing pattern)

Implementation Phases

Phase 1: Core Shell (Week 1-2)

• Module registry system
• Unified layout (header, sidebar, content area)
• Theme integration
• Basic navigation

Phase 2: Theia Integration (Week 3-4)

• iframe embed option
• Theme synchronization
• Session passing
• Terminal integration

Phase 3: Module Migration (Week 5-8)

• Dev Studio module (coditect-dev-ui)
• AI Studio module (Theia chat)
• Pitch Deck module (ADR-141)
• LIMS module (compliance)

Phase 4: Advanced Features (Week 9-12)

• Cross-module state sharing
• Unified terminal commands
• Session history integration
• Performance optimization

Alternatives Considered

Alternative 1: Keep Separate Applications

• Decision: Rejected
• Reason: Fragmentation hurts user experience

Alternative 2: Make Theia the Wrapper

• Decision: Rejected
• Reason: Theia UI limitations, harder to customize

Alternative 3: Full Theia Extension

• Decision: Rejected for now
• Reason: Requires rebuilding Theia, limits flexibility

Alternative 4: Pure Custom (No Theia)

• Decision: Partial (for some modules)
• Reason: Monaco + xterm.js sufficient for Dev Studio

References

• ADR-017-v4 - Original Unified Workspace
• Theia as Library - Integration options analysis
• Unified Studio Architecture - Full architecture document
• Production: https://coditect.ai

Decision Log

Date	Decision	Rationale
2026-01-30	Create new ADR-142	Evolution from ADR-017, new product scope
2026-01-30	Use Next.js as core	Alignment with coditect-dev-ui
2026-01-30	Theia as module, not wrapper	Greater UI flexibility
2026-01-30	Phased Theia integration	Manage complexity, quick wins first
2026-01-30	Socket.io for WebSockets	Real-time agent and terminal updates
2026-01-30	Next.js API Routes	Simplified backend architecture

---

Backend Architecture (Added 2026-01-30)

API Layer

apps/web/src/app/api/
├── socket/route.ts          # WebSocket initialization
├── agents/route.ts          # Agent CRUD API
├── sessions/route.ts        # Session management API
├── terminal/route.ts        # Terminal proxy API
└── health/route.ts          # Health check endpoint

WebSocket Events

Client → Server:

• auth - Authenticate connection
• agent:subscribe - Subscribe to agent updates
• agent:command - Send command to agent
• terminal:input - Send terminal input
• terminal:resize - Resize terminal
• session:update - Update session state
• session:module:change - Switch module

Server → Client:

• agent:status - Agent status update
• agent:log - Agent log entry
• terminal:output - Terminal output
• session:state - Session state update
• session:module:change - Module changed notification

Data Models

// Agent Status
interface AgentStatus {
  id: string;
  name: string;
  status: 'running' | 'idle' | 'error' | 'paused';
  type: 'coding' | 'analysis' | 'review' | 'testing';
  tasksCompleted: number;
  successRate: number;
  lastActivity: Date;
}

// Session
interface Session {
  id: string;
  userId: string;
  moduleId: string;
  agentId: string | null;
  terminalOpen: boolean;
  createdAt: Date;
  updatedAt: Date;
}

// Terminal Message
interface TerminalMessage {
  type: 'input' | 'output' | 'error';
  data: string;
  timestamp: string;
  sessionId: string;
}

Storage

In-Memory (Current):

• Map<string, AgentStatus> - Agent registry
• Map<string, Session> - Active sessions
• Map<string, string> - Socket to user mapping

Future (Production):

• Redis for session storage
• PostgreSQL for persistent data
• Message queue for agent tasks

Security

• JWT authentication on socket connection
• API route authentication middleware
• CORS configuration for production
• Rate limiting on API endpoints

---

Implementation Status (Updated 2026-01-30)

Phase 1: Core Shell ✅ COMPLETE

• Module registry system
• Unified layout (header, sidebar, footer, content area)
• Theme integration (dark/light mode)
• CODITECT branding with SVG logo
• Footer with copyright and links

Phase 2: Backend & WebSockets ✅ COMPLETE

• Socket.io server implementation
• Agent API (CRUD operations)
• Session API
• Terminal proxy
• Health check endpoint
• Real-time updates for agents

Phase 3: Modules ✅ COMPLETE

• AI Studio module (chat-to-code)
• LIMS module (GxP compliance dashboard)
• Agent Orchestrator (with real-time updates)
• Dev Studio module (coditect-dev-ui integration)
• Pitch Deck module (pitch-deck-studio integration)
• Theia IDE iframe integration

Phase 4: Advanced Features ⏳ PENDING

• Cross-module state sharing via WebSocket
• Terminal shell proxy (real shell access)
• Authentication middleware
• Redis session storage
• Performance optimization

---

Supersedes: None (complements ADR-017)
Related:

• ADR-017 (cloud-ide): Unified Workspace Architecture (original cloud IDE)
• ADR-027 (cloud-ide): CODITECT Skills Container Integration
• ADR-028 (cloud-ide): Hybrid Storage Architecture
• ADR-057 (core): CODITECT Core Initial Setup
• ADR-141 (core): Pitch Deck Mastery v3 Architecture

Registry: See REGISTRY.md
Author: CODITECT Architecture Team
Reviewers: CTO, Lead Architect, Product Director