From 3ced2979a9588a547a10772cfff19f60ae16352d Mon Sep 17 00:00:00 2001
From: rah7202 <rpidiyar249@gmail.com>
Date: Sat, 4 Apr 2026 18:43:59 +0530
Subject: [PATCH 1/5] fix: removed old readme file

---
 frontend/README.md | 73 ----------------------------------------------
 1 file changed, 73 deletions(-)
 delete mode 100644 frontend/README.md

diff --git a/frontend/README.md b/frontend/README.md
deleted file mode 100644
index 7dbf7eb..0000000
--- a/frontend/README.md
+++ /dev/null
@@ -1,73 +0,0 @@
-# React + TypeScript + Vite
-
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
-
-Currently, two official plugins are available:
-
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
-
-## React Compiler
-
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
-
-## Expanding the ESLint configuration
-
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
-
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
-
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
-```
-
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
-```

From 5b82dcecd36f66aa6f0638538691fd24a75352ae Mon Sep 17 00:00:00 2001
From: rah7202 <rpidiyar249@gmail.com>
Date: Sat, 4 Apr 2026 19:16:52 +0530
Subject: [PATCH 2/5] fix: added a ROOT README file

---
 README.md => ROOT_README.md | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename README.md => ROOT_README.md (100%)

diff --git a/README.md b/ROOT_README.md
similarity index 100%
rename from README.md
rename to ROOT_README.md

From 50c7555eb7b225217e7820c2dcb553e3c070ecf8 Mon Sep 17 00:00:00 2001
From: rah7202 <rpidiyar249@gmail.com>
Date: Sat, 4 Apr 2026 19:19:00 +0530
Subject: [PATCH 3/5] fix: added a ROOT README file

---
 ROOT_README.md | 439 ++++++++++++++++++++++++-------------------------
 1 file changed, 217 insertions(+), 222 deletions(-)

diff --git a/ROOT_README.md b/ROOT_README.md
index 891ae1f..38e5b1a 100644
--- a/ROOT_README.md
+++ b/ROOT_README.md
@@ -1,295 +1,290 @@
-# Smart Code Lab 🧪
+# Smart Code Lab
 
-A real-time collaborative code editor with AI-powered assistance, multi-language support, and version  — built for teams who want to write, run, and review code together.
+> _Code together. Think faster._
 
-![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white)
-![React](https://img.shields.io/badge/React-20232A?style=flat&logo=react&logoColor=61DAFB)
-![Node.js](https://img.shields.io/badge/Node.js-339933?style=flat&logo=node.js&logoColor=white)
-![Prisma](https://img.shields.io/badge/Prisma-2D3748?style=flat&logo=prisma&logoColor=white)
-![Socket.io](https://img.shields.io/badge/Socket.io-010101?style=flat&logo=socket.io&logoColor=white)
+A real-time collaborative code editor with AI-powered assistance. Multiple users can simultaneously write, edit, and debug code in the same room — with live cursor tracking, instant code synchronization, and an AI assistant powered by Google Gemini that streams responses in real-time.
+
+[![CI Pipeline](https://github.com/rah7202/smart-code-lab/actions/workflows/ci.yml/badge.svg)](https://github.com/rah7202/smart-code-lab/actions)
+
+---
+
+## Features
+
+| Feature                        | Description                                                                                                    |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| 🖥️ **Monaco Editor**           | VS Code-quality editor with syntax highlighting, IntelliSense, and custom themes per language                  |
+| 👥 **Real-Time Collaboration** | Multiple users edit simultaneously with live cursor positions and colored name badges                          |
+| 🤖 **AI Assistant (Gemini)**   | Ask Gemini to explain, review, fix, or optimize your code — responses stream in real-time via SSE              |
+| ✂️ **Selection Toolbar**       | Select any code snippet → inline floating toolbar with Explain, Review, Fix, Optimize, and custom Ask actions  |
+| ▶️ **Code Execution**          | Run code directly in the browser (Python, JavaScript, C++, C) via Judge0 API                                   |
+| 📸 **Version History**         | Automatic snapshots on every run + manual save with one-click restore                                          |
+| 🔐 **JWT Authentication**      | Secure signup/signin with bcrypt password hashing and JWT tokens                                               |
+| ⚡ **Redis-Backed State**      | Room state, user presence, and code content stored in Redis for horizontal scaling                             |
+| 🖱️ **Resizable AI Panel**      | Drag to resize the AI output section for a customized workspace                                                |
+| 📥 **Code Download**           | Download your code as a properly named file (e.g., `Rahul-2026-04-04.py`)                                      |
+| 🎨 **Custom Themes**           | Each language has its own color-tuned Monaco theme (blue for Python, amber for JS, purple for C++, teal for C) |
 
 ---
 
-## ✨ Features
+## Supported Languages
 
-- **Real-time collaboration** — Live cursors, user presence, and instant code sync across all users in a room
-- **Multi-language support** — Python, JavaScript, C++, C with per-language syntax themes and starter templates
-- **AI assistance (Gemini Flash 2.5)** — Full code analysis, freeform Q&A, and selection-aware inline toolbar
-- **Code execution** — Run code via Judge0 with stdin support and live output
-- **Version history** — Auto-saved snapshots on every run and Ctrl+S, with one-click restore
-- **Persistent rooms** — Code is saved to the database and reloaded on re-join
-- **Download code** — Auto-named file with username + timestamp
-- **Rate limiting** — Client + server side (5 req/min per user)
+| Language   | Badge | Judge0 ID | Monaco Theme |
+| ---------- | ----- | --------- | ------------ |
+| JavaScript | `JS`  | 63        | Warm amber   |
+| Python     | `PY`  | 71        | Deep blue    |
+| C++        | `C++` | 54        | Purple       |
+| C          | `C`   | 50        | Teal         |
 
 ---
 
-## 🏗️ Architecture
-
-```mermaid
-graph TB
-    subgraph Client ["Frontend (React + TypeScript + Vite)"]
-        direction TB
-        EP["EditorPage"]
-        NB["Navbar"]
-        UP["UserPresenceBar"]
-        ME["Monaco Editor"]
-        ST["SelectionToolbar"]
-
-        subgraph RightSide ["Right Panel"]
-            CI["CodeInputPanel"]
-            AI["AIPanel"]
-            VP["VersionPanel"]
-        end
-
-        subgraph Hooks ["Custom Hooks"]
-            UC["useCollaboration"]
-            UAI["useAI"]
-            UEP["useEditorPersistence"]
-        end
-
-        EP --> NB
-        EP --> UP
-        EP --> ME
-        EP --> ST
-        EP --> RightSide
-        EP --> Hooks
-    end
-
-    subgraph Server ["Backend (Node.js + Express + TypeScript)"]
-        direction TB
-        APP["app.ts"]
-
-        subgraph Routes ["Routes"]
-            AR["ai.route.ts"]
-            CR["compile.route.ts"]
-            RR["room.route.ts"]
-            SR["codeSnapshot.routes.ts"]
-        end
-
-        subgraph Controllers ["Controllers"]
-            AC["ai.controller.ts"]
-            CC["compile.controller.ts"]
-            RC["room.controller.ts"]
-            SC["codeSnapshot.controller.ts"]
-        end
-
-        subgraph Services ["Services"]
-            AS["ai.service.ts"]
-            J0["judge0.service.ts"]
-            RS["room.service.ts"]
-            CSS["codeSnapshot.service.ts"]
-        end
-
-        SOC["socket.ts (Socket.IO)"]
-        DB["prisma.ts (Prisma ORM)"]
-
-        APP --> Routes
-        APP --> SOC
-        Routes --> Controllers
-        Controllers --> Services
-        Services --> DB
-    end
-
-    subgraph External ["External Services"]
-        GEM["Gemini Flash 2.5 API"]
-        J0EXT["Judge0 API"]
-        PG[("PostgreSQL / SQLite")]
-    end
-
-    ME -- "onChange / onMount" --> UC
-    UC -- "socket events" --> SOC
-    SOC -- "cursor-move\ncontent-edited\nusers\ncode-sync" --> UC
-
-    UAI -- "POST /ai/generate" --> AC
-    AC --> AS
-    AS --> GEM
-
-    CI -- "POST /compile" --> CC
-    CC --> J0
-    J0 --> J0EXT
-
-    UEP -- "GET /room/:id\nPOST /room/:id/save\nPOST /snapshot/:id" --> RC
-    RC --> RS
-    RS --> DB
-    DB --> PG
-
-    VP -- "GET /snapshots/:id" --> SC
-    SC --> CSS
-    CSS --> DB
+## Architecture
+
+```
+┌─────────────────────────────────────┐
+│           Frontend (React)          │
+│  ┌──────────┐ ┌──────┐ ┌────────┐  │
+│  │  Monaco   │ │  AI  │ │Version │  │
+│  │  Editor   │ │Panel │ │History │  │
+│  └────┬─────┘ └──┬───┘ └───┬────┘  │
+│       │          │          │       │
+│  ┌────┴──────────┴──────────┴────┐  │
+│  │         Hooks Layer           │  │
+│  │  useCollaboration             │  │
+│  │  useAI (SSE streaming)        │  │
+│  │  useEditorPersistence         │  │
+│  └────┬──────────┬──────────┬────┘  │
+└───────┼──────────┼──────────┼───────┘
+        │ WebSocket│ REST/SSE │ REST
+        │          │          │
+┌───────┼──────────┼──────────┼───────┐
+│       │   Backend (Express)  │      │
+│  ┌────┴────┐ ┌───┴───┐ ┌───┴────┐  │
+│  │Socket.IO│ │  AI   │ │  Room  │  │
+│  │ Server  │ │Service│ │Service │  │
+│  └────┬────┘ └───┬───┘ └───┬────┘  │
+│       │          │          │       │
+│  ┌────┴──────────┴──────────┴────┐  │
+│  │         Data Layer            │  │
+│  │  PostgreSQL       Redis       │  │
+│  │  (Prisma ORM)  (state/adapter)│  │
+│  └───────────────────────────────┘  │
+└─────────────────────────────────────┘
 ```
 
 ---
 
-## 📁 Project Structure
+## Project Structure
 
 ```
-Smart Code Lab/
-├── backend/
-│   ├── prisma/
-│   │   ├── migrations/
-│   │   └── schema.prisma
-│   └── src/
-│       ├── controllers/
-│       │   ├── ai.controller.ts
-│       │   ├── codeSnapshot.controller.ts
-│       │   ├── compile.controller.ts
-│       │   └── room.controller.ts
-│       ├── db/
-│       │   └── prisma.ts
-│       ├── routes/
-│       │   ├── ai.route.ts
-│       │   ├── codeSnapshot.routes.ts
-│       │   ├── compile.route.ts
-│       │   └── room.route.ts
-│       ├── services/
-│       │   ├── ai.service.ts
-│       │   ├── codeSnapshot.service.ts
-│       │   ├── judge0.service.ts
-│       │   └── room.service.ts
-│       ├── sockets/
-│       │   └── socket.ts
-│       ├── types/
-│       │   └── index.ts
-│       ├── app.ts
-│       └── index.ts
-│
-└── frontend/
-    └── src/
-        ├── assets/
-        ├── components/
-        │   ├── AIPanel.tsx
-        │   ├── CodeInputPanel.tsx
-        │   ├── EditorPage.tsx
-        │   ├── Footer.tsx
-        │   ├── Home.tsx
-        │   ├── LanguageBadge.tsx
-        │   ├── Navbar.tsx
-        │   ├── RightPanel.tsx
-        │   ├── SelectionToolbar.tsx
-        │   ├── UserPresenceBar.tsx
-        │   ├── VersionHistory.tsx
-        │   └── VersionPanel.tsx
-        ├── hooks/
-        │   ├── useAI.ts
-        │   ├── useCollaboration.ts
-        │   └── useEditorPersistence.ts
-        ├── languageOptions.ts
-        ├── socket.ts
-        └── App.tsx
+smart-code-lab/
+├── .github/
+│   └── workflows/
+│       └── ci.yml               # CI pipeline (GitHub Actions)
+├── backend/                     # Express API + Socket.IO server
+├── frontend/                    # React + Vite SPA
+├── .gitignore
+└── README.md
 ```
 
 ---
 
-## 🚀 Getting Started
+## Tech Stack
+
+### Frontend
+
+| Technology       | Version | Purpose                           |
+| ---------------- | ------- | --------------------------------- |
+| React            | 19.2    | UI framework                      |
+| Vite             | 8.0     | Build tool & dev server           |
+| TypeScript       | 5.9     | Type safety                       |
+| TailwindCSS      | 4.2     | Utility-first styling             |
+| Monaco Editor    | 4.7     | Code editor (VS Code engine)      |
+| Socket.IO Client | 4.8     | Real-time WebSocket communication |
+| Axios            | 1.13    | HTTP client with interceptors     |
+| React Router DOM | 7.13    | Client-side routing               |
+| React Markdown   | 10.1    | AI response rendering             |
+| Vitest           | 4.1     | Testing framework                 |
+| Testing Library  | 16.3    | Component testing                 |
+
+### Backend
+
+| Technology               | Version | Purpose                           |
+| ------------------------ | ------- | --------------------------------- |
+| Express                  | 5.2     | Web framework                     |
+| TypeScript               | 5.9     | Type safety                       |
+| Prisma                   | 5.22    | ORM for PostgreSQL                |
+| PostgreSQL               | —       | Primary database                  |
+| Redis                    | 5.11    | Session state + Socket.IO adapter |
+| Socket.IO                | 4.8     | Real-time WebSocket server        |
+| @socket.io/redis-adapter | 8.3     | Multi-server pub/sub              |
+| Google Generative AI     | 0.24    | Gemini AI integration             |
+| JSON Web Token           | 9.0     | Authentication                    |
+| Bcrypt                   | 6.0     | Password hashing                  |
+| Zod                      | 4.3     | Request validation                |
+| Helmet                   | 8.1     | Security headers                  |
+| Express Rate Limit       | 8.3     | Rate limiting                     |
+| Jest                     | 30.3    | Testing framework                 |
+| Supertest                | 7.2     | HTTP assertion library            |
+
+---
+
+## Getting Started
 
 ### Prerequisites
 
-- Node.js ≥ 18
-- npm or pnpm
-- A running PostgreSQL instance (or update `schema.prisma` for SQLite)
-- Judge0 API key (self-hosted or RapidAPI)
-- Google Gemini API key
+- **Node.js** ≥ 20
+- **npm** ≥ 9
+- **PostgreSQL** (local or hosted, e.g., Neon)
+- **Redis** (local or hosted, e.g., Render Redis)
+- **Gemini API Key** — [Get one here](https://aistudio.google.com/apikey)
 
-### 1. Clone the repo
+### 1. Clone the Repository
 
 ```bash
 git clone https://github.com/rah7202/smart-code-lab.git
 cd smart-code-lab
 ```
 
-### 2. Backend setup
+### 2. Backend Setup
 
 ```bash
 cd backend
 npm install
 ```
 
-Create a `.env` file:
+Create `backend/.env.local`:
 
 ```env
 DATABASE_URL="postgresql://user:password@localhost:5432/smartcodelab"
-GEMINI_API_KEY="your_gemini_api_key"
-JUDGE0_API_KEY="your_judge0_api_key"
-JUDGE0_BASE_URL="https://judge0-ce.p.rapidapi.com"
-PORT=8000
+GEMINI_API_KEY=your_gemini_api_key
+JWT_SECRET=your_jwt_secret_here_minimum_64_chars
+ALLOWED_ORIGINS=http://localhost:5173
+REDIS_URL=redis://localhost:6379
+LOG_LEVEL=debug
 ```
 
-Run migrations and start:
+Generate Prisma client and run migrations:
 
 ```bash
+npx prisma generate
 npx prisma migrate dev
+```
+
+Start the backend dev server:
+
+```bash
 npm run dev
+# → Server starts on http://localhost:8000
 ```
 
-### 3. Frontend setup
+### 3. Frontend Setup
 
 ```bash
-cd frontend
+cd ../frontend
 npm install
+```
+
+Create `frontend/.env.local`:
+
+```env
+VITE_BACKEND_URL=http://localhost:8000
+```
+
+Start the frontend dev server:
+
+```bash
 npm run dev
+# → App opens on http://localhost:5173
 ```
 
-App runs at `http://localhost:5173`
+### 4. Open the App
+
+1. Navigate to `http://localhost:5173`
+2. Sign up for an account
+3. Create a room or enter an existing Room ID
+4. Start coding!
 
 ---
 
-## 🔌 API Reference
+## Environment Variables
 
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `POST` | `/compile` | Execute code via Judge0 |
-| `POST` | `/ai/generate` | Ask Gemini about code |
-| `DELETE` | `/ai/history/:roomId` | Clear AI chat history |
-| `GET` | `/room/:roomId` | Load room code + language |
-| `POST` | `/room/:roomId/save` | Save current code to room |
-| `POST` | `/snapshot/:roomId` | Save a named snapshot |
-| `GET` | `/snapshots/:roomId` | Get all snapshots for a room |
+### Backend (`backend/.env.local`)
 
-### Socket Events
+| Variable          | Required | Description                                  |
+| ----------------- | -------- | -------------------------------------------- |
+| `DATABASE_URL`    | ✅       | PostgreSQL connection string                 |
+| `GEMINI_API_KEY`  | ✅       | Google Gemini API key                        |
+| `JWT_SECRET`      | ✅       | Secret for signing JWT tokens (min 64 chars) |
+| `ALLOWED_ORIGINS` | ✅       | Comma-separated allowed CORS origins         |
+| `REDIS_URL`       | ✅       | Redis connection string                      |
+| `LOG_LEVEL`       | ❌       | Log level (`debug`, `info`, `warn`, `error`) |
+| `NODE_ENV`        | ❌       | Environment mode                             |
 
-| Event | Direction | Payload | Description |
-|-------|-----------|---------|-------------|
-| `join` | Client → Server | `{ RoomId, username }` | Join a room |
-| `content-edited` | Client ↔ Server | `{ code, language }` | Broadcast code change |
-| `cursor-move` | Client ↔ Server | `{ line, column, username, color, socketId }` | Broadcast cursor position |
-| `code-sync` | Server → Client | `string` | Send existing code to new joiner |
-| `users` | Server → Client | `User[]` | Updated user list with colors |
+### Frontend (`frontend/.env.local`)
+
+| Variable           | Required | Description        |
+| ------------------ | -------- | ------------------ |
+| `VITE_BACKEND_URL` | ✅       | Backend server URL |
 
 ---
 
-## 🛠️ Tech Stack
-
-| Layer | Technology |
-|-------|-----------|
-| Frontend framework | React 18 + TypeScript + Vite |
-| Editor | Monaco Editor (`@monaco-editor/react`) |
-| Styling | Tailwind CSS v4 |
-| Real-time | Socket.IO |
-| Backend | Node.js + Express + TypeScript |
-| ORM | Prisma |
-| Database | PostgreSQL |
-| Code execution | Judge0 API |
-| AI | Google Gemini Flash 2.5 |
-| State management | React hooks (no external lib) |
+## Scripts Reference
+
+### Backend
+
+| Script          | Description                      |
+| --------------- | -------------------------------- |
+| `npm run dev`   | Start dev server with hot reload |
+| `npm run build` | Compile TypeScript to `dist/`    |
+| `npm start`     | Start production server          |
+| `npm test`      | Run tests with coverage report   |
+
+### Frontend
+
+| Script                  | Description                       |
+| ----------------------- | --------------------------------- |
+| `npm run dev`           | Start Vite dev server             |
+| `npm run build`         | Type-check + build for production |
+| `npm test`              | Run tests once                    |
+| `npm run test:coverage` | Run tests with coverage report    |
+| `npm run lint`          | Lint all files                    |
 
 ---
 
-## ⌨️ Keyboard Shortcuts
+## CI/CD Pipeline
 
-| Shortcut | Action |
-|----------|--------|
-| `Ctrl + S` | Save snapshot |
-| `Enter` (in AI input) | Send question to Gemini |
-| `Shift + Enter` | New line in AI input |
+GitHub Actions runs on every push/PR to `main`. Both jobs enforce **70% coverage thresholds** for lines and functions.
+
+```
+backend job:
+  1. Checkout → Setup Node 20 → npm ci (cached)
+  2. npx prisma generate
+  3. npm test -- --coverage --ci
+  4. npm run build
+
+frontend job (runs after backend passes):
+  1. Checkout → Setup Node 20 → npm ci (cached)
+  2. npm run test:coverage
+  3. npm run build
+```
 
 ---
 
-## 🤝 Contributing
+## Future Roadmap
 
-Pull requests are welcome. For major changes, please open an issue first.
+| Feature                     | Priority      | Notes                                                                        |
+| --------------------------- | ------------- | ---------------------------------------------------------------------------- |
+| **Yjs / CRDT Integration**  | 🔵 Next Major | Replace keystroke broadcasting with binary delta sync for better concurrency |
+| **Docker Compose**          | 🟡 Medium     | Redis + PostgreSQL + App in one-command setup                                |
+| **More Languages**          | 🟡 Medium     | Java, Go, Rust, etc.                                                         |
+| **Room Sharing Link**       | 🟢 Easy       | Copy-to-clipboard shareable URL                                              |
+| **AI Context Awareness**    | 🔵 Future     | Pass execution output to Gemini for smarter debugging                        |
+| **JWT Blacklist on Logout** | 🟢 Easy       | `redis.set(blacklist:${token})` with TTL                                     |
 
 ---
 
-## 📄 License
+## Author
+
+**Rahul** — [github.com/rah7202](https://github.com/rah7202)
 
-MIT © [rah7202](https://github.com/rah7202)
+**Repository** — [github.com/rah7202/smart-code-lab](https://github.com/rah7202/smart-code-lab)

From e4f82873007b57189f51a413eb0582e0441ddb58 Mon Sep 17 00:00:00 2001
From: rah7202 <rpidiyar249@gmail.com>
Date: Sat, 4 Apr 2026 19:33:40 +0530
Subject: [PATCH 4/5] fix: Added a FRONTEND README file

---
 frontend/FRONTEND_README.md | 356 ++++++++++++++++++++++++++++++++++++
 1 file changed, 356 insertions(+)
 create mode 100644 frontend/FRONTEND_README.md

diff --git a/frontend/FRONTEND_README.md b/frontend/FRONTEND_README.md
new file mode 100644
index 0000000..23d32c8
--- /dev/null
+++ b/frontend/FRONTEND_README.md
@@ -0,0 +1,356 @@
+# Smart Code Lab — Frontend
+
+React + Vite + TypeScript SPA. Monaco editor with real-time collaboration via Socket.IO, AI-powered code assistance with SSE streaming, and full version history.
+
+---
+
+## File Structure
+
+```
+frontend/
+├── public/
+├── src/
+│   ├── App.tsx                     # Routes: /, /login, /signup, /editor/:roomId
+│   ├── App.css                     # Global styles
+│   ├── main.tsx                    # React entry point
+│   ├── socket.ts                   # Socket.IO client (autoConnect: false)
+│   ├── languageOptions.ts          # 4 languages + custom Monaco themes
+│   ├── components/
+│   │   ├── EditorPage.tsx          # Main editor page — Monaco + all hooks
+│   │   ├── AIPanel.tsx             # AI chat with markdown + SSE rendering + resize
+│   │   ├── CodeInputPanel.tsx      # stdin input + Run + Ask Gemini buttons
+│   │   ├── RightPanel.tsx          # Composes CodeInputPanel + AIPanel + VersionPanel
+│   │   ├── SelectionToolbar.tsx    # Floating toolbar on text selection
+│   │   ├── Navbar.tsx              # Language/theme selectors, save/download/clear
+│   │   ├── UserPresenceBar.tsx     # Colored user badges for room members
+│   │   ├── VersionPanel.tsx        # Toggle for version history
+│   │   ├── VersionHistory.tsx      # Snapshot list with restore
+│   │   ├── LanguageBadge.tsx       # Language indicator badge (PY/JS/C++/C)
+│   │   ├── Home.tsx                # Room create/join + logout
+│   │   ├── LoginPage.tsx           # Sign in form
+│   │   ├── Signup.tsx              # Sign up form
+│   │   └── Footer.tsx              # GitHub link
+│   ├── hooks/
+│   │   ├── useAI.ts                # AI SSE streaming + rate limiting + 3 modes
+│   │   ├── useCollaboration.ts     # Socket.IO collab + cursor decorations
+│   │   └── useEditorPersistence.ts # DB sync, Ctrl+S, beforeunload snapshots
+│   ├── lib/
+│   │   └── authAxios.ts            # Axios instance with JWT interceptor + 401 redirect
+│   ├── utils/
+│   │   ├── auth.ts                 # Token validation + decode helpers
+│   │   └── ProtectedRoute.tsx      # Route guard component
+│   ├── assets/
+│   │   └── geminiLogo.png
+│   └── test/
+│       ├── setup.ts                # jsdom + @testing-library/jest-dom
+│       ├── socket.test.ts
+│       ├── languageOptions.test.ts
+│       ├── __mocks__/
+│       │   └── socket.ts           # Socket.IO mock
+│       ├── components/             # 12 component test files
+│       └── hooks/                  # 3 hook test files
+├── .env.local
+├── vite.config.ts                  # Vite + Vitest config
+├── package.json
+└── tsconfig.json
+```
+
+---
+
+## Architecture
+
+### EditorPage — The Orchestration Hub
+
+`EditorPage.tsx` is the main page component. It owns Monaco, refs, and imperative helpers — but delegates all business logic to three custom hooks:
+
+```
+EditorPage
+│
+├── useEditorPersistence    DB load/save, Ctrl+S, auto-save, beforeunload, download, restore
+├── useCollaboration        Socket connect, code-sync, cursor decorations, emit helpers
+└── useAI                   SSE streaming, rate limiting, chat history, 3 AI modes
+```
+
+### Monaco — Uncontrolled Pattern
+
+Monaco is rendered **without a `value` prop** (uncontrolled). This prevents React from fighting Monaco over content during collaboration.
+
+All updates go through two imperative helpers defined in `EditorPage`:
+
+```typescript
+applyCode(code: string)
+// Sets editor content via editor.setValue()
+// Sets isRemoteUpdate = true first to block onChange re-emit
+
+applyLang(lang: string)
+// Sets Monaco model language + theme without re-mounting
+// Also updates React state (userLang, userLangId) as a mirror
+```
+
+The `onChange` handler only fires for **real user keystrokes** — all programmatic updates are gated by the `isRemoteUpdate` ref.
+
+### Data Flow
+
+```
+User types in Monaco
+      │
+      ▼
+onChange fires (isRemoteUpdate = false)
+      │
+      ├── persistence.handleEditorChange(code, lang)   → debounced DB save
+      └── emitCodeChange({ code, language })           → Socket.IO broadcast
+                                                             │
+                              ┌──────────────────────────────┘
+                              ▼
+                    Other users receive "content-edited"
+                              │
+                              ▼
+                    onCodeChange(code) callback
+                              │
+                              ▼
+                    applyCode(code)              → editor.setValue() with isRemoteUpdate = true
+                    persistence.setUserCode(code) → keeps AI / DB saves in sync
+```
+
+### Auth Flow
+
+```typescript
+// authAxios.ts — shared axios instance
+const api = axios.create({ baseURL: import.meta.env.VITE_BACKEND_URL });
+
+api.interceptors.request.use((config) => {
+  config.headers.Authorization = `Bearer ${localStorage.getItem("token")}`;
+  return config;
+});
+
+api.interceptors.response.use(null, (error) => {
+  if (error.response?.status === 401) {
+    localStorage.removeItem("token");
+    window.location.href = "/login";
+  }
+  return Promise.reject(error);
+});
+```
+
+Login/Signup pages use plain `axios` (not `api`) to avoid the 401 interceptor triggering a redirect loop during authentication failures.
+
+---
+
+## Component Breakdown
+
+| Component            | Responsibility                                                                                                                                           |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **EditorPage**       | Wires Monaco, all three hooks, and child components. Owns `editorRef`, `monacoRef`, `isRemoteUpdate`, `applyCode`, `applyLang`                           |
+| **Navbar**           | Language dropdown (with `LanguageBadge`), theme dropdown, font size slider, save/clear/download buttons, leave room                                      |
+| **UserPresenceBar**  | Renders a colored pill badge for each connected user. Hides when room is empty                                                                           |
+| **RightPanel**       | Wrapper that stacks `CodeInputPanel`, `AIPanel`, and `VersionPanel`                                                                                      |
+| **CodeInputPanel**   | stdin textarea, Run button with loading spinner, Ask Gemini button, rate limit countdown                                                                 |
+| **AIPanel**          | Question input, execution output display, scrollable AI chat with markdown rendering, copy buttons on code blocks, clear chat, resizable via drag handle |
+| **SelectionToolbar** | Appears above selected Monaco text. Quick actions: Explain / Review / Fix / Optimize. Custom "Ask…" input. Shows line count of selection                 |
+| **VersionPanel**     | Toggle button to open/close `VersionHistory`                                                                                                             |
+| **VersionHistory**   | Lists snapshots with relative timestamps. Click any to restore. Fetches from `/api/snapshot/:roomId`                                                     |
+| **LanguageBadge**    | Colored dot + short label (PY / JS / C++ / C) — uses Tailwind classes from `languageOptions.ts`                                                          |
+| **Home**             | Room ID input, Join button, Create Room button (calls `/api/room/create`), logout                                                                        |
+| **LoginPage**        | Username + password form, POSTs to `/api/auth/signin`, stores token in `localStorage`                                                                    |
+| **Signup**           | Username + password form, POSTs to `/api/auth/signup`, stores token in `localStorage`                                                                    |
+| **Footer**           | GitHub icon link                                                                                                                                         |
+
+---
+
+## Custom Hook Details
+
+### `useAI`
+
+Manages all AI interactions with three distinct modes.
+
+**SSE Streaming:**
+
+```typescript
+const res = await fetch(`${URL}/api/ai/stream`, {
+  method: "POST",
+  headers: { Authorization: `Bearer ${token}` },
+  body: JSON.stringify({ prompt, roomId }),
+});
+
+const reader = res.body!.getReader();
+// Reads chunks, parses "data: {...}\n\n" SSE format
+// Updates last history entry on each chunk
+```
+
+**AI Modes:**
+
+| Mode        | Trigger                  | What Gets Sent                              |
+| ----------- | ------------------------ | ------------------------------------------- |
+| `code`      | "Ask Gemini" button      | Full editor code + structured review prompt |
+| `selection` | Selection Toolbar action | Selected snippet + specific action prompt   |
+| `question`  | Text input               | Freeform question — no code injected        |
+
+**Rate Limiting:**
+
+- Client-side 5 requests/60 seconds
+- Timestamps tracked in a ref (`aiTimestamps`)
+- Countdown timer displayed in `CodeInputPanel`
+- Error toast when limit is hit
+
+**History:**
+
+- Fetches existing history from `/api/ai/history/:roomId` on mount
+- Single insertion point: user message + empty AI placeholder added together before streaming starts
+- Streaming updates the last entry in-place — no duplicate insertions
+
+---
+
+### `useCollaboration`
+
+Manages the full Socket.IO lifecycle and cursor decorations.
+
+**Socket Lifecycle:**
+
+```typescript
+useEffect(() => {
+  socket.auth = { token: localStorage.getItem("token") };
+  socket.connect();
+
+  socket.on("connect", () => {
+    socket.emit("join", { RoomId: roomId }); // only after confirmed connected
+  });
+
+  // ... attach all listeners
+
+  return () => {
+    socket.off("connect");
+    // ... remove all listeners
+    socket.disconnect();
+  };
+}, [roomId]);
+```
+
+**Cursor Decorations:**
+
+- Injects `<style>` tags per user with unique `socketId`-based class names
+- Colored cursor line (`border-left`), label (`::before` pseudo-element), and line highlight
+- Cleans up styles and `deltaDecorations` on user disconnect
+- Uses a `Map<socketId, decorationIds[]>` so each user's cursor is tracked independently
+
+**Emit Guard:**
+
+```typescript
+const emitCodeChange = ({ code, language }) => {
+  if (isRemoteUpdate.current) {
+    isRemoteUpdate.current = false;
+    return; // don't re-emit what was just received
+  }
+  socket.emit("content-edited", { code, language });
+};
+```
+
+---
+
+### `useEditorPersistence`
+
+Manages all code saving, loading, and version history.
+
+**Auto-save:** Debounced 2 seconds after each keystroke via `lodash.debounce`. Calls `POST /api/room/:roomId/save`.
+
+**Ctrl+S:** Creates a snapshot via `POST /api/snapshot/:roomId` and bumps `refreshHistory` counter to trigger `VersionHistory` refetch.
+
+**beforeunload:** Uses `fetch({ keepalive: true })` with auth header to save a final snapshot when the tab is closed or navigated away.
+
+**Language Code Map:** Per-language code is stored in a `Record<string, string>`. Switching languages saves the current language's code and restores the new language's previously typed code — or falls back to starter code.
+
+**DB Load:** On mount, fetches room data from `/api/room/:roomId`. Calls the `onLoad(code, lang)` callback so `EditorPage` can apply imperatively via `applyCode` + `applyLang` (avoids race conditions with controlled Monaco).
+
+---
+
+## Language Configuration
+
+Defined in `languageOptions.ts`:
+
+```typescript
+export const languageOptions: LanguageOption[] = [
+  {
+    label: "JavaScript",
+    value: "javascript",
+    monacoLanguage: "javascript",
+    monacoTheme: "js-theme", // warm amber — registered via registerMonacoThemes()
+    badge: { bg: "bg-yellow-400/15", text: "text-yellow-400", label: "JS" },
+    judge0Id: 63,
+    starterCode: "console.log('Welcome to Smart Code Lab!');",
+  },
+  // python, cpp, c follow the same shape
+];
+```
+
+Each language registers a custom Monaco theme with `monaco.editor.defineTheme()` — called once in `handleEditorMount`. The theme includes token color rules (keywords, strings, comments) and editor background/cursor colors.
+
+---
+
+## Setup
+
+### Prerequisites
+
+- Node.js ≥ 20
+- Backend running on `http://localhost:8000`
+
+### Installation
+
+```bash
+npm install
+```
+
+### Environment Variables
+
+Create `.env.local`:
+
+```env
+VITE_BACKEND_URL=http://localhost:8000
+```
+
+### Scripts
+
+| Script                  | Description                                      |
+| ----------------------- | ------------------------------------------------ |
+| `npm run dev`           | Start Vite dev server on `http://localhost:5173` |
+| `npm run build`         | Type-check + build for production                |
+| `npm run preview`       | Preview production build locally                 |
+| `npm test`              | Run all tests once                               |
+| `npm run test:watch`    | Run tests in watch mode                          |
+| `npm run test:coverage` | Run tests with V8 coverage report                |
+| `npm run lint`          | Run ESLint on all files                          |
+
+---
+
+## Testing
+
+**Framework:** Vitest + React Testing Library + jsdom
+
+```bash
+npm run test:coverage
+# Coverage thresholds: 70% lines, 70% functions
+```
+
+### Test Setup
+
+`src/test/setup.ts` imports `@testing-library/jest-dom` for extended matchers. Socket.IO is mocked via `src/test/__mocks__/socket.ts`. Axios is mocked per-test with `vi.mock("axios", () => ({ default: { get: vi.fn(), post: vi.fn() } }))`.
+
+### Test Files
+
+| File                           | What it Tests                                                                                 |
+| ------------------------------ | --------------------------------------------------------------------------------------------- |
+| `AIPanel.test.tsx`             | AI chat rendering, clear chat, markdown display, empty state                                  |
+| `CodeInputPanel.test.tsx`      | Run button states, Ask Gemini button, rate limit indicator                                    |
+| `EditorPage.test.tsx`          | Full page integration — hook wiring, auth guard                                               |
+| `Footer.test.tsx`              | GitHub link rendering                                                                         |
+| `Home.test.tsx`                | Room creation, join validation, logout, navigation                                            |
+| `LanguageBadge.test.tsx`       | Badge label + color for all 4 languages + fallback                                            |
+| `Navbar.test.tsx`              | Language/theme dropdowns, font slider, button handlers                                        |
+| `RightPanel.test.tsx`          | Panel composition and prop forwarding                                                         |
+| `SelectionToolBar.test.tsx`    | Quick action buttons, custom Ask… input, line count display                                   |
+| `UserPresenceBar.test.tsx`     | User badge rendering, colors, empty state                                                     |
+| `VersionHistory.test.tsx`      | Snapshot list rendering, restore on click                                                     |
+| `VersionPanel.test.tsx`        | Open/close toggle                                                                             |
+| `useAI.test.ts`                | SSE streaming, rate limiting, prompt building for all 3 modes, duplicate insertion prevention |
+| `useCollaboration.test.ts`     | Socket events, cursor decoration injection, user list deduplication                           |
+| `useEditorPersistence.test.ts` | Auto-save debounce, Ctrl+S snapshot, restore, download, code map                              |
+| `socket.test.ts`               | Client configuration — autoConnect, transports, reconnection                                  |
+| `languageOptions.test.ts`      | Language config completeness, theme registration                                              |

From 36f2fc919408a92c1102aa00f1a2d7d93970a695 Mon Sep 17 00:00:00 2001
From: rah7202 <rpidiyar249@gmail.com>
Date: Sat, 4 Apr 2026 19:34:17 +0530
Subject: [PATCH 5/5] fix: Added a BACKEND README file

---
 backend/BACKEND_README.md | 562 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 562 insertions(+)
 create mode 100644 backend/BACKEND_README.md

diff --git a/backend/BACKEND_README.md b/backend/BACKEND_README.md
new file mode 100644
index 0000000..1bea843
--- /dev/null
+++ b/backend/BACKEND_README.md
@@ -0,0 +1,562 @@
+# Smart Code Lab — Backend
+
+Express + TypeScript API server with Socket.IO real-time collaboration, Gemini AI integration, PostgreSQL via Prisma, and Redis for scalable state management.
+
+---
+
+## File Structure
+
+```
+backend/
+├── prisma/
+│   ├── schema.prisma               # Database models (User, Room, CodeSnapshot, AIMessage)
+│   └── migrations/                 # Auto-generated migration files
+├── src/
+│   ├── index.ts                    # Entry point — Redis connect → HTTP server → Socket.IO
+│   ├── app.ts                      # Express config — CORS, Helmet, rate limiters, routes
+│   ├── controllers/
+│   │   ├── ai.controller.ts        # AI generate (batch + SSE stream) + history CRUD
+│   │   ├── auth.controller.ts      # Signup + Signin
+│   │   ├── codeSnapshot.controller.ts  # Save + list snapshots
+│   │   ├── compile.controller.ts   # Judge0 code compilation proxy
+│   │   └── room.controller.ts      # Room CRUD + save code
+│   ├── services/
+│   │   ├── ai.service.ts           # Gemini batch + streaming (AsyncGenerator)
+│   │   ├── auth.service.ts         # Bcrypt hash + JWT sign
+│   │   ├── codeSnapshot.service.ts # Deduplicated snapshot saves
+│   │   ├── judge0.service.ts       # Judge0 API proxy
+│   │   └── room.service.ts         # Room creation + lookup
+│   ├── middleware/
+│   │   ├── auth.middleware.ts      # JWT verification middleware
+│   │   └── validate.ts             # Zod schemas + validation middleware
+│   ├── routes/
+│   │   ├── ai.route.ts             # /api/ai/*
+│   │   ├── auth.route.ts           # /api/auth/*
+│   │   ├── codeSnapshot.routes.ts  # /api/snapshot/*
+│   │   ├── compile.route.ts        # /api/compile
+│   │   └── room.route.ts           # /api/room/*
+│   ├── sockets/
+│   │   └── socket.ts               # Socket.IO — Redis adapter, JWT auth, room events
+│   ├── db/
+│   │   ├── prisma.ts               # PrismaClient singleton
+│   │   └── redis.ts                # Redis client + subscriber pair
+│   ├── types/
+│   │   └── index.ts                # Shared TypeScript types
+│   ├── utils/
+│   │   └── logger.ts               # Structured JSON logger
+│   └── __tests__/
+│       ├── app.test.ts             # Integration: health, CORS, rate-limit, helmet
+│       ├── envSetup.ts             # Test environment variables
+│       ├── controllers/
+│       │   ├── ai.controller.test.ts
+│       │   └── compile.controller.test.ts
+│       ├── middleware/
+│       │   └── validate.middleware.test.ts
+│       └── services/
+│           ├── ai.service.test.ts
+│           ├── codeSnapshot.service.test.ts
+│           ├── judge0.service.test.ts
+│           └── room.service.test.ts
+├── .env.local
+├── jest.config.ts
+├── package.json
+└── tsconfig.json
+```
+
+---
+
+## Architecture
+
+### Request Flow
+
+```
+Client Request
+      │
+      ▼
+ Helmet (security headers)
+      │
+      ▼
+ CORS (origin allowlist)
+      │
+      ▼
+ Rate Limiter (global: 100/min, AI: 10/min)
+      │
+      ▼
+ Body Parser (50KB limit)
+      │
+      ▼
+ authenticate middleware (JWT verify)
+      │
+      ▼
+ validate middleware (Zod schema)
+      │
+      ▼
+ Controller → Service → Prisma/Redis
+      │
+      ▼
+ JSON Response
+```
+
+### Socket.IO Flow
+
+```
+WebSocket Handshake
+      │
+      ▼
+ JWT Middleware (socket.handshake.auth.token)
+      │
+      ▼
+ io.on("connection")
+      │
+      ├── "join"           → validate room exists → add user to Redis → broadcast users list
+      ├── "content-edited" → store in Redis → broadcast to room
+      ├── "cursor-move"    → enrich with username/color from Redis → broadcast to room
+      └── "disconnect"     → remove from Redis → broadcast updated users list
+```
+
+### Redis Architecture
+
+Room state is stored entirely in Redis, enabling horizontal scaling via the `@socket.io/redis-adapter`:
+
+```
+Redis Keys:
+  socket:{socketId}:room          → String  (maps socket to room)
+  room:{roomId}:users             → Hash    (socketId → user JSON)
+  room:{roomId}:content           → String  (serialized {code, language})
+```
+
+When multiple backend instances run, Socket.IO events are pub/sub'd across all instances via the Redis adapter — any user in any room receives updates regardless of which server they're connected to.
+
+---
+
+## Setup
+
+### Prerequisites
+
+- Node.js ≥ 20
+- PostgreSQL (local or Neon)
+- Redis (local or Render)
+- Gemini API Key from [Google AI Studio](https://aistudio.google.com/apikey)
+
+### Installation
+
+```bash
+npm install
+```
+
+### Environment Variables
+
+Create `.env.local`:
+
+```env
+DATABASE_URL="postgresql://user:password@localhost:5432/smartcodelab"
+GEMINI_API_KEY=your_gemini_api_key
+JWT_SECRET=your_jwt_secret_minimum_64_chars
+ALLOWED_ORIGINS=http://localhost:5173
+REDIS_URL=redis://localhost:6379
+LOG_LEVEL=debug
+NODE_ENV=development
+```
+
+| Variable          | Required | Description                                              |
+| ----------------- | -------- | -------------------------------------------------------- |
+| `DATABASE_URL`    | ✅       | PostgreSQL connection string                             |
+| `GEMINI_API_KEY`  | ✅       | Google Gemini API key                                    |
+| `JWT_SECRET`      | ✅       | Secret for signing JWT tokens (min 64 chars recommended) |
+| `ALLOWED_ORIGINS` | ✅       | Comma-separated allowed CORS origins                     |
+| `REDIS_URL`       | ✅       | Redis connection string                                  |
+| `LOG_LEVEL`       | ❌       | `debug` / `info` / `warn` / `error`                      |
+| `NODE_ENV`        | ❌       | `development` / `production` / `test`                    |
+
+### Database Setup
+
+```bash
+# Generate Prisma client
+npx prisma generate
+
+# Run migrations
+npx prisma migrate dev
+
+# (Optional) Open Prisma Studio
+npx prisma studio
+```
+
+### Scripts
+
+| Script                    | Command                                               | Description                      |
+| ------------------------- | ----------------------------------------------------- | -------------------------------- |
+| `npm run dev`             | `ts-node-dev --respawn --transpile-only src/index.ts` | Start dev server with hot reload |
+| `npm run build`           | `tsc`                                                 | Compile TypeScript to `dist/`    |
+| `npm start`               | `node dist/index.js`                                  | Start production server          |
+| `npm test`                | `jest --coverage`                                     | Run tests with coverage          |
+| `npm run prisma:generate` | `prisma generate`                                     | Regenerate Prisma client         |
+
+---
+
+## API Reference
+
+All protected routes require the header:
+
+```
+Authorization: Bearer <jwt_token>
+```
+
+---
+
+### Authentication
+
+#### `POST /api/auth/signup`
+
+Create a new user account.
+
+**Request body:**
+
+```json
+{ "username": "rahul", "password": "mypassword" }
+```
+
+**Validation:** username 3–30 chars, password min 6 chars
+
+**Response `201`:**
+
+```json
+{ "token": "eyJhbGciOiJIUzI1NiIs..." }
+```
+
+---
+
+#### `POST /api/auth/signin`
+
+Sign in with existing credentials.
+
+**Request body:**
+
+```json
+{ "username": "rahul", "password": "mypassword" }
+```
+
+**Response `200`:**
+
+```json
+{ "token": "eyJhbGciOiJIUzI1NiIs..." }
+```
+
+---
+
+### Rooms 🔒
+
+#### `GET /api/room/:roomId`
+
+Load room data.
+
+**Response `200`:**
+
+```json
+{
+  "roomId": "abc-123",
+  "language": "javascript",
+  "code": "console.log('hello')"
+}
+```
+
+**Response `404`:** Room not found.
+
+---
+
+#### `POST /api/room/create`
+
+Create a new room (owned by the authenticated user).
+
+**Response `200`:**
+
+```json
+{ "roomId": "generated-uuid" }
+```
+
+---
+
+#### `POST /api/room/:roomId/save`
+
+Save the current code to the room. Only the room owner can save.
+
+**Request body:**
+
+```json
+{ "code": "print('hello')", "language": "python" }
+```
+
+**Validation:** `language` must be one of `javascript | python | cpp | c`
+
+**Response `200`:**
+
+```json
+{ "success": true }
+```
+
+**Response `403`:** Not the room owner.
+
+---
+
+### Code Execution 🔒
+
+#### `POST /api/compile`
+
+Execute code via the Judge0 API.
+
+**Request body:**
+
+```json
+{
+  "code": "print('hello')",
+  "userLangId": 71,
+  "input": ""
+}
+```
+
+| Field        | Type   | Description                                         |
+| ------------ | ------ | --------------------------------------------------- |
+| `code`       | string | 1–50,000 chars                                      |
+| `userLangId` | number | Judge0 language ID (63=JS, 71=Python, 54=C++, 50=C) |
+| `input`      | string | Optional stdin, max 10,000 chars                    |
+
+**Response `200`:**
+
+```json
+{
+  "output": "hello\n",
+  "status": { "id": 3, "description": "Accepted" },
+  "time": "0.01"
+}
+```
+
+---
+
+### AI 🔒 (Rate limited: 10 req/min per IP)
+
+#### `POST /api/ai/generate`
+
+Generate AI response as a complete batch response.
+
+**Request body:**
+
+```json
+{ "prompt": "Explain this code...", "roomId": "abc-123" }
+```
+
+**Response `200`:**
+
+```json
+{ "success": true, "data": "## 🔍 Explanation\nThis code..." }
+```
+
+Saves both the user prompt and AI response to `AIMessage` table.
+
+---
+
+#### `POST /api/ai/stream`
+
+Stream AI response via Server-Sent Events (SSE).
+
+Same request body as `/generate`. Response is a chunked stream:
+
+```
+data: {"chunk":"## 🔍 "}
+
+data: {"chunk":"Explanation\n"}
+
+data: {"chunk":"This code does..."}
+
+data: {"done":true}
+```
+
+Each chunk is a JSON-encoded object on a `data:` line, separated by `\n\n`.
+
+---
+
+#### `GET /api/ai/history/:roomId`
+
+Get all AI chat messages for a room, ordered by `createdAt asc`.
+
+**Response `200`:**
+
+```json
+[
+  {
+    "id": "...",
+    "role": "user",
+    "content": "Explain this",
+    "createdAt": "..."
+  },
+  { "id": "...", "role": "ai", "content": "## 🔍 ...", "createdAt": "..." }
+]
+```
+
+---
+
+#### `DELETE /api/ai/history/:roomId`
+
+Clear all AI chat history for a room.
+
+**Response `200`:**
+
+```json
+{ "success": true }
+```
+
+---
+
+### Snapshots 🔒
+
+#### `POST /api/snapshot/:roomId`
+
+Save a code snapshot (version checkpoint). Skips save if code and language are identical to the last snapshot.
+
+**Request body:**
+
+```json
+{ "code": "print('hi')", "language": "python" }
+```
+
+**Response `201`:**
+
+```json
+{ "id": "snapshot-uuid", "createdAt": "2026-04-04T10:00:00Z" }
+```
+
+---
+
+#### `GET /api/snapshot/:roomId`
+
+Get all snapshots for a room, ordered newest first.
+
+**Response `200`:**
+
+```json
+[{ "id": "...", "code": "...", "language": "python", "createdAt": "..." }]
+```
+
+---
+
+## Socket.IO Events
+
+Connection requires a JWT token in the socket handshake:
+
+```typescript
+const socket = io("http://localhost:8000", {
+  auth: { token: localStorage.getItem("token") },
+  transports: ["websocket"],
+});
+```
+
+### Client → Server
+
+| Event            | Payload                              | Description                                            |
+| ---------------- | ------------------------------------ | ------------------------------------------------------ |
+| `join`           | `{ RoomId: string }`                 | Join a room — triggers user list broadcast + code sync |
+| `content-edited` | `{ code: string, language: string }` | Broadcast code changes to room on every keystroke      |
+| `cursor-move`    | `{ line: number, column: number }`   | Broadcast cursor position to room                      |
+
+### Server → Client
+
+| Event            | Payload                                       | Description                                       |
+| ---------------- | --------------------------------------------- | ------------------------------------------------- |
+| `users`          | `User[]`                                      | Updated user list `{ username, color, socketId }` |
+| `code-sync`      | `string`                                      | Initial code sync when a user joins a room        |
+| `content-edited` | `{ code, language }`                          | Code update from a collaborator                   |
+| `cursor-move`    | `{ line, column, username, color, socketId }` | Cursor position from a collaborator               |
+| `error`          | `string`                                      | Error message (e.g., `"Room does not exist"`)     |
+
+---
+
+## Database Schema
+
+```prisma
+model User {
+  id        String   @id @default(uuid())
+  username  String   @unique
+  password  String
+  createdAt DateTime @default(now())
+  rooms     Room[]
+}
+
+model Room {
+  id        String        @id @default(uuid())
+  language  String
+  code      String        @db.Text
+  createdAt DateTime      @default(now())
+  userId    String
+  user      User          @relation(fields: [userId], references: [id])
+  snapshots CodeSnapshot[]
+  aiMessages AIMessage[]
+  @@index([userId])
+}
+
+model CodeSnapshot {
+  id        String   @id @default(uuid())
+  roomId    String
+  room      Room     @relation(fields: [roomId], references: [id])
+  code      String   @db.Text
+  language  String
+  createdAt DateTime @default(now())
+  @@index([roomId])
+}
+
+model AIMessage {
+  id        String   @id @default(uuid())
+  roomId    String
+  room      Room     @relation(fields: [roomId], references: [id])
+  role      String   // "user" | "ai"
+  content   String   @db.Text
+  createdAt DateTime @default(now())
+  @@index([roomId])
+}
+```
+
+**Relationships:**
+
+```
+User (1) ──→ (N) Room
+Room (1) ──→ (N) CodeSnapshot
+Room (1) ──→ (N) AIMessage
+```
+
+---
+
+## Security
+
+| Layer                | Implementation                                                                                   |
+| -------------------- | ------------------------------------------------------------------------------------------------ |
+| **Authentication**   | JWT tokens (7-day expiry) — `jsonwebtoken` + `bcrypt` password hashing                           |
+| **Authorization**    | `authenticate` middleware on all protected routes + room owner checks                            |
+| **Input Validation** | Zod schemas on all mutation endpoints — invalid requests return `400` before hitting controllers |
+| **Rate Limiting**    | Global: 100 req/min per IP — AI routes: additional 10 req/min per IP                             |
+| **CORS**             | Origin allowlist from `ALLOWED_ORIGINS` — rejects all unlisted origins                           |
+| **Security Headers** | Helmet (CSP, HSTS, X-Frame-Options, X-Content-Type-Options, etc.)                                |
+| **Body Limit**       | 50KB JSON body limit                                                                             |
+| **Socket Auth**      | JWT verification on WebSocket handshake before any room events are processed                     |
+
+---
+
+## Testing
+
+**Framework:** Jest + Supertest + ts-jest
+
+```bash
+# Run all tests with coverage
+npm test
+
+# Coverage thresholds: 70% lines, 70% functions
+```
+
+Test environment variables are set in `src/__tests__/envSetup.ts` — `JWT_SECRET`, `NODE_ENV=test`, and `DATABASE_URL` are all provided so no real database is needed (Prisma is mocked).
+
+| Test File                      | What it Tests                                                         |
+| ------------------------------ | --------------------------------------------------------------------- |
+| `app.test.ts`                  | Health check, CORS allowlist/rejection, rate limiting, Helmet headers |
+| `ai.controller.test.ts`        | Generate, stream, history CRUD — Prisma and AI service mocked         |
+| `compile.controller.test.ts`   | Judge0 proxy — accepted/error/timeout cases                           |
+| `validate.middleware.test.ts`  | All Zod schemas — valid inputs, edge cases, enum rejection            |
+| `ai.service.test.ts`           | Gemini SDK mock — prompt validation, error propagation                |
+| `codeSnapshot.service.test.ts` | Deduplication logic, DB create/find                                   |
+| `judge0.service.test.ts`       | Judge0 API proxy — response parsing                                   |
+| `room.service.test.ts`         | Room CRUD — create, find, authorization                               |