Skip to main content

ADR-001-v4: Container Execution Architecture - Part 1: Human

Document Specification Block​

Document: ADR-001-v4-container-execution-architecture-part1-human
Version: 3.0.0
Purpose: Explain CODITECT's browser-based development environment architecture for business stakeholders
Audience: Business stakeholders, product managers, non-technical decision makers
Date Created: 2025-08-27
Date Modified: 2025-09-03
Status: UPDATED_FOR_STATEFULSETS
Changes: Replaced ephemeral containers with GKE StatefulSets

Table of Contents​

↑ Back to Top

What This Architecture Does​

CODITECT provides developers with complete Linux development environments accessible through any web browser. Instead of installing software locally, developers connect to their workspace and have all their tools, files, and terminal access ready immediately. Work is automatically saved and synchronized, making development possible from any device.

Why This Matters for Business​

The Developer Experience Problem​

Today's software developers face significant challenges:

  • Setup Time: New developers spend 2-3 days installing and configuring tools
  • Device Limitations: Powerful laptops cost $3,000-5,000 per developer
  • Lost Work: System crashes or device failures can lose hours of work
  • Remote Access: Working from different locations requires complex VPN setups
  • Collaboration Barriers: Sharing development environments is nearly impossible

Market Opportunity​

  • Developer Population: 27 million developers worldwide, growing 5% annually
  • Cloud IDE Market: Expected to reach $15.2 billion by 2028
  • Remote Work: 86% of developers work remotely at least part-time
  • Hardware Costs: Companies spend $4,000+ per developer on hardware

The Problem We're Solving​

Current State Analysis​

CODITECT has already deployed working infrastructure:

  • ✅ API service running on Google Cloud
  • ✅ WebSocket connections for real-time communication
  • ✅ Authentication system with workspace isolation
  • ✅ Basic file operations (create, read, update, delete)
  • ✅ terminal output display

However, critical issues prevent full functionality:

  • ❌ terminal input broken (developers can't type commands)
  • ❌ Running on cost-optimized GKE Autopilot ($50/month with Spot)
  • ❌ No user interface deployed
  • ❌ AI assistance features not responding

Business Impact of Current Issues​

  • Blocked Launch: Can't release without working terminal input
  • High Operating Costs: Kubernetes overhead eating into margins
  • Limited Demo Capability: Can't show full product to investors
  • Developer Frustration: Early testers abandon due to bugs

Our Solution Approach​

Visual Overview​

Cost Comparison​

Key Architecture Decisions​

  1. Persistent workspace Model

    • Instead of: Ephemeral containers that lose state
    • We use: GKE StatefulSets with persistent volumes
    • Result: Instant workspace recovery, better developer experience

  2. Browser-Based Access

    • Instead of: Installing software locally
    • We use: Web technologies for everything
    • Result: Works on any device with a browser

  3. Integrated Persistence

    • Instead of: External state storage only
    • We use: PersistentVolumeClaims + FoundationDB metadata
    • Result: Fast file access, automatic backups

Business Benefits​

Immediate Benefits (Week 1-2)​

  • Fix Critical Bug: Enable developers to actually use the terminal
  • Reduce Costs: 75% reduction using GKE Autopilot with Spot instances
  • Launch MVP: Deploy working product with persistent workspaces

Short-Term Benefits (Month 1-3)​

  • Developer Onboarding: Reduce from 3 days to 30 minutes
  • Hardware Savings: Eliminate $5,000 per developer laptop costs
  • Remote Work: Enable development from any device, anywhere
  • Team Efficiency: Share workspaces for pair programming

Long-Term Benefits (Year 1)​

  • Scale to 10,000+ Users: Architecture supports massive growth
  • Enterprise Sales: IT departments love centralized management
  • Global Expansion: Low latency from regional deployments
  • Platform Revenue: $50-200 per developer per month

Competitive Advantages​

  • Instant Start: 5 minutes vs 3 days for traditional setup
  • Cost Efficiency: 80% lower total cost of ownership
  • Zero Install: Nothing to download or configure
  • Always Available: 99.9% uptime with cloud infrastructure

Success Metrics​

Technical Metrics​

  • terminal Response Time: <100ms (currently broken)
  • File Operation Speed: <300ms (currently working)
  • Session Recovery: <2 seconds (needs implementation)
  • Concurrent Users: 10,000+ per region (architecture supports)

Business Metrics​

  • Cost per User: <$5/month infrastructure (target)
  • Setup Time: 5 minutes from signup to coding
  • User Retention: 80%+ monthly active users
  • Revenue per User: $50-200/month

Quality Metrics​

  • Uptime: 99.9% availability
  • Data Loss: Zero with automatic saves
  • Security: SOC2 compliant isolation
  • Performance: Faster than local development

Implementation Timeline​

Phase 1: Critical Fixes (Week 1)​

Goal: Make the product actually work

  • Day 1-2: Fix terminal input bug
  • Day 3-4: Test across browsers
  • Day 5: Deploy fixes to production
  • Business Impact: Can demo to investors and early customers

Phase 2: Cost Optimization (Week 2)​

Goal: Reduce operating costs by 60-80%

  • Day 1-2: Deploy to GKE Autopilot with StatefulSets
  • Day 3-4: Configure Spot instances and auto-scaling
  • Day 5: Monitor and optimize
  • Business Impact: Sustainable unit economics

Phase 3: User Interface (Week 3)​

Goal: Launch usable product

  • Day 1-3: Deploy terminal interface
  • Day 4-5: Add file browser
  • Business Impact: Ready for beta customers

Cost Analysis​

Current State (Broken)​

  • GKE Cluster: $50/month with Spot instances
  • Per User: ~$5/month at low scale
  • Problem: Need to optimize for persistent workspaces

Target State (Fixed)​

  • GKE StatefulSets: $50/month base with Spot instances
  • Per User: $2-5/month at any scale
  • Benefit: 75% cost reduction with persistent workspaces

Revenue Model​

  • Hobbyist: $19/month (limited resources)
  • Professional: $49/month (standard resources)
  • Team: $99/month (premium resources + collaboration)
  • Enterprise: $199/month (dedicated resources + support)

Unit Economics​

  • Cost per User: $5/month
  • Average Revenue: $50/month
  • Gross Margin: 90%
  • Payback Period: <1 month

Technical Summary​

The architecture uses a shared WebSocket gateway model with workspace isolation at the process level. terminal sessions run in isolated PTY processes with state persisted to FoundationDB. File operations use a virtual filesystem layer with PersistentVolumeClaims for storage. The implementation uses GKE Autopilot with StatefulSets to provide persistent workspaces while reducing operational complexity and costs through Spot instances.

Key technical components:

  • WebSocket Gateway: Connection management and routing
  • terminal Bridge: PTY process lifecycle management
  • Session Manager: State persistence and recovery
  • File Handler: CRUD operations with workspace isolation
  • FoundationDB: Consistent state storage across instances

Next Steps​

Next: See Part 2: Technical Implementation for detailed architecture blueprints, code implementations, and deployment specifications.

↑ Back to Top