# benikk/pair-program architecture

> Architecture diagram of the GitHub repository benikk/pair-program, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/benikk/pair-program
- Repository: https://github.com/benikk/pair-program

## Overview

##### Project type and purpose
- This is a full-stack collaborative coding application ("pair-program") that lets multiple users join a room, discuss, write and review code together in real time, with audio/video support and AI-powered question generation.
- Key features (from README): real-time updates via WebSocket + CRDT (Y.js), audio/video via LiveKit, Express + TypeScript backend, Next.js + Tailwind frontend, AI question generation with Gemini.

##### File structure
- Top-level:
- frontend/ (Next.js app, UI components, Tailwind CSS, page routes including /room/[id])
- backend/ (Express + TypeScript server, HTTP routes, WS (ws library), CRDT utilities, LiveKit token routes)
- docker-compose.yml (compose both frontend & backend and any supporting services)
- backend/src/http/server.ts: sets up Express HTTP server and WS upgrade handlers.
- backend/src/ws/socket.ts + utils/broadCast.ts: core real-time and CRDT message distribution.
- backend/src/http/routes/livekit.ts: issues tokens/credentials for LiveKit.
- frontend/lib/api.ts & lib/utils.ts: wrapper for REST + WS client calls.
- frontend/app/room/[id]/page.tsx & components/Livekit.tsx: integrate audio/video UI and WebSocket/CRDT client.

##### README for additional insights
- Confirms CRDT conflict management via Y.js.
- AI question generation is an external API call (Gemini).
- Running instructions: docker-compose.

a. Main components
- Client (Next.js React SPA)
- Backend Service (Express + WS + CRDT logic)
- LiveKit Service (audio/video)
- External AI Service (Gemini for question generation)
- (Optional) Reverse proxy / load balancer if deployed in production
b. Relationships & interactions
- Client ↔ Backend HTTP: authentication, room metadata, AI question API calls
- Client ↔ Backend WebSocket: real-time CRDT document updates, chat/messages
- Client ↔ LiveKit: media negotiation & streaming (via tokens from backend)
- Backend → Gemini API: send code/context, receive generated questions
- docker-compose orchestrates frontend, backend, and can include a self-hosted LiveKit server
c. Architectural patterns & principles
- Two-tier full-stack: decoupled frontend & backend
- Real-time collaboration pattern using CRDT (Y.js) for conflict-free document merging
- Single WS endpoint handling CRDT synchronization
- Microservices-style external services (LiveKit, Gemini)
d. Key technologies/frameworks
- Next.js (frontend SSR/SSG & client-side routing)
- Tailwind CSS (styling)
- Express + ws (backend HTTP + WebSocket)
- TypeScript end-to-end
- Y.js (CRDT library)
- LiveKit (audio/video)
- Gemini API (AI question generation)
- Docker & docker-compose (container orchestration)

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "Docker Host"
    subgraph "Frontend Container"
      NextClient["Next.js Client"]:::frontend
      UILayout["UI Layer (layout.tsx & globals.css)"]:::frontend
      Pages["Home & Room Pages"]:::frontend
      ComponentsLib["UI Components Library"]:::frontend
      LivekitClient["LiveKit Client Integration"]:::frontend
      ClientUtils["REST Client Utilities (api.ts & utils.ts)"]:::frontend
      ClientTypes["Type Definitions (type.ts)"]:::frontend

      NextClient --> UILayout
      NextClient --> Pages
      NextClient --> ComponentsLib
      NextClient --> LivekitClient
      NextClient --> ClientUtils
      NextClient --> ClientTypes
    end

    subgraph "Backend Container"
      HTTPServer["Express HTTP Server"]:::backend
      APIGeneral["Room & AI Question Endpoints"]:::backend
      LivekitRoutes["LiveKit Token Endpoints"]:::backend
      WSRt["WebSocket & CRDT Layer"]:::backend
      UtilsBrd["Broadcast Utility"]:::backend
      SharedTypes["Shared Types"]:::backend
      Config["Configuration"]:::backend
      Entry["Entry Points & Build"]:::backend

      HTTPServer --> APIGeneral
      HTTPServer --> LivekitRoutes
      HTTPServer --> WSRt
      WSRt --> UtilsBrd
      APIGeneral --> SharedTypes
      HTTPServer --> Config
      Entry --> HTTPServer
      Entry --> APIGeneral
      Entry --> WSRt
    end
  end

  subgraph "External Services"
    LiveKitSvc["LiveKit Media Server"]:::external
    Gemini["Gemini AI API"]:::external
  end

  dockerCompose["docker-compose.yml"]:::infra

  NextClient -->|HTTP Requests| APIGeneral
  NextClient -->|HTTP Requests| LivekitRoutes
  NextClient -->|WebSocket Stream| WSRt
  NextClient -->|Media Stream| LiveKitSvc
  APIGeneral -->|AI Calls| Gemini
  LivekitRoutes -->|Token Provision| LiveKitSvc
  dockerCompose -->|orchestrates| NextClient
  dockerCompose -->|orchestrates| HTTPServer

  click NextClient "https://github.com/benikk/pair-program/tree/main/frontend/"
  click UILayout "https://github.com/benikk/pair-program/blob/main/frontend/app/layout.tsx"
  click UILayout "https://github.com/benikk/pair-program/blob/main/frontend/app/globals.css"
  click Pages "https://github.com/benikk/pair-program/blob/main/frontend/app/page.tsx"
  click Pages "https://github.com/benikk/pair-program/blob/main/frontend/app/room/[id]/page.tsx"
  click ComponentsLib "https://github.com/benikk/pair-program/tree/main/frontend/components/"
  click LivekitClient "https://github.com/benikk/pair-program/blob/main/frontend/components/Livekit.tsx"
  click ClientUtils "https://github.com/benikk/pair-program/blob/main/frontend/lib/api.ts"
  click ClientUtils "https://github.com/benikk/pair-program/blob/main/frontend/lib/utils.ts"
  click ClientTypes "https://github.com/benikk/pair-program/blob/main/frontend/lib/type.ts"
  click HTTPServer "https://github.com/benikk/pair-program/blob/main/backend/src/http/server.ts"
  click APIGeneral "https://github.com/benikk/pair-program/blob/main/backend/src/http/routes/api.ts"
  click LivekitRoutes "https://github.com/benikk/pair-program/blob/main/backend/src/http/routes/livekit.ts"
  click WSRt "https://github.com/benikk/pair-program/blob/main/backend/src/ws/socket.ts"
  click UtilsBrd "https://github.com/benikk/pair-program/blob/main/backend/src/utils/broadCast.ts"
  click SharedTypes "https://github.com/benikk/pair-program/blob/main/backend/src/types/room.ts"
  click Config "https://github.com/benikk/pair-program/blob/main/backend/src/config/config.ts"
  click Entry "https://github.com/benikk/pair-program/blob/main/backend/src/index.ts"
  click dockerCompose "https://github.com/benikk/pair-program/blob/main/docker-compose.yml"

  classDef frontend fill:#D0E8FF,stroke:#0284C7
  classDef backend fill:#DFF5D5,stroke:#22C55E
  classDef external fill:#E5E7EB,stroke:#6B7280
  classDef infra fill:#F5F3FF,stroke:#7C3AED
```
