chad/server/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Chad is a real-time voice/video chat server (think Discord-like) built with Fastify, Socket.IO, and mediasoup for WebRTC media handling. It uses SQLite via Prisma ORM and Lucia for session-based authentication. The client is a Tauri desktop app (separate repo).

Commands

• Start server: yarn start (runs ts-node --transpile-only server.ts)
• Deploy DB (migrate + seed + generate): yarn db:deploy
• Generate Prisma client after schema changes: npx prisma generate
• Create a migration: npx prisma migrate dev --name <name>
• Lint: npx eslint .
• Package manager: Yarn 4 (corepack). Do not use npm.

Architecture

Entry Point & Plugin System

server.ts creates a Fastify instance and uses @fastify/autoload to auto-register everything in plugins/ and routes/ (prefixed under /chad). Plugins use fastify-plugin (fp) with named dependencies to control load order.

Plugin Load Order (dependency chain)

1. plugins/auth.ts — Adds req.user / req.session via Lucia cookie validation on every request (preHandler hook)
2. plugins/mediasoup-worker.ts — Creates a mediasoup Worker, decorates fastify.mediasoupWorker
3. plugins/mediasoup-router.ts — Creates a mediasoup Router (depends on worker), decorates fastify.mediasoupRouter. Configures supported audio/video codecs (Opus, VP8, VP9, H.264, AV1)
4. plugins/socket.ts — Creates Socket.IO server at /chad/ws (depends on worker + router), decorates fastify.io. Registers socket handlers on fastify.ready()

Socket Handlers (socket/)

• socket/webrtc.ts — Main WebRTC signaling: join/leave, transport creation, producer/consumer lifecycle, audio level observation, active speaker detection
• socket/channel.ts — Channel-based socket logic (in development on channels branch)

Both handlers authenticate by looking up socket.handshake.auth.userId against the DB.

REST Routes (routes/)

All routes are prefixed with /chad via autoload config.

• routes/auth.ts — /register, /login, /logout, /me
• routes/user.ts — /preferences (GET/PATCH), /profile (PATCH). Profile changes broadcast to connected socket peers via clientChanged event.

Type System (types/socket.ts)

Fully typed Socket.IO events: ClientToServerEvents, ServerToClientEvents, SocketData. The SomeSocket union type covers both live Socket and RemoteSocket (from fetchSockets()).

Database

• SQLite with Prisma 7 + @prisma/adapter-better-sqlite3
• Schema at prisma/schema.prisma, generated client at prisma/generated/client/
• Models: User, Session (Lucia), UserPreferences, Channel
• Seed creates a persistent "Default" channel
• Config in prisma.config.ts using dotenv for DATABASE_URL

Key Patterns

• Request validation uses Zod schemas defined inline in route handlers
• DTOs in dto/ define Prisma select objects with satisfies Prisma.*Select for type-safe projections
• utils/socket-to-client.ts maps socket data to the ChadClient interface sent to clients
• ESLint uses @antfu/eslint-config (flat config) with no-console and n/prefer-global/process disabled

Environment Variables

• PORT — Server port (default: 4000, Docker: 80)
• DATABASE_URL — SQLite path (e.g., file:../data/database.db)
• ANNOUNCED_ADDRESS — Public IP for WebRTC ICE candidates (default: 127.0.0.1)
• CORS_ORIGIN — Socket.IO CORS origin (default: *)

Docker

Dockerfile requires python3 and build-essential for mediasoup native compilation. Runs yarn db:deploy && yarn start.