# gireesh2658/nexus architecture

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

- Interactive diagram: https://gitdiagram.com/gireesh2658/nexus
- Repository: https://github.com/gireesh2658/nexus

## Overview

Nexus is a video-meeting and collaboration platform with a browser client, an authenticated signaling/API server, and an optional Python analysis service. The main user journey is sign in, create or join a meeting, collaborate live, then view meeting intelligence and a summary. The README documents messaging, whiteboards, facial tracking, transcription, analytics, and AI debriefs; these are represented where the tree supports them. Several analysis routes and workers are unsampled, so their internal wiring is shown only where documented or evidenced by sampled source.

Main entry points: [`signaling-server/src/server.ts`](https://github.com/gireesh2658/nexus/blob/main/signaling-server/src/server.ts) (HTTP and socket server), [`frontend/src/pages/MeetingRoom.tsx`](https://github.com/gireesh2658/nexus/blob/main/frontend/src/pages/MeetingRoom.tsx) (Meeting and lobby UI), [`analysis-api/app/main.py`](https://github.com/gireesh2658/nexus/blob/main/analysis-api/app/main.py) (Analysis API), [`analysis-api/app/workers/room_egress_worker.py`](https://github.com/gireesh2658/nexus/blob/main/analysis-api/app/workers/room_egress_worker.py) (Room egress worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_webapp["React application<br/>[App.tsx]"]
  node_routes["Protected routes<br/>[routes.tsx]"]
  node_meetingui["Meeting and lobby UI<br/>[MeetingRoom.tsx]"]
  node_meetingservices["Meeting API client<br/>[meetingService.ts]"]
  node_authclient["Authentication client<br/>[authService.ts]"]
  node_socketclient["Realtime client<br/>[socket.ts]"]
  node_facehook["Face tracking<br/>[useFaceMesh.ts]"]
end

subgraph group_signaling["Signaling and meetings"]
  node_api["HTTP and socket server<br/>[server.ts]"]
  node_authroutes["Auth routes<br/>[authRoutes.ts]"]
  node_authcontroller["Auth controller<br/>[authController.ts]"]
  node_meetingroutes["Meeting routes<br/>[meetingRoutes.ts]"]
  node_meetingcontroller["Meeting controller"]
  node_socketmeeting["Meeting coordination<br/>[meetingHandler.ts]"]
end

subgraph group_analysis["Analysis pipeline"]
  node_analysisapi["Analysis API<br/>[main.py]"]
  node_analysisrouters["Analysis endpoints"]
  node_egress["Room egress worker"]
  node_transcriber["Speech transcription<br/>[transcriber.py]"]
  node_transcriptsink["Transcript sink<br/>[transcript_sink.py]"]
  node_telemetrysink["Telemetry sink<br/>[telemetry_sink.py]"]
  node_summarizer["Meeting summarizer"]
end

subgraph group_integrations["External services"]
  node_db[("Application database<br/>[db.ts]")]
  node_redis[("Redis<br/>[redis.ts]")]
  node_kafka["Kafka topics"]
  node_livekit["LiveKit WebRTC"]
  node_gemini["Gemini AI"]
  node_mailer["Email delivery<br/>[mailer.ts]"]
  node_browser["Browser media"]
end

node_participant(("Meeting participant"))

node_participant -->|"uses"| node_webapp
node_webapp -->|"renders"| node_routes
node_routes -->|"routes to"| node_meetingui
node_webapp -->|"restores session"| node_authclient
node_authclient -->|"requests auth"| node_api
node_meetingui -->|"requests meetings"| node_meetingservices
node_meetingservices -->|"calls API"| node_api
node_meetingui -->|"opens realtime"| node_socketclient
node_socketclient -->|"connects socket"| node_api
node_api -->|"dispatches"| node_authroutes
node_authroutes -->|"dispatches"| node_authcontroller
node_api -->|"dispatches"| node_meetingroutes
node_meetingroutes -->|"dispatches"| node_meetingcontroller
node_authcontroller -->|"reads/writes users"| node_db
node_authcontroller -->|"stores tokens"| node_redis
node_meetingcontroller -->|"reads/writes meetings"| node_db
node_meetingcontroller -->|"creates join token"| node_livekit
node_meetingcontroller -->|"sends debrief"| node_mailer
node_api -->|"sets up handler"| node_socketmeeting
node_socketmeeting -->|"updates participants"| node_db
node_meetingui -->|"joins media room"| node_livekit
node_meetingui -->|"runs tracking"| node_facehook
node_facehook -->|"reads video frames"| node_browser
node_facehook -->|"sends landmarks"| node_analysisapi
node_api -.->|"serves separately"| node_analysisapi
node_analysisapi -->|"registers endpoints"| node_analysisrouters
node_analysisapi -->|"initializes client"| node_redis
node_analysisapi -->|"initializes producer"| node_kafka
node_kafka -->|"dispatches room events"| node_egress
node_egress -->|"joins room"| node_livekit
node_livekit -->|"streams media/events"| node_egress
node_egress -->|"transcribes audio"| node_transcriber
node_egress -->|"publishes telemetry/transcripts"| node_kafka
node_kafka -->|"delivers transcripts"| node_transcriptsink
node_kafka -->|"delivers telemetry"| node_telemetrysink
node_kafka -->|"delivers meeting data"| node_summarizer
node_summarizer -.->|"generates debrief"| node_gemini
node_summarizer -.->|"stores summary"| node_db

click node_webapp "https://github.com/gireesh2658/nexus/blob/main/frontend/src/App.tsx"
click node_routes "https://github.com/gireesh2658/nexus/blob/main/frontend/src/routes.tsx"
click node_meetingui "https://github.com/gireesh2658/nexus/blob/main/frontend/src/pages/MeetingRoom.tsx"
click node_meetingservices "https://github.com/gireesh2658/nexus/blob/main/frontend/src/services/meetingService.ts"
click node_authclient "https://github.com/gireesh2658/nexus/blob/main/frontend/src/services/authService.ts"
click node_socketclient "https://github.com/gireesh2658/nexus/blob/main/frontend/src/services/socket.ts"
click node_facehook "https://github.com/gireesh2658/nexus/blob/main/frontend/src/hooks/useFaceMesh.ts"
click node_api "https://github.com/gireesh2658/nexus/blob/main/signaling-server/src/server.ts"
click node_authroutes "https://github.com/gireesh2658/nexus/blob/main/signaling-server/src/routes/authRoutes.ts"
click node_authcontroller "https://github.com/gireesh2658/nexus/blob/main/signaling-server/src/controllers/authController.ts"
click node_meetingroutes "https://github.com/gireesh2658/nexus/blob/main/signaling-server/src/routes/meetingRoutes.ts"
click node_meetingcontroller "https://github.com/gireesh2658/nexus/blob/main/signaling-server/src/controllers/meetingController.ts"
click node_socketmeeting "https://github.com/gireesh2658/nexus/blob/main/signaling-server/src/sockets/meetingHandler.ts"
click node_analysisapi "https://github.com/gireesh2658/nexus/blob/main/analysis-api/app/main.py"
click node_analysisrouters "https://github.com/gireesh2658/nexus/tree/main/analysis-api/app/routers"
click node_egress "https://github.com/gireesh2658/nexus/blob/main/analysis-api/app/workers/room_egress_worker.py"
click node_transcriber "https://github.com/gireesh2658/nexus/blob/main/analysis-api/app/ml/transcriber.py"
click node_transcriptsink "https://github.com/gireesh2658/nexus/blob/main/analysis-api/app/workers/transcript_sink.py"
click node_telemetrysink "https://github.com/gireesh2658/nexus/blob/main/analysis-api/app/workers/telemetry_sink.py"
click node_summarizer "https://github.com/gireesh2658/nexus/blob/main/analysis-api/app/workers/meeting_summarizer.py"
click node_db "https://github.com/gireesh2658/nexus/blob/main/signaling-server/src/config/db.ts"
click node_redis "https://github.com/gireesh2658/nexus/blob/main/signaling-server/src/config/redis.ts"
click node_mailer "https://github.com/gireesh2658/nexus/blob/main/signaling-server/src/services/mailer.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webapp,node_routes,node_meetingui,node_meetingservices,node_authclient,node_socketclient,node_facehook toneBlue
class node_api,node_authroutes,node_authcontroller,node_meetingroutes,node_meetingcontroller,node_socketmeeting toneAmber
class node_analysisapi,node_analysisrouters,node_egress,node_transcriber,node_transcriptsink,node_telemetrysink,node_summarizer toneMint
class node_db,node_redis,node_kafka,node_livekit,node_gemini,node_mailer,node_browser toneRose
class node_participant toneIndigo
```

## Components

### Web client

- [React application](https://github.com/gireesh2658/nexus/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Protected routes](https://github.com/gireesh2658/nexus/blob/main/frontend/src/routes.tsx): `frontend/src/routes.tsx`
- [Meeting and lobby UI](https://github.com/gireesh2658/nexus/blob/main/frontend/src/pages/MeetingRoom.tsx): `frontend/src/pages/MeetingRoom.tsx`
- [Meeting API client](https://github.com/gireesh2658/nexus/blob/main/frontend/src/services/meetingService.ts): `frontend/src/services/meetingService.ts`
- [Authentication client](https://github.com/gireesh2658/nexus/blob/main/frontend/src/services/authService.ts): `frontend/src/services/authService.ts`
- [Realtime client](https://github.com/gireesh2658/nexus/blob/main/frontend/src/services/socket.ts): `frontend/src/services/socket.ts`
- [Face tracking](https://github.com/gireesh2658/nexus/blob/main/frontend/src/hooks/useFaceMesh.ts): `frontend/src/hooks/useFaceMesh.ts`

### Signaling and meetings

- [HTTP and socket server](https://github.com/gireesh2658/nexus/blob/main/signaling-server/src/server.ts): `signaling-server/src/server.ts`
- [Auth routes](https://github.com/gireesh2658/nexus/blob/main/signaling-server/src/routes/authRoutes.ts): `signaling-server/src/routes/authRoutes.ts`
- [Auth controller](https://github.com/gireesh2658/nexus/blob/main/signaling-server/src/controllers/authController.ts): `signaling-server/src/controllers/authController.ts`
- [Meeting routes](https://github.com/gireesh2658/nexus/blob/main/signaling-server/src/routes/meetingRoutes.ts): `signaling-server/src/routes/meetingRoutes.ts`
- [Meeting controller](https://github.com/gireesh2658/nexus/blob/main/signaling-server/src/controllers/meetingController.ts): `signaling-server/src/controllers/meetingController.ts`
- [Meeting coordination](https://github.com/gireesh2658/nexus/blob/main/signaling-server/src/sockets/meetingHandler.ts): `signaling-server/src/sockets/meetingHandler.ts`

### Analysis pipeline

- [Analysis API](https://github.com/gireesh2658/nexus/blob/main/analysis-api/app/main.py): `analysis-api/app/main.py`
- [Analysis endpoints](https://github.com/gireesh2658/nexus/tree/main/analysis-api/app/routers): `analysis-api/app/routers`
- [Room egress worker](https://github.com/gireesh2658/nexus/blob/main/analysis-api/app/workers/room_egress_worker.py): `analysis-api/app/workers/room_egress_worker.py`
- [Speech transcription](https://github.com/gireesh2658/nexus/blob/main/analysis-api/app/ml/transcriber.py): `analysis-api/app/ml/transcriber.py`
- [Transcript sink](https://github.com/gireesh2658/nexus/blob/main/analysis-api/app/workers/transcript_sink.py): `analysis-api/app/workers/transcript_sink.py`
- [Telemetry sink](https://github.com/gireesh2658/nexus/blob/main/analysis-api/app/workers/telemetry_sink.py): `analysis-api/app/workers/telemetry_sink.py`
- [Meeting summarizer](https://github.com/gireesh2658/nexus/blob/main/analysis-api/app/workers/meeting_summarizer.py): `analysis-api/app/workers/meeting_summarizer.py`

### External services

- [Application database](https://github.com/gireesh2658/nexus/blob/main/signaling-server/src/config/db.ts): `signaling-server/src/config/db.ts`
- [Redis](https://github.com/gireesh2658/nexus/blob/main/signaling-server/src/config/redis.ts): `signaling-server/src/config/redis.ts`
- **Kafka topics**
- **LiveKit WebRTC**
- **Gemini AI**
- [Email delivery](https://github.com/gireesh2658/nexus/blob/main/signaling-server/src/services/mailer.ts): `signaling-server/src/services/mailer.ts`
- **Browser media**

### Other components

- **Meeting participant**

## Connections

- Meeting participant → React application: uses
- React application → Protected routes: renders
- Protected routes → Meeting and lobby UI: routes to
- React application → Authentication client: restores session
- Authentication client → HTTP and socket server: requests auth
- Meeting and lobby UI → Meeting API client: requests meetings
- Meeting API client → HTTP and socket server: calls API
- Meeting and lobby UI → Realtime client: opens realtime
- Realtime client → HTTP and socket server: connects socket
- HTTP and socket server → Auth routes: dispatches
- Auth routes → Auth controller: dispatches
- HTTP and socket server → Meeting routes: dispatches
- Meeting routes → Meeting controller: dispatches
- Auth controller → Application database: reads/writes users
- Auth controller → Redis: stores tokens
- Meeting controller → Application database: reads/writes meetings
- Meeting controller → LiveKit WebRTC: creates join token
- Meeting controller → Email delivery: sends debrief
- HTTP and socket server → Meeting coordination: sets up handler
- Meeting coordination → Application database: updates participants
- Meeting and lobby UI → LiveKit WebRTC: joins media room
- Meeting and lobby UI → Face tracking: runs tracking
- Face tracking → Browser media: reads video frames
- Face tracking → Analysis API: sends landmarks
- HTTP and socket server → Analysis API: serves separately
- Analysis API → Analysis endpoints: registers endpoints
- Analysis API → Redis: initializes client
- Analysis API → Kafka topics: initializes producer
- Kafka topics → Room egress worker: dispatches room events
- Room egress worker → LiveKit WebRTC: joins room
- LiveKit WebRTC → Room egress worker: streams media/events
- Room egress worker → Speech transcription: transcribes audio
- Room egress worker → Kafka topics: publishes telemetry/transcripts
- Kafka topics → Transcript sink: delivers transcripts
- Kafka topics → Telemetry sink: delivers telemetry
- Kafka topics → Meeting summarizer: delivers meeting data
- Meeting summarizer → Gemini AI: generates debrief
- Meeting summarizer → Application database: stores summary