# zulqadar/voice-buddy architecture

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

- Interactive diagram: https://gitdiagram.com/zulqadar/voice-buddy
- Repository: https://github.com/zulqadar/voice-buddy

## Overview

##### Project Type and Purpose
- Voice Buddy is a full-stack real-time voice chat web application.
- The frontend (“client”) is a React/TypeScript SPA that manages UI, user flow (Home → Room), and WebRTC/PeerJS integration.
- The backend (“server”) is a Node.js/TypeScript signaling service using Socket.IO and PeerJS to match random users and facilitate WebRTC connections.

##### File Structure
- Top-level:
- client/ – React app (Vite, Tailwind CSS, TS)
- server/ – Node/Socket.IO/PeerJS signaling server (TS)
- client/src/components, pages, context show an MVVM-style separation: components (UI), pages (routing), context (state management and peer logic).
- server/src/room handles room/session logic and pairing.
- Build/config files: client/vite.config.ts, tailwind.config.js, tsconfigs; server:nodemon.json, tsconfig.json.

##### README for Additional Insights
- Confirms use of WebRTC for media streams, Socket.IO for signaling, PeerJS to simplify peer connections.
- No persistent database—session management is in memory.

##### Components
a. Main Components
- Client Browser (React App)
- Signaling Server (Node.js + Socket.IO + PeerJS Server)
- Peer-to-Peer WebRTC Connection
- STUN/TURN Infrastructure (external or built into PeerJS)
b. Relationships & Interactions
1) Client connects to Signaling Server via Socket.IO (control connection).
2) Server pairs two clients into a “room.”
3) Server exchanges WebRTC SDP offers/answers and ICE candidates via the Socket.IO channel.
4) Once negotiated, the two clients open a direct WebRTC peer connection carrying audio streams.
c. Architectural Patterns & Design Principles
- Clear frontend/backend separation
- Single-page architecture on the client, with context-based state management for peer actions
- Event-driven messaging via WebSockets (Socket.IO)
- P2P media using WebRTC/PeerJS to offload media traffic from the server
d. Key Technologies
- React, TypeScript, Vite, Tailwind CSS on client
- Node.js, TypeScript, Socket.IO, PeerJS on server
- WebRTC (STUN/TURN) for audio streaming

##### Detailed Capture of Architectural Elements
- How the React context modules (peer-actions.ts, peer-reducer.ts, room-context.tsx) mediate between UI and peer connections.
- That client/src/assets and client/src/components create the UI for create-button and video-player.
- On the server side, illustrate server/src/room/index.ts handling room lifecycle and signaling events.

Putting It All Together
Layer 1 (Client): Pages & Context → Socket.IO Client → PeerJS Client → WebRTC API
Layer 2 (Network): Socket.IO WS, STUN/TURN, WebRTC ICE connections
Layer 3 (Server): Socket.IO Server → Room Manager → PeerJS Server module
1. Client WS connect → Server
2. Server emits “match” → Client A & B
3. Clients exchange SDP via Server
4. Clients establish P2P audio stream

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend"
        style Frontend fill:#ccffcc,stroke:#333,stroke-width:1px
        Browser["Browser (React App)"]:::frontend
        subgraph "Pages"
            Home["Home Page"]:::frontend
            Room["Room Page"]:::frontend
        end
        subgraph "Context"
            RC["room-context.tsx"]:::frontend
            PA["peer-actions.ts"]:::frontend
            PR["peer-reducer.ts"]:::frontend
        end
        subgraph "UI Components"
            CB["create-button.tsx"]:::frontend
            VP["video-player.tsx"]:::frontend
        end
        subgraph "Config"
            Vite["vite.config.ts"]:::frontend
            Tailwind["tailwind.config.js"]:::frontend
        end
        Assets["assets"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend"
        style Backend fill:#cce5ff,stroke:#333,stroke-width:1px
        SIG["Socket.IO Signaling Server"]:::backend
        RM["Room Manager"]:::backend
        PS["PeerJS Server"]:::backend
        subgraph "Server Configs"
            Nodemon["nodemon.json"]:::backend
            TSConfS["tsconfig.json"]:::backend
            PKG["package.json"]:::backend
        end
    end

    %% External Infrastructure
    STUN["STUN/TURN Servers"]:::external
    P2P["WebRTC P2P Channel"]:::external

    %% Connections
    Browser -->|"WebSocket (Socket.IO)"| SIG
    SIG -->|"manage rooms"| RM
    SIG -->|"init PeerJS"| PS
    SIG -->|"match clients"| Browser
    Browser -->|"SDP/ICE via WS"| SIG
    Browser --> P2P
    P2P --> Browser
    STUN --> P2P

    %% Peer-to-Peer Media
    Browser <-->|"WebRTC Audio Stream"| Browser

    %% Click Events
    click Browser "https://github.com/zulqadar/voice-buddy/blob/master/client/src/main.tsx"
    click Browser "https://github.com/zulqadar/voice-buddy/blob/master/client/src/App.tsx"
    click Home "https://github.com/zulqadar/voice-buddy/blob/master/client/src/pages/home.tsx"
    click Room "https://github.com/zulqadar/voice-buddy/blob/master/client/src/pages/room.tsx"
    click RC "https://github.com/zulqadar/voice-buddy/blob/master/client/src/context/room-context.tsx"
    click PA "https://github.com/zulqadar/voice-buddy/blob/master/client/src/context/peer-actions.ts"
    click PR "https://github.com/zulqadar/voice-buddy/blob/master/client/src/context/peer-reducer.ts"
    click CB "https://github.com/zulqadar/voice-buddy/blob/master/client/src/components/create-button.tsx"
    click VP "https://github.com/zulqadar/voice-buddy/blob/master/client/src/components/video-player.tsx"
    click Assets "https://github.com/zulqadar/voice-buddy/tree/master/client/src/assets"
    click Vite "https://github.com/zulqadar/voice-buddy/blob/master/client/vite.config.ts"
    click Tailwind "https://github.com/zulqadar/voice-buddy/blob/master/client/tailwind.config.js"
    click SIG "https://github.com/zulqadar/voice-buddy/blob/master/server/src/index.ts"
    click RM "https://github.com/zulqadar/voice-buddy/blob/master/server/src/room/index.ts"
    click Nodemon "https://github.com/zulqadar/voice-buddy/blob/master/server/nodemon.json"
    click TSConfS "https://github.com/zulqadar/voice-buddy/blob/master/server/tsconfig.json"
    click PKG "https://github.com/zulqadar/voice-buddy/blob/master/server/package.json"

    %% Styles
    classDef frontend fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef backend fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef external fill:#ffe0b3,stroke:#333,stroke-width:1px
```
