# jakekitchen/mumbai architecture

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

- Interactive diagram: https://gitdiagram.com/jakekitchen/mumbai
- Repository: https://github.com/jakekitchen/mumbai

## Overview

##### Project Type & Purpose
- Mumbai is a secure, open-source, one-to-one video conferencing application built to eliminate third-party logging or data capture.
- Its primary goal is to enable highly private, direct video calls using WebRTC. The README emphasizes that it is clientless, requiring no downloads or persistent logs.

##### Analyzing the File Structure
- Top-level:
– Files like .env, package.json, tsconfig.json, and LICENSE, which set up the environment, project configuration, and dependencies.
- Public Directory:
– Contains static assets such as CSS, JavaScript, EJS templates (home.ejs, call.ejs, header.ejs) used for the frontend.
– The JavaScript files (e.g., call.js, handle-ws.js, media.js, video-grid.js) manage client-side interactions – from handling media streams and WebRTC sessions to managing the video grid UI.
- src Directory:
– App.ts appears to be the entry point for the Node server.
– Routes directory (e.g., index.ts, room.router.ts) sets up express endpoints, including room management.
– Utils directory holds key modules for WebRTC signaling, room and user management, and websocket client handling.
– TLS key files in src (e.g., localhost+2-key.pem, localhost+2.pem) indicate secure communications.
- .github Directory:
– Provides CI/CD workflows which although peripheral to the system design, highlight automated testing and deployment practices.

##### Key Architectural Components
a. Frontend:
– Static pages served via EJS templates (e.g., home.ejs, call.ejs).
– CSS and JS assets that control UI and client-side logic.
– Browser API integration with WebRTC for peer-to-peer video functionality.
b. Backend:
– A Node/Express server (entry in src/app.ts) providing endpoints for room creation and routing (via room.router.ts and index.ts).
– Websocket handling (src/utils/handleWebsocket.ts, wsClients.ts, wsMessage.ts) that facilitates signaling between clients.
– Room and user management utilities (room.ts, rooms.ts, user.ts) to manage session states.
c. Signaling Layer:
– Uses websocket services to exchange session initiation messages, so clients can negotiate their WebRTC connection.
d. Security & Deployment:
– Integration of TLS certificates ensures secure client-server communication.
– The .env configuration files at both project root and within src suggest environment-specific settings.

##### Relationships & Interactions
- Clients (browsers) request the webpage HTML (EJS templates from the public folder) from the Express server.
- After rendering, the client-side JavaScript initiates WebRTC calls.
- A websocket connection (handled by modules in the src/utils directory) is established between the client and the server to exchange call setup signals.
- Once connected, direct peer-to-peer calls commence using the framework provided by WebRTC.
- The server also manages room creation, verification, and termination, ensuring that each room only hosts two participants.

##### Architectural Patterns & Design Principles
- Clear separation of concerns between frontend (presentation/UI, media handling) and backend (server routing, signaling, room management).
- Minimalist and secure design – intentionally limiting features for a privacy-first, two-participant system.
- Usage of common Node.js and Express patterns with a modular approach (distinct directories for routes and utilities).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        Client["Frontend UI (Client Browser)"]:::client
        Peer["Peer Client (Frontend UI)"]:::client
    end

    %% Backend Layer
    subgraph "Backend Layer"
        %% HTTP Server Subgroup
        subgraph "HTTP Server"
            App["Node/Express App"]:::server
            Routes["HTTP Routes"]:::server
        end

        %% Signaling Service Subgroup
        subgraph "Signaling Service"
            WS1["handleWebsocket"]:::signaling
            WS2["wsClients"]:::signaling
            WS3["wsMessage"]:::signaling
        end

        %% Room & Session Management Subgroup
        subgraph "Room & Session Management"
            RM1["room"]:::room
            RM2["rooms"]:::room
            RM3["user"]:::room
        end

        %% Security & Configuration Subgroup
        subgraph "Security & Config"
            TLS["TLS Certificates"]:::security
            Env["Environment Config"]:::config
        end
    end

    %% Relationships & Data Flows
    Client -->|"HTTPRequest"| App
    App -->|"Uses_Routes"| Routes
    App -->|"Serves_static_assets"| Client
    Client -->|"Initiate_WS"| WS1
    WS1 ---|"Relays_signaling"| WS2
    WS1 ---|"Relays_signaling"| WS3
    WS1 -->|"Manages_session"| RM1
    WS1 -->|"Manages_session"| RM2
    WS1 -->|"Manages_session"| RM3
    Client ---|"Direct_WebRTC_stream"| Peer
    App ---|"Secured_by"| TLS
    App ---|"Configured_by"| Env

    %% Click Events
    click Client "https://github.com/jakekitchen/mumbai/tree/main/public"
    click App "https://github.com/jakekitchen/mumbai/blob/main/src/app.ts"
    click Routes "https://github.com/jakekitchen/mumbai/tree/main/src/routes"
    click WS1 "https://github.com/jakekitchen/mumbai/blob/main/src/utils/handleWebsocket.ts"
    click WS2 "https://github.com/jakekitchen/mumbai/blob/main/src/utils/wsClients.ts"
    click WS3 "https://github.com/jakekitchen/mumbai/blob/main/src/utils/wsMessage.ts"
    click RM1 "https://github.com/jakekitchen/mumbai/blob/main/src/utils/room.ts"
    click RM2 "https://github.com/jakekitchen/mumbai/blob/main/src/utils/rooms.ts"
    click RM3 "https://github.com/jakekitchen/mumbai/blob/main/src/utils/user.ts"
    click TLS "https://github.com/jakekitchen/mumbai/blob/main/src/localhost+2-key.pem"
    click TLS "https://github.com/jakekitchen/mumbai/blob/main/src/localhost+2.pem"
    click Env "https://github.com/jakekitchen/mumbai/blob/main/.env"
    click Env "https://github.com/jakekitchen/mumbai/blob/main/src/.env"

    %% Styles
    classDef client fill:#a2d2ff,stroke:#000,stroke-width:1px;
    classDef server fill:#ffadad,stroke:#000,stroke-width:1px;
    classDef signaling fill:#ffd6a5,stroke:#000,stroke-width:1px;
    classDef room fill:#fdffb6,stroke:#000,stroke-width:1px;
    classDef security fill:#caffbf,stroke:#000,stroke-width:1px;
    classDef config fill:#d0f4de,stroke:#000,stroke-width:1px;
```
