Release/final

.env.example

@@ -0,0 +1,15 @@
+# Example environment variables (DO NOT COMMIT REAL SECRETS)
+
+# Backend (put these on your backend host or in deployment settings)
+DATABASE_URL=file:./dev.db
+JWT_SECRET=replace-with-a-strong-random-secret
+CLIENT_URL=http://localhost:3000
+PORT=5000
+YJS_PORT=1234
+
+# AI provider keys (optional)
+OPENROUTER_API_KEY=
+GEMINI_API_KEY=
+
+# Frontend (public values must be prefixed with NEXT_PUBLIC_)
+NEXT_PUBLIC_API_URL=http://localhost:5001

.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+  workflow_dispatch:
+
+jobs:
+  build-and-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install backend deps
+        run: |
+          npm --prefix backend ci
+
+      - name: Install frontend deps
+        run: |
+          npm --prefix frontend ci
+
+      - name: Build backend
+        run: npm --prefix backend run build
+
+      - name: Lint backend
+        run: npm --prefix backend run lint || true
+
+      - name: Build frontend
+        run: npm --prefix frontend run build
+
+      - name: Lint frontend
+        run: npm --prefix frontend run lint || true
+
+      - name: Audit
+        run: |
+          npm --prefix backend audit --audit-level=high || true
+          npm --prefix frontend audit --audit-level=high || true

DEPLOYMENT.md

@@ -57,8 +57,8 @@ npm run build
 ### Step 3: Set Environment Variables in Railway
 ```
 DATABASE_URL=file:./dev.db
-JWT_SECRET=your-secret-key-123
-JWT_REFRESH_SECRET=refresh-secret-456
+JWT_SECRET=<generate-a-random-secret>
+JWT_REFRESH_SECRET=<generate-a-random-secret>
 PORT=3001
 CLIENT_URL=https://your-frontend-vercel.vercel.app
 ```
@@ -136,8 +136,8 @@ NEXT_PUBLIC_WS_URL=wss://backend-url.com
 ### Backend (.env)
 ```env
 DATABASE_URL="file:./dev.db"  # or PostgreSQL URL
-JWT_SECRET="super-secret-key-123"
-JWT_REFRESH_SECRET="refresh-secret-456"
+JWT_SECRET="<generate-a-random-secret>"
+JWT_REFRESH_SECRET="<generate-a-random-secret>"
 PORT=3001
 CLIENT_URL="https://frontend-url.vercel.app"
 ```

DEPLOYMENT_ENV.md

@@ -0,0 +1,21 @@
+Deployment environment variables
+
+This project requires the following environment variables to run correctly. Add them to your host (Vercel project settings, server `.env`, PM2 `ecosystem.config`, or GitHub Actions secrets) — do NOT commit real secrets to git.
+
+- `DATABASE_URL` : Prisma database connection string. Example: `postgresql://user:pass@db.example.com:5432/collabeditor`. For local dev you can use `file:./dev.db`.
+- `JWT_SECRET` : Secret used to sign JSON Web Tokens for authentication. Provide a strong random string.
+- `CLIENT_URL` : Public URL of the frontend (used by CORS). Example: `https://your-frontend.vercel.app`.
+- `NEXT_PUBLIC_API_URL` : Public API base URL used by the frontend to call the backend (must start with `http(s)://`). Example: `https://api.example.com`.
+- `OPENROUTER_API_KEY` : (optional) API key for OpenRouter AI integration (used in `backend/src/routes/ai.ts`).
+- `GEMINI_API_KEY` : (optional) API key for Gemini/Google AI integration (used in `backend/src/routes/ai.ts`).
+- `YJS_PORT` : (optional) port for the Yjs websocket server (default in code: `1234`).
+- `PORT` : (optional) backend port (default `5000`). Not required on serverless platforms.
+
+Where to set them:
+- Vercel (frontend): go to your Project → Settings → Environment Variables. Add `NEXT_PUBLIC_API_URL` (and any other frontend `NEXT_PUBLIC_` vars) for `Production`, `Preview`, and `Development` environments.
+- Backend host (server/VM/container): place the variables in a `.env` file on the server (read by the backend), or configure them in the service manager (PM2 `ecosystem.config.cjs` `env` section, or systemd unit `Environment=` entries).
+- GitHub Actions: add secrets in the repository Settings → Secrets & variables → Actions. Use them to run CI builds or deployment steps.
+
+Security notes:
+- Never commit real keys. Use `.env.example` (this repo) for placeholders only.
+- Rotate keys if they are accidentally committed or exposed.

DEVELOPER_GUIDE_FOR_FRIEND.md

@@ -0,0 +1,162 @@
+# CollabEditor — Developer Guide (Big Picture)
+
+Purpose: a single-file primer so your friend can understand the project from scratch and run or extend it.
+
+Contents
+- Project overview
+- Architecture & components
+- Key flows (room lifecycle, sockets, cursors)
+- Frontend: pages & important components
+- Backend: routes & socket behavior
+- Local setup and commands
+- Build, test, lint, and deploy
+- Troubleshooting and debugging
+- Remaining tasks to finish for production
+
+---
+
+## 1) Project overview
+
+CollabEditor is a real-time collaborative code editor using:
+- Frontend: Next.js + React + Monaco Editor for code editing.
+- Backend: Express + Socket.IO for real-time events and REST endpoints for auth/rooms/run.
+- Optional: Prisma for DB migrations (schema in `backend/prisma`).
+
+Primary features:
+- Real-time editing (Yjs optional + socket fallbacks)
+- Live cursors and presence
+- Run code (server-side runner)
+- Chat + AI assistant UI
+
+## 2) Architecture & components (big picture)
+
+- `frontend/` (Next.js app)
+  - `app/`: Next app routes and pages (home, login, register, dashboard, room/[slug]).
+  - `app/components/CollabEditor.tsx`: Monaco wrapper, editor options, remote cursor rendering.
+  - `app/hooks/useSocket.ts`: Socket.IO client, emits and listeners for code-change, cursor-move, chat-message, etc.
+  - `app/context/ThemeContext.tsx`: theme provider and persistence.
+  - `app/globals.css`: design tokens and shared styles.
+
+- `backend/` (Express API + Socket.IO)
+  - `src/app.ts`: server bootstrap, CORS, routes, and socket initialization.
+  - `src/socket.ts`: room user tracking, join/leave, code-change, yjs-update, language-change, cursor-move, chat-message handlers.
+  - `src/routes/*`: REST endpoints for auth, rooms, run (code execution sandbox), ai.
+
+## 3) Key flows
+
+- Room join flow:
+  1. Client emits `join-room` with `{ slug, username }`.
+  2. Server stores user in `roomUsers` map and emits `room-users` and `user-joined` to the room.
+
+- Code sync:
+  - Clients emit `code-change` with `{ slug, code }`.
+  - Server forwards `code-change` to others in the room.
+  - Alternatively, Yjs CRDT sync is supported via `yjs-update` events.
+
+- Cursor presence:
+  - Clients emit `cursor-move` with `{ slug, line, column }`.
+  - Server attaches `socketId`, `username`, and `color` and broadcasts `cursor-move` to the room.
+  - Frontend renders remote cursors as Monaco decorations with color and a label.
+
+- Chat:
+  - Clients send `chat-message` with `{ slug, message, username }` and server broadcasts to room.
+
+## 4) Frontend: important files to read first
+- `app/room/[slug]/page.tsx` — room UI orchestration (fetch room meta, wire socket hook, pass props to `CollabEditor`).
+- `app/components/CollabEditor.tsx` — editor mounting, theme registration, remote cursor decorations, emits local cursor events.
+- `app/hooks/useSocket.ts` — socket connection code, events, and helper emitters.
+- `app/context/ThemeContext.tsx` — how theme is persisted and applied.
+
+## 5) Backend: important files to read first
+- `src/socket.ts` — how socket events are wired. Look here to understand cursor handling and room user lifecycle.
+- `src/routes/*` — authenticate, create/join rooms, run code endpoints.
+
+## 6) Local setup (quick)
+
+1. Install dependencies (from repo root):
+
+```bash
+npm --prefix backend install
+npm --prefix frontend install
+```
+
+2. Backend env (create `backend/.env`):
+
+```
+DATABASE_URL=postgres://user:pass@localhost:5432/collab
+JWT_SECRET=<generate-a-random-secret>
+CLIENT_URL=http://localhost:3000
+```
+
+3. Run locally in dev:
+
+```bash
+# start backend (auto-reload)
+npm --prefix backend run dev
+
+# start frontend
+npm --prefix frontend run dev
+```
+
+Open `http://localhost:3000` and test flows.
+
+## 7) Production build & run
+
+- Backend build and start:
+
+```bash
+npm --prefix backend run build
+npm --prefix backend run start
+```
+
+- Frontend build and start (Next.js):
+
+```bash
+npm --prefix frontend run build
+npm --prefix frontend run start
+```
+
+If you deploy with Docker, create `Dockerfile`s for each service and a `docker-compose.yml`.
+
+## 8) Tests, lint, format
+
+- Format backend: `npm --prefix backend run format`
+- Lint backend: `npm --prefix backend run lint` (ensure dev deps installed)
+- Format frontend: `npm --prefix frontend run format`
+- Build frontend: `npm --prefix frontend run build`
+
+## 9) Debugging tips
+
+- Editor not loading: confirm `@monaco-editor/react` is dynamically imported (SSR disabled).
+- Socket connect errors: confirm `NEXT_PUBLIC_API_URL` points to the running backend and CORS allows origin.
+- Cursor missing: ensure backend emits `cursor-move` and frontend `useSocket` receives `onCursorMove` and that `CollabEditor` receives cursor list as prop.
+
+## 10) Security & production hardening
+
+- Remove secrets from source; store them in environment/secret manager.
+- Run `npm audit` and address high/critical vulnerabilities.
+- Lock dependency versions in `package-lock.json` or use `npm ci` in CI.
+
+## 11) Remaining high-priority tasks (finish works)
+
+These are safe, high-impact items you can finish before the interview:
+
+1. Finish frontend production build and verify artifacts (run `npm --prefix frontend run build`).
+2. Run full lint and fix warnings on backend and frontend.
+3. Add Dockerfile + docker-compose for local staging.
+4. Create a seeded demo account and script for your interview demo.
+5. Run `npm audit fix` and review remaining vulnerabilities.
+
+I can finish these for you — tell me which to do first (I recommend finishing the frontend build and creating a demo account).
+
+## 12) Quick demo script for interview (2–3 minutes)
+
+1. Open app, toggle theme to show consistency.
+2. Create a room and copy share link.
+3. Open same room in two windows and show real-time edits and cursors.
+4. Run sample code and show output panel.
+5. Show chat or AI assistant quick suggestion.
+
+---
+
+If your friend wants a walkthrough video or a shorter cheat-sheet, I can generate that too.