diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..e08ce19 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Anuraj Jit Saikia + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index e78deb3..687278e 100644 --- a/README.md +++ b/README.md @@ -1,383 +1,223 @@ -# A-Meet - -> A full-stack video conferencing platform built from scratch — not a tutorial, not a template. - -A-Meet is a production-grade Google Meet alternative engineered with a real SFU (Selective Forwarding Unit), end-to-end auth, scheduled meetings, and a handcrafted UI. Built as a deep-dive learning project to understand exactly how platforms like Google Meet, Whereby, and Daily.co work under the hood — and then build one. - ---- - -## Why A-Meet instead of just... using Google Meet? - -Google Meet is a product. A-Meet is an understanding. - -Most "video calling" tutorials stop at a 2-person WebRTC peer connection. A-Meet goes further: - -| What Google Meet hides | What A-Meet exposes | -|---|---| -| The SFU routing every stream | mediasoup running in your own process — you can read every line | -| Simulcast + layer switching | Three spatial layers × L3 temporal per camera, SFU sheds layers per-viewer's downlink | -| Audio priority over video | `consumer.setPriority(255)` on every audio consumer — voice survives bandwidth drops | -| Presence & reconnect handling | `join-room` re-emitted on every socket reconnect; grace-window debounce kills churn noise | -| Per-person volume | Discord-style per-tile volume slider — independent of master volume | -| Mic gain | GainNode always in the signal chain (Google Meet / Discord model) — fully synchronous, no `replaceTrack` races | -| Auto Picture-in-Picture | Canvas composites all tiles; `requestPictureInPicture` on tab hide, auto-close on return | -| Observability | Grafana + Loki + Promtail wired to structured server logs — watch SFU events in real time | - -You can self-host it, read every line, break it, and understand why it broke. That's the point. - ---- - -## Feature Set - -### Core call -- **Google OAuth → JWT** auth (httpOnly cookie, zero client-side token storage) -- **mediasoup SFU** — scales beyond 2 peers; the same architecture used by production conferencing platforms -- **Simulcast** (3 spatial layers × L1T3 temporal) — video degrades gracefully on bad connections; audio stays -- **Screen sharing** with multi-share support, name attribution, and presentation layout -- **Auto Picture-in-Picture** — tab switch opens a mini player; returning closes it - -### Audio / Video controls -- Master output volume (all remote peers) -- Per-participant output volume (Discord-style hover slider) -- Mic input gain via GainNode (no `replaceTrack`, no races) -- Camera + mic device switching mid-call -- Speaking indicator — level-reactive pulsing ring via `AnalyserNode` (no audio feedback) - -### In-call UX -- Emoji reactions — per-tile popup + Google Meet-style floating emoji stream -- Raise hand with visual indicator across all layouts -- Chat panel with unread badge -- Screenshot to clipboard (canvas composite of all visible tiles, with download fallback) -- "Stop presenting" header chip (matches Google Meet top-bar behaviour) -- Auto-hide control bar during screen share; hover to reveal; pin/unpin toggle -- RTC stats overlay for debugging -- Shared English transcript — each browser streams only its own microphone as 16 kHz PCM; - Deepgram Nova-3 supplies background transcription and Groq Whisper refines completed turns -- Background meeting transcription + reconnect-safe transcript panel; every participant can download the same - canonical `.txt` transcript (ephemeral in v1, not saved to MongoDB) - -### Meetings -- Schedule future meetings with title, date/time, and shareable invite link -- Upcoming meetings list on landing page -- Lobby shows meeting title and scheduled time when joining a scheduled meeting -- Post-login redirect — invited users land back on the meeting after signing in - -### Infrastructure -- **Docker Compose** — MongoDB, Promtail, Loki, Grafana all in one command -- **TURN server** support (coturn config included) -- **EC2-aware announced IP** — auto-detects public IPv4 via IMDSv2 on deploy; actionable error off-EC2 -- **Structured logging** — Pino JSON; local → Promtail/Loki/Grafana, production → CloudWatch - ---- - -## Stack - -| Layer | Technology | -|---|---| -| Frontend | React (Vite) + Material UI + Socket.io-client | -| Backend | Node.js + Express + Socket.io | -| Database | MongoDB + Mongoose | -| Media | mediasoup (SFU) | -| Auth | Passport `google-oauth20` → JWT (httpOnly cookie) | -| Validation | Joi (API) + Mongoose (schema) | -| Observability | Local: Grafana + Loki + Promtail · Production: CloudWatch + SNS/Telegram | -| Infra | Docker Compose + coturn | - ---- - -## Getting Started - -### Prerequisites -- Node.js 20+ -- Docker + Docker Compose -- A Google OAuth app (Client ID + Secret) - -### 1. Clone and install -```bash -git clone https://github.com/Anuraj-dev/A-Meet.git -cd A-Meet -npm install -npm --prefix client install -npm --prefix server install -``` +
+
+
+ Video calls in the style of Google Meet, running on a server you control.
+ Sign in with Google, share a meeting link, and the media runs through a mediasoup SFU you host.
+
+ Live demo + · + Run it locally + · + Configuration + · + Deployment +
-`docker compose` reads the **repo-root `.env`** for the Mongo container credentials, so those -live there — not in `server/.env`. Keep the two in sync: the username/password in the root -`.env` must match the ones embedded in the server's `MONGO_URI` (both default to -`admin` / `change-me`). +A-Meet is a video call app. You sign in with Google, click "New meeting", and send the link. Everyone who opens the link signs in, waits in the lobby, and joins the room. The room has camera and microphone controls, screen share with optional tab audio, chat, emoji reactions, raise hand, a Picture-in-Picture mini player, and a shared transcript. -The **`client/.env`** supplies `VITE_SERVER_URL` — the origin the browser opens the Socket.io -connection to. There is no built-in fallback, so on a fresh clone signaling silently fails to -connect until this file exists; the default points at the local server (`http://localhost:5000`). +The API server is Express and Socket.io. It starts mediasoup worker subprocesses for the media, so audio and video pass through the machine you run it on. You need MongoDB, a Google OAuth client, and a JWT secret. Transcription also needs Deepgram and Groq API keys. Without a Deepgram key, the server logs a warning and transcription stays unavailable. -Repo-root `.env` (local Docker Mongo only — unused in production): +## What you get -```env -MONGO_ROOT_USERNAME=admin -MONGO_ROOT_PASSWORD=change-me -``` +- **Calls run through a mediasoup SFU.** Each browser uploads its camera at three resolutions, a quarter, half and full size, capped at 200, 500 and 1500 kbps. The SFU forwards to each viewer the layer that fits their connection, without decoding or re-encoding. Audio consumers get priority 255, so voice keeps its share of bandwidth when video layers drop. +- **A shared transcript from each speaker's own microphone.** The meeting admin starts the transcript, and each participant's browser sends its microphone as 16 kHz PCM. Deepgram Nova-3 streams English text while people talk. When a turn ends, Groq Whisper transcribes it again, and a second Groq model merges the two results when they differ. The panel shows finals only. Anyone in the room can download the transcript as a `.txt` file. The server keeps it in memory and drops it six hours after the last participant leaves. Nothing goes to MongoDB. +- **Google sign-in with an httpOnly cookie.** Passport's Google OAuth strategy creates or updates the user, and the server sets a JWT in the `ameet_token` cookie for 7 days. Page scripts cannot read the cookie. Socket connections check the same cookie during the handshake. +- **Scheduled meetings with calendar links.** You schedule a meeting with a title and a time. It appears in the upcoming list on the landing page, and the lobby shows the scheduled time. Each meeting also gets an "Add to Google Calendar" link. +- **Admin controls.** The meeting admin can mute one participant or everyone, remove a participant, spotlight a speaker, and end the meeting. Muting pauses the participant's producer on the server. Nobody is switched back on. A muted participant can only ask to unmute. +- **In-call audio and video tools.** Each participant has a volume slider, and the call has a master output volume. Mic gain runs through a GainNode, and a speaking ring follows an AnalyserNode. The chat panel has an unread badge, reactions float over the call, and the layout chooser switches between auto, tiled, spotlight and sidebar. +- **Picture-in-Picture and structured logs.** Auto Picture-in-Picture opens a mini player when the tab is hidden and closes it when you come back. The app draws all camera tiles onto a canvas and sends that canvas to a hidden video element, so it works only in Chromium-based browsers. The server writes Pino JSON logs with fields such as `roomId` and `socketId`. `/api/health` reports liveness, and `/api/health/ready` returns 503 when MongoDB is down or a mediasoup worker has died. -Open `server/.env` and fill in: +## Running it locally -```env -# MongoDB — local dev points at the Docker Mongo container; credentials must match -# the repo-root .env above. In production, set MONGO_URI to your Atlas SRV string -# instead (see Deployment). -MONGO_URI=mongodb://admin:change-me@localhost:27017/ameet?authSource=admin - -# Auth -GOOGLE_CLIENT_ID=your_google_client_id -GOOGLE_CLIENT_SECRET=your_google_client_secret -JWT_SECRET=a_long_random_string -CLIENT_URL=http://localhost:5173 -SERVER_URL=http://localhost:5000 +You need Node.js 22.13 or newer, Docker with Compose, and a Google OAuth client. In the Google Cloud console, add `http://localhost:5000/api/auth/google/callback` as an authorized redirect URI. -# mediasoup -MEDIASOUP_ANNOUNCED_IP= # leave blank on localhost; set to EC2 public IP on deploy - -# Session -SESSION_SECRET=another_long_random_string -``` +### Clone and install -To get a Google OAuth client: -1. Go to [Google Cloud Console](https://console.cloud.google.com/) -2. Create a project → APIs & Services → Credentials → Create OAuth 2.0 Client ID -3. Authorized redirect URI: `http://localhost:5000/auth/google/callback` - -### 3. Start infrastructure (local dev) -```bash -npm run docker:up +```sh +git clone https://github.com/Anuraj-dev/A-Meet.git +cd A-Meet +npm install ``` -This starts the **local development** stack from `docker-compose.yml`: MongoDB (27017), -mongo-express (8081), Loki (3100), Promtail, and Grafana (3000). This is the one documented -way to run MongoDB locally for offline/full-stack work. +The root `package.json` declares the client, server, shared, bot and e2e packages as npm workspaces, so one install covers all of them. -> **Dev vs production database:** the local Mongo container above is for development only. -> In production the database is **MongoDB Atlas** (set `MONGO_URI` to the Atlas connection -> string) and no Mongo container runs on the server — see [Deployment](#deployment-ec2-containerized). +### Create the environment files -### 4. Run the app -```bash -npm run dev +```sh +cp .env.example .env # Docker Compose: local MongoDB credentials +cp server/.env.example server/.env # API server +cp client/.env.example client/.env # Vite client ``` -- **Client:** http://localhost:5173 -- **Server:** http://localhost:5000 -- **Grafana (logs):** http://localhost:3000 -- **mongo-express:** http://localhost:8081 +Set these values in `server/.env`: -### 5. Create a meeting -1. Sign in with Google -2. Click **New meeting** on the landing page -3. Share the link with anyone — they sign in and land directly in the meeting +```env +MONGO_URI=mongodb://admin:change-me@localhost:27017/ameet?authSource=admin +JWT_SECRET=a-long-random-string +GOOGLE_CLIENT_ID=your-google-client-id +GOOGLE_CLIENT_SECRET=your-google-client-secret +``` ---- +The credentials in `MONGO_URI` must match `MONGO_ROOT_USERNAME` and `MONGO_ROOT_PASSWORD` in the root `.env`. Both default to `admin` and `change-me`. Change them before you use the stack for anything real. -## Linting & tests +In `client/.env`, set `VITE_SERVER_URL=http://localhost:5000`. Without it, the client has no signaling server to reach, and calls never connect. -Each package has its own ESLint flat config (ESLint 10) and test suite. The same -commands run locally and in CI: +To enable transcription, add `DEEPGRAM_API_KEY` and `GROQ_API_KEY` to `server/.env`. -```bash -# Server (Express + Socket.io + mediasoup) -npm --prefix server run lint # ESLint over src/, test/, and config files -npm --prefix server test # Vitest +### Start the stack -# Client (React + Vite) -npm --prefix client run lint -npm --prefix client test +```sh +npm run docker:up +npm run dev ``` -The server lint config (`server/eslint.config.js`) uses Node globals for source and -Vitest globals for `test/**`, and ignores generated/dependency dirs -(`node_modules`, `logs`, `coverage`, `dist`). `npm --prefix server run lint` exits zero -on a clean checkout and runs as a CI gate. +`docker:up` starts MongoDB on 27017, mongo-express on 8081, Loki on 3100, and Grafana on 3000. `dev` starts the API on port 5000 and the Vite client on port 5173. -### Full pre-merge suite +Open http://localhost:5173, sign in with Google, and click "New meeting". To test with a second participant, open the same link in another browser window. The default announced IP, `127.0.0.1`, works when every tab runs on the same machine. -Run the CI gates that fire on every PR in one command: +## Configuration -```bash -# One-time: download Playwright browsers (not part of npm ci) -npm run test:e2e:install +The server reads `server/.env`, and the client reads `client/.env`. The server exits at startup if `MONGO_URI` or `JWT_SECRET` is missing. -# lint (server + client) → npm audit (server + client) → typecheck → unit/coverage → client build → E2E smoke -npm run verify -``` +### Server -`verify` fails fast — the first failing phase stops the run. It mirrors the CI jobs that -run on every PR: `Server lint`, `Client lint`, `npm audit (high)`, `Workspaces typecheck`, -`Client tests + build`, `Server tests` (coverage ratchet), and the `Playwright smoke`. It does **not** run -the path-scoped `Server image smoke` (a ~15-min Docker build that spawns a real mediasoup -worker), which CI runs only when server-image files change. A green `verify` locally means -those every-PR gates are satisfied. +| Variable | Default | What it does | +| --- | --- | --- | +| `MONGO_URI` | none, required | MongoDB connection string. | +| `JWT_SECRET` | none, required | Signs the session JWT. | +| `JWT_EXPIRES_IN` | `7d` | JWT lifetime. | +| `GOOGLE_CLIENT_ID` | empty | Google OAuth client. Without it, login stays disabled. | +| `GOOGLE_CLIENT_SECRET` | empty | Google OAuth client secret. | +| `CLIENT_URL` | `http://localhost:5173` | Where the server sends the browser after login. Also the CORS origin. | +| `SERVER_URL` | `http://localhost:5000` | Base URL for the OAuth callback. | +| `PORT` | `5000` | HTTP and Socket.io port. | +| `MEDIASOUP_ANNOUNCED_IP` | `127.0.0.1` | Address advertised to browsers for media. See [How the SFU works](#how-the-sfu-works). | +| `MEDIASOUP_MIN_PORT` | `40000` | Start of the RTC port range. Open it in the firewall. | +| `MEDIASOUP_MAX_PORT` | `40100` | End of the RTC port range. | +| `MEDIASOUP_NUM_WORKERS` | CPU core count | Number of mediasoup worker subprocesses. | +| `DEEPGRAM_API_KEY` | empty | Enables live transcription. | +| `GROQ_API_KEY` | empty | Enables the Groq re-transcription and merge step. | +| `DEEPGRAM_TRANSCRIPTION_MODEL` | `nova-3` | Deepgram model. | +| `GROQ_TRANSCRIPTION_MODEL` | `whisper-large-v3` | Groq Whisper model. | +| `GROQ_TRANSCRIPT_MERGE_MODEL` | `qwen/qwen3.6-27b` | Groq model that merges the two transcripts. | +| `DISCORD_BOT_API_KEY` | empty | Shared key the Discord bot sends. Empty disables the integration. | +| `DISCORD_LINK_TOKEN_TTL` | `10m` | Lifetime of the Discord account link token. | +| `LOG_LEVEL` | `debug` in development, `info` in production | Pino log level. | ---- +Rate limits have generous defaults in `server/src/config/env.ts`. The `RATE_LIMIT_*` variables in `server/.env.example` override them. -## Project Structure +### Client -``` -A-Meet/ -├── client/ # React (Vite) frontend -│ └── src/ -│ ├── pages/ # LandingPage, LobbyPage, RoomPage -│ ├── components/ # VideoTile, ControlBar, ChatPanel, … -│ ├── hooks/ # useMediasoup, usePictureInPicture, useAudioLevel, … -│ ├── context/ # AuthContext, RoomMetaContext -│ └── utils/ # video-composite, logger -├── server/ # Express + Socket.io + mediasoup -│ └── src/ -│ ├── routes/ # auth, meetings, rooms -│ ├── socket/ # room events, SFU signalling -│ ├── models/ # User, Room -│ └── middleware/ # JWT cookie auth -├── docker-compose.yml # LOCAL DEV: MongoDB + observability stack -├── docker-compose.prod.yml # PRODUCTION: server only (DB is Atlas via MONGO_URI) -├── docker-compose.coturn.yml -├── docs/ -│ ├── STATE.md # current status (source of truth — read first) -│ ├── decisions.md # load-bearing decision log -│ └── old_plan.md # archived milestone-by-milestone history -└── CLAUDE.md / AGENTS.md # agent entry point -``` +| Variable | Default | What it does | +| --- | --- | --- | +| `VITE_SERVER_URL` | none, required | Origin of the API and Socket.io server. | +| `VITE_TURN_DOMAIN` | empty | TURN hostname. Adds relay servers to the ICE configuration. | +| `VITE_TURN_USERNAME` | `ameet` | TURN username. | +| `VITE_TURN_SECRET` | empty | TURN credential. | +| `VITE_TURN_TRANSPORT` | empty | Set to `udp`, `tcp` or `tls` to advertise only that relay path. Leave empty to advertise all three. | +| `VITE_FORCE_RELAY` | empty | Set to `1` to send all media through TURN. Has no effect unless TURN is configured. | ---- - -## Architecture — How the SFU works - -``` -Browser A mediasoup Router Browser B - │ │ │ - │── produce (camera) ──▶ │ │ - │ │◀── consume (B's recv) ── │ - │ │── stream A's layers ──▶ │ - │ │ (layer switch per B's │ - │ │ available bandwidth) │ -``` +## How the SFU works -Every participant **produces** one video track (simulcast: 3 quality layers) and one audio track. Every other participant **consumes** those tracks via the router. The SFU forwards only the right layer — no mixing, no re-encoding, low latency. Audio consumers get `priority(255)` so the SFU always reserves voice bitrate before dropping video layers. +Each room gets its own mediasoup router. The server spreads routers across the worker pool in round-robin order. Every browser opens one send transport and one receive transport. It produces its camera, microphone and screen tracks on the send transport, and it consumes everyone else's tracks on the receive transport. The router forwards RTP packets without mixing or re-encoding them. ---- +Camera video uses simulcast with three spatial layers. Audio consumers get priority 255, so the SFU reserves voice bitrate before it drops video layers. -## Observability +The announced IP is the setting most likely to break a cloud deployment. mediasoup binds `0.0.0.0`, but it advertises `MEDIASOUP_ANNOUNCED_IP` to browsers, and browsers send media to that address. On EC2, the network interface only holds the private address. A loopback or private announced IP leaves remote peers unable to connect media. At startup, the server replaces such a value with the instance's public IPv4, read from IMDSv2. If that lookup fails, it logs an error in production. Set `MEDIASOUP_ANNOUNCED_IP` explicitly to avoid the lookup. -Local logs flow: **Pino (server)** → JSON files → **Promtail** → **Loki** → **Grafana**. +## Repository layout -Open Grafana at `http://localhost:3000`, go to Explore → Loki, and query: ``` -{job="a-meet-server"} +client/ React, Vite and Material UI frontend +server/ Express, Socket.io and mediasoup API server +shared/ @a-meet/contracts, the socket event and REST types shared by client and server +bot/ Discord bot, a thin discord.js client for the API +e2e/ Playwright end-to-end tests +deploy/ EC2, TURN and observability scripts ``` -You can watch SFU `produce` / `consume` / `close-producer` events in real time while a call is live. +## Tests and checks + +```sh +npm test # server, client and bot unit tests (Vitest) +npm run typecheck # shared, server, client and bot +npm run lint # ESLint across all four packages +npm run test:e2e:install # once: install the Playwright Chromium build +npm run test:e2e # Playwright end-to-end tests +npm run verify # lint, audit, typecheck, coverage, client build and E2E in one run +``` -Production does not depend on this local stack. The container's structured JSON stdout uses -Docker's `awslogs` driver and is sent to `/a-meet/prod/server` with 14-day retention. See -[Production logs, alerts, and secrets](#production-logs-alerts-and-secrets). +Vitest transpiles without type checking, so run `npm run typecheck` as well. A green test run does not prove the types are correct. ---- +## Deployment -## Deployment (EC2, containerized) +Production runs the API as a Docker image on one EC2 instance. MongoDB Atlas stores the data, and SSM Parameter Store holds the secrets. The client is a Vite build deployed to Vercel. `client/vercel.json` rewrites every path to the root page, so client-side routes load. -Production runs the backend as an **immutable Docker image** built from `server/Dockerfile`, -supervised by Docker (not pm2). The container uses **host networking** so mediasoup's RTP -port range is reachable, and the server's SIGTERM graceful-drain handles clean restarts. +### Deploy the server image -Releases are **image-based**: CI builds the server image, publishes an immutable tag to -**Amazon ECR**, and the EC2 node **pulls that tag** and restarts the container — it never -rebuilds mediasoup on the box. Docker's `restart: unless-stopped` is the supervisor. In -production the server logs **structured JSON to stdout only** and Docker's `awslogs` driver -forwards it to CloudWatch rather than a bind-mounted file. (The local `docker-compose.yml` -dev stack still uses the Loki/Promtail/Grafana file tail.) +`.github/workflows/deploy-backend.yml` runs on pushes to `main` that touch `server/**`, `shared/**`, the root package files, `.dockerignore`, `docker-compose.prod.yml`, or the workflow itself. It builds the `runtime` target of `server/Dockerfile` and pushes two tags to ECR, `latest` and an immutable `