CodeSpace

A cloud-native microservices development platform that provides browser-based, AI-orchestrated container sandboxes for real-time frontend prototyping, code editing, interactive terminal execution, and live application preview.

---

Features

• In-Browser Monaco Code Editor: Syntax-highlighted code editing with file extension detection and 300ms debounced auto-saving directly to container storage (CodeViewer.jsx, MonacoEditorWrapper.jsx).
• Real-Time AI Generation Stream: Natural-language coding assistant powered by LangGraph and Mistral AI, streaming code mutations and progress over Server-Sent Events (agent.routes.js, ChatPanel.jsx).
• Interactive Container Terminal: In-browser terminal stream connected to containerized pseudo-terminals (node-pty) over Socket.io WebSockets and xterm.js (TerminalPanel.jsx, sandbox/agent/src/app.js).
• Dynamic Kubernetes Sandbox Provisioning: On-demand lifecycle orchestration creating dedicated sandbox Pods, ClusterIP Services, and 20-minute Redis TTL expiration triggers (sandbox/server/src/kubernetes/pod.js, redis.js).
• Host-Header Routing & Reverse Proxy: Dynamic wildcard subdomain proxying routing traffic for *.preview.developerever.dev to the template dev server (port 5173) and *.agent.developerever.dev to the agent API (port 3000) (sandbox/router/src/app.js).
• Resilient File Synchronization: In-pod chokidar file watcher synchronizing workspace updates bi-directionally with AWS S3 (sandbox/sync-agent/sync.js).
• Google OAuth & Event Publishing: OAuth 2.0 authentication flow with JWT session management and login notification publishing via RabbitMQ (auth/src/routes/auth.routes.js).
• Asynchronous Email Notifications: RabbitMQ worker consuming authentication events and dispatching login alerts via Nodemailer (notification/src/app.js).

---

Tech Stack

Category	Tool	Version
Frontend Framework	React	19.2.8
Frontend Bundler	Vite	8.2.0
Frontend Styling	Tailwind CSS	4.3.3
Frontend Motion	Framer Motion	13.0.0
Code Editor	Monaco Editor (@monaco-editor/react, monaco-editor)	4.7.0 / 0.53.0
Terminal Emulator	xterm.js (@xterm/xterm, @xterm/addon-fit, @xterm/addon-web-links)	6.0.0
Real-Time Client	Socket.io Client	4.8.3
Backend Framework	Express	5.2.1
AI Orchestration	LangGraph (@langchain/langgraph), LangChain (langchain)	1.4.8 / 1.5.4
LLM Provider	Mistral AI (@langchain/mistralai)	1.2.0
Schema Validation	Zod	4.4.3
Kubernetes Integration	@kubernetes/client-node	1.4.0
Reverse Proxy Engine	http-proxy-middleware, httpxy	4.2.0 / 0.5.1
Terminal Engine (Backend)	node-pty	1.1.0
WebSockets (Backend)	socket.io	4.8.3
File Watching	chokidar	5.0.0
Object Storage Client	AWS SDK S3 (@aws-sdk/client-s3)	3.1105.0
Database & ORM	MongoDB, Mongoose	9.9.1
Cache & Key Expiration	Redis (ioredis)	6.0.0
Message Broker	RabbitMQ (amqplib)	2.0.1
Email Service	Nodemailer	9.0.3
Authentication	Passport (passport-google-oauth20), JSON Web Token (jsonwebtoken)	0.7.0 / 2.0.0 / 9.0.3

---

Architecture & Directory Structure

CodeSpace is architected as an event-driven microservices system deployed on Kubernetes.

08 - The Capstone/
├── ai-orchestration/           # LangGraph + Mistral AI agent streaming code generation via SSE
│   └── src/
│       ├── agents/             # Agent definition and file manipulation tool implementations
│       ├── routes/             # Express SSE route handlers (/api/ai/invoke)
│       └── app.js              # Express app setup and health endpoints
├── auth/                       # Google OAuth 2.0 and JWT issuance service
│   └── src/
│       ├── config/             # MongoDB and RabbitMQ connection handlers
│       ├── models/             # Mongoose User schema
│       ├── routes/             # Authentication endpoints (/api/auth/google, /callback)
│       └── app.js              # Passport configuration and Express app setup
├── frontend/                   # React 19 SPA featuring Monaco Editor, xterm.js, and SSE chat
│   └── src/
│       ├── components/         # IDELayout, CodeViewer, TerminalPanel, ChatPanel, FileExplorer
│       ├── hooks/              # useSandboxSocket custom hook for Socket.io management
│       ├── utils/              # monacoLanguageMap utility
│       ├── App.jsx             # Top-level application controller
│       └── main.jsx            # Entry point configuring local Monaco Web Workers
├── k8s/                        # Kubernetes manifests for deployments, services, ingress, and RBAC
│   ├── ai-deployment.yml       # AI orchestration deployment manifest
│   ├── auth-deployment.yml     # Auth service deployment manifest
│   ├── ingress.yml             # NGINX Ingress definitions for API and wildcard subdomains
│   ├── notification-deployment.yml # Notification service deployment manifest
│   ├── rbac.yml                # Cluster role and binding for Pod lifecycle operations
│   ├── router-deployment.yml   # Sandbox router reverse proxy deployment
│   ├── sandbox-deployment.yml  # Sandbox server orchestrator deployment
│   └── secrets.yml.example     # Template for required Kubernetes secrets
├── notification/               # RabbitMQ consumer dispatching transactional emails via Nodemailer
│   └── src/
│       ├── app.js              # RabbitMQ queue consumer loop
│       ├── email.js            # Nodemailer transport configuration
│       └── mq.js               # RabbitMQ channel initialization
├── sandbox/                    # Core sandbox orchestration, container agent, and routing engine
│   ├── agent/                  # In-pod node-pty terminal provider and REST filesystem API
│   │   └── src/app.js          # File manipulation (/read-files, /update-files) and terminal stream
│   ├── router/                 # Dynamic reverse proxy matching *.preview and *.agent host headers
│   │   └── src/app.js          # HTTP proxy and WebSocket upgrade handler
│   ├── server/                 # Sandbox lifecycle orchestrator creating K8s pods and Redis keys
│   │   └── src/
│   │       ├── kubernetes/     # Pod and Service creation logic via @kubernetes/client-node
│   │       ├── routes/         # Sandbox start and project management endpoints
│   │       └── config/redis.js # Redis TTL expiration event listener for automatic pod cleanup
│   ├── sync-agent/             # In-pod background worker synchronizing workspace files to AWS S3
│   │   └── sync.js             # Chokidar watcher with debounced S3 Put/Delete commands
│   └── template/               # Base Vite + React project container image cloned into each sandbox
├── skaffold.yml                # Local Kubernetes development workflow configuration
└── skaffold-eks.yaml           # AWS ECR / EKS deployment configuration

---

Getting Started

Prerequisites

• Node.js 20.x or later
• Docker and Docker Compose / Kubernetes cluster (e.g., Minikube, Docker Desktop Kubernetes, or EKS)
• Skaffold v2.x (for container build and sync orchestration)
• MongoDB instance
• Redis instance (keyspace notifications enabled: notify-keyspace-events "Ex")
• RabbitMQ instance

1. Installation

Install dependencies across services:

# Frontend
cd frontend && npm install

# Auth Service
cd ../auth && npm install

# AI Orchestration Service
cd ../ai-orchestration && npm install

# Notification Service
cd ../notification && npm install

# Sandbox Server
cd ../sandbox/server && npm install

# Sandbox Agent
cd ../sandbox/agent && npm install

# Sandbox Router
cd ../sandbox/router && npm install

# Sandbox Sync Agent
cd ../sandbox/sync-agent && npm install

# Sandbox Template
cd ../sandbox/template && npm install

2. Running the Application

Option A: Kubernetes via Skaffold (Standard Environment)

To build all container images and deploy manifests to your active Kubernetes cluster context:

skaffold dev

For AWS EKS deployment using ECR repositories:

skaffold dev -f skaffold-eks.yaml

Option B: Standalone Node.js Services (Local Development)

Run required services individually in separate terminal sessions:

# 1. Frontend Development Server (http://localhost:5173)
cd frontend
npm run dev

# 2. Auth Service
cd auth
npm run dev

# 3. AI Orchestration Service
cd ai-orchestration
npm run dev

# 4. Notification Service
cd notification
npm run dev

# 5. Sandbox Orchestrator Server
cd sandbox/server
npm run dev

# 6. Sandbox Router
cd sandbox/router
npm run dev

---

Configuration

Configuration values are supplied via environment variables or Kubernetes secrets (k8s/secrets.yml.example).

Environment Variables Matrix

Variable	Target Service	Purpose
AUTH_DATABASE_URL / AUTH	auth	MongoDB connection URI for user identity storage
SANDBOX_DATABASE_URL / SANDBOX	sandbox/server	MongoDB connection URI for project metadata
REDIS_URI / REDIS_URL	sandbox/server, sandbox/router	Redis connection URI for session tracking and TTL cleanup
RABBITMQ_URL	auth, notification	RabbitMQ connection URI for asynchronous event messaging
JWT_SECRET	auth, sandbox/server	Secret key used to sign and verify user JWT authentication tokens
GOOGLE_CLIENT_ID	auth, notification	Google OAuth 2.0 client ID
GOOGLE_CLIENT_SECRET	auth, notification	Google OAuth 2.0 client secret
GOOGLE_REFRESH_TOKEN	notification	OAuth 2.0 refresh token for Nodemailer Gmail transport
EMAIL_USER	notification	Sender email address for account notification alerts
MISTRAL_API_KEY	ai-orchestration	API key for Mistral AI LLM interaction (mistral-medium-latest)
AWS_ACCESS_KEY_ID	sandbox/sync-agent	AWS access key for S3 bucket operations
AWS_SECRET_ACCESS_KEY	sandbox/sync-agent	AWS secret key for S3 bucket operations
AWS_REGION	sandbox/sync-agent	AWS region hosting the S3 bucket (cohort-codespace-buckett)
PROJECT_ID	sandbox/sync-agent	Identifier of active project session injected into container pod

---

Testing

Individual microservices declare npm test scripts in their manifests:

# Frontend ESLint validation
cd frontend && npm run lint

# Template ESLint validation
cd sandbox/template && npm run lint

Backend services currently have default test placeholders (npm test). Automated end-to-end integration tests are not yet configured.

---

Operational Notes & Reconciliation

• Ingress Routing: Kubernetes Ingress (k8s/ingress.yml) maps root domain traffic to backend APIs and wildcards *.preview.developerever.dev and *.agent.developerever.dev to router-service. Local testing requires appropriate DNS / /etc/hosts resolution pointing wildcard hosts to the cluster ingress controller.
• Monaco Web Workers: Local Web Workers are configured in frontend/src/main.jsx and loaded directly from node_modules/monaco-editor. When deploying under Content Security Policy (CSP), ensure worker-src 'self' blob: and script-src 'self' directives are enabled.