StackSpace

A full-stack, real-time collaborative cloud IDE — built from scratch.

Code together in a real VS Code, in the cloud, from your browser. No setup. No installs. Just create a room, share a link, and start building.

🎬 Demo

⚠️ Note: The live deployment is currently offline — my free AWS tier expired. The video below shows the fully working project.

StackSpace.mp4

Watch the full demo: room creation, launching a cloud IDE, real-time collaboration, whiteboard, and team chat — all running on AWS Fargate.

🚀 What is StackSpace?

StackSpace lets you spin up a full VS Code IDE in the cloud inside an isolated Docker container, share it with teammates via a link, and collaborate in real time — complete with a synchronized whiteboard and built-in team chat.

Think of it as your own private Repl.it, but self-hosted on AWS and powered by the real VS Code.

• No local installs required for collaborators — just a browser
• Full VS Code experience (extensions, terminal, debugger, themes)
• 8 pre-configured language stacks — from Python to C++
• Persistent file storage via AWS EFS — your code survives container restarts
• Real-time presence — see who's online, who's typing, who's in the room
• Collaborative whiteboard — draw diagrams together using Excalidraw, synced over WebSockets
• Team chat with file sharing — built-in, no need for a separate Slack window

✨ Features

🖥️ Cloud IDE (The Core)

• Full OpenVSCode Server running inside a Docker container on AWS Fargate
• Per-room isolated containers — each room gets its own compute
• Embedded directly inside the browser via <iframe>
• Container liveness detection — automatically shows "Start Room" if the container died
• 2-minute heartbeat keeps idle containers from being shut down while you're active
• Multi-step loader with descriptive phases: "Allocating Fargate resources", "Starting VS Code backend", etc.

👥 Real-Time Collaboration

• Socket.IO server handles room presence, live user lists, and whiteboard sync
• Knock-to-enter flow — guests request to join, owner approves/rejects with a toast notification
• Owner/guest role separation baked into the socket layer
• Real-time reconnection handling — sockets re-register state on reconnect

🎨 Collaborative Whiteboard

• Powered by Excalidraw — the same whiteboard used by teams at major tech companies
• Changes broadcast in real-time over Socket.IO to all room members
• 1-second debounced persistence to Appwrite DB — no data loss on refresh
• Remote-update loop prevention — your own changes don't echo back

💬 Team Chat

• Persistent chat history stored in Appwrite Database with Realtime subscriptions
• File sharing — upload and download any file type directly in chat
• Smart MIME type handling — .docx, .xlsx, .pptx, .pdf download correctly without renaming
• Reply toasts — get a non-intrusive popup when a teammate messages you while you're in the IDE
• Unread message badge on the chat dock icon

🛠️ 8 Language Stacks (Pre-configured IDE Environments)

Each stack is a custom Docker image with language tooling + VS Code extensions pre-installed:

Stack	Runtime	Key Extensions
🐍 Python	Python 3.12	Pylance, Black formatter, isort
🟢 Node.js	Node.js 20 LTS	ESLint, Prettier
⚛️ React + Vite	Node.js 20 + Vite	ESLint, Prettier, Tailwind CSS
🔺 Next.js	Node.js 20 + Next.js	ESLint, Prettier, Tailwind CSS, dotenv
☕ Java	Eclipse Temurin JDK 21	Java Extension Pack
➕ C++	GCC on Debian Bookworm	clangd (LSP), CMake Tools
🌐 HTML/CSS/JS	Node.js 20	ESLint, Prettier
📊 DSA Practice	Python 3.12	Pylance, Black formatter

⌨️ Keyboard Shortcuts

Full shortcut system built with a custom useKeyboardShortcuts hook (Ctrl+Alt to avoid VS Code conflicts):

Shortcut	Action
Ctrl+Alt+D	Toggle Dock
Ctrl+Alt+1	Switch to IDE view
Ctrl+Alt+2	Switch to Whiteboard view
Ctrl+Alt+C	Open Chat panel
Ctrl+Alt+U	Open Users panel
Ctrl+/	Show shortcuts dialog
Escape	Close dock/dialog

🏗️ Architecture

graph TD
    %% Styling
    classDef client fill:#10B981,stroke:#059669,stroke-width:2px,color:#fff;
    classDef next fill:#000000,stroke:#333333,stroke-width:2px,color:#fff;
    classDef cloud fill:#2563EB,stroke:#1D4ED8,stroke-width:2px,color:#fff;
    classDef aws fill:#FF9900,stroke:#E68A00,stroke-width:2px,color:#fff;
    classDef socket fill:#6366F1,stroke:#4F46E5,stroke-width:2px,color:#fff;

    subgraph Client ["Client Side (Browser)"]
        User(["Developer / Teammate"])
        UI["Next.js Web UI<br>(React 19 / RTK)"]
        IDE["Embedded OpenVSCode<br>(Iframe)"]
    end

    subgraph AppServer ["Application Hosting"]
        NextJS["Next.js App Server<br>(Vercel / Node.js)"]
        API["API Routes<br>(/api/rooms/*)"]
    end

    subgraph BackendServices ["Backend & Collaboration"]
        Appwrite["Appwrite Cloud<br>(Auth, Database, Storage, Realtime)"]
        SocketIO["Socket.IO Server<br>(Presence, Whiteboard Sync)"]
    end

    subgraph AWSInfra ["AWS Cloud Infrastructure"]
        ECS["AWS ECS Fargate Cluster"]
        Containers["Isolated IDE Containers<br>(Python, Node, Java, C++)"]
        EFS[("AWS EFS<br>(Persistent Volume per Room)")]
    end

    %% Interactions
    User -->|"1. Navigates / Codes"| UI
    UI -->|"2. Authenticates & Fetches Room Metadata"| Appwrite
    UI -->|"3. Connects for Live Collab & Whiteboard"| SocketIO
    
    UI -->|"4. Starts / Stops IDE Container"| NextJS
    NextJS --> API
    API -->|"5. Provisions serverless compute"| ECS
    
    ECS -->|"6. Launches"| Containers
    Containers -->|"7. Mounts workspace files"| EFS
    
    UI -->|"8. Connects directly to IDE instance"| IDE
    IDE -.->|"Accesses running container"| Containers

    %% Class applications
    class User,UI,IDE client;
    class NextJS,API next;
    class Appwrite cloud;
    class ECS,Containers,EFS aws;
    class SocketIO socket;

Loading

Infrastructure

• AWS ECS Fargate — serverless container compute, one task per room

• AWS EFS — shared filesystem, workspace files persist across container restarts

• AWS ECR — private container registry for all language stack images

• Vercel — frontend and API routes deployment

• Appwrite Cloud — auth, database, realtime subscriptions, file storage

📁 Project Structure

stackspace/
├── apps/
│   ├── web/                   # Next.js 16 app (frontend + API)
│   │   ├── src/
│   │   │   ├── app/
│   │   │   │   ├── page.tsx          # Landing page
│   │   │   │   ├── dashboard/        # Room management dashboard
│   │   │   │   ├── room/[roomId]/    # The main collaborative room
│   │   │   │   └── api/
│   │   │   │       ├── rooms/        # Room CRUD, start/stop, status, ping
│   │   │   │       ├── auth/         # Auth endpoints
│   │   │   │       └── cron/         # Idle container cleanup cron
│   │   │   ├── components/
│   │   │   │   ├── room/             # Room UI (Whiteboard, Chat, JoinLobby)
│   │   │   │   ├── dashboard/        # Dashboard components
│   │   │   │   └── ui/               # Shadcn + HeroUI components
│   │   │   ├── templates/stacks.tsx  # All 8 stack definitions + starter files
│   │   │   ├── services/             # Docker, Appwrite service wrappers
│   │   │   ├── store/                # Redux slices (auth, chat)
│   │   │   └── hooks/                # useKeyboardShortcuts, etc.
│   │   └── package.json
│   │
│   └── socket-server/         # Standalone Socket.IO server (TypeScript)
│       └── src/
│           ├── server.ts             # HTTP + Socket.IO server setup
│           ├── socket.ts             # Room events, whiteboard sync
│           └── fileWatcher.ts        # File change notifications
│
├── docker/                    # Custom IDE Docker images per stack
│   ├── Dockerfile.python
│   ├── Dockerfile.nodejs
│   ├── Dockerfile.nextjs
│   ├── Dockerfile.java
│   ├── Dockerfile.cpp
│   └── build-and-push.sh      # Build + push all images to DockerHub & ECR
│
├── infra/                     # AWS infrastructure configuration (ECS, EFS, Security Groups)
│   ├── main.tf
│   ├── variables.tf
│   └── outputs.tf
│
└── assets/
    └── demo.webm              # Project demo video

🧰 Tech Stack

Layer	Technology	Why
Frontend	Next.js 16, React 19, TypeScript	App Router, server components, latest React
Styling	Tailwind CSS v4, HeroUI, Shadcn/UI	Rapid UI with polished components
Animations	Framer Motion / Motion	Smooth transitions and micro-interactions
State	Redux Toolkit	Predictable global state (auth, chat)
Realtime	Socket.IO	Bidirectional WebSocket events
Auth & DB	Appwrite Cloud	Auth, DB, File Storage, Realtime in one
IDE Engine	OpenVSCode Server	The real VS Code, open-source
Containers	Docker + AWS ECS Fargate	Serverless, per-room isolated containers
Storage	AWS EFS	Persistent workspace files, NFS-mounted

| Whiteboard | Excalidraw | Best-in-class collaborative drawing |

| Container Registry | AWS ECR + Docker Hub | Multi-registry image distribution |

🚀 Running Locally

Prerequisites

• Node.js 20+
• Docker (for running the IDE containers locally)
• An Appwrite project (free tier works)

1. Clone & Install

git clone https://github.com/rohankrsingh/stackspace.git
cd stackspace
npm install

2. Configure Environment

cp apps/web/.env.example apps/web/.env.local

Fill in your Appwrite credentials in apps/web/.env.local. See .env.example for all required variables.

3. Start Development Servers

# Start the Next.js app
npm run dev

# In another terminal, start the Socket.IO server
cd apps/socket-server
npm install
npm run dev

The app will be at http://localhost:3000.

Note: For the IDE containers to work locally, Docker must be running. The app falls back gracefully if no containers are available.

☁️ Production Deployment

The original deployment used AWS Fargate for containers and Vercel for the frontend. The free AWS tier has since expired, but the full setup is documented.

High-Level Steps

1. Frontend & API: Deploy apps/web to Vercel
2. Socket Server: Deploy apps/socket-server to any Node.js host (ECS, Railway, Fly.io)
3. AWS Infrastructure: Set up ECS cluster, EFS filesystem, and security groups in AWS
4. Docker Images: Build and push all stack images using docker/build-and-push.sh

See docs/ for detailed architecture notes and deployment guides.

📐 Design Decisions & Technical Highlights

Why AWS Fargate instead of a single Docker host? Each room gets its own compute-isolated Fargate task. This means one user can't affect another room's resources, and there's no port conflict management needed.

Why EFS for workspace storage? Fargate tasks are stateless — EFS provides a persistent NFS volume that survives container restarts and even task replacements, so your code is always there.

Why Socket.IO for whiteboard sync instead of Appwrite Realtime? Lower latency for frequent updates (every canvas change). Appwrite Realtime is used for chat (less frequent, needs persistence) and Socket.IO for whiteboard (high-frequency, low-latency).

Why OpenVSCode Server? It's the open-source core of VS Code (same codebase, open-source extensions via Open-VSX), maintained by Gitpod. It's the most mature self-hostable VS Code solution available.

🧑‍💻 About

Built entirely solo by Rohan Kumar Singh as a full-stack systems project — from custom Docker images to AWS cloud infrastructure to a polished Next.js UI.

This project covers:

• Containerized cloud compute management from a web app
• Real-time multi-user collaboration architecture
• Full-stack TypeScript development (frontend + backend + infra)
• DevOps: Docker image pipelines, AWS ECS, EFS, ECR

📄 License

MIT © 2026 Rohan Kumar Singh