# vokuorg/voku architecture

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

- Interactive diagram: https://gitdiagram.com/vokuorg/voku
- Repository: https://github.com/vokuorg/voku

## Overview

##### Project Type & Purpose
- Full-stack (front-end heavy) web application.
- Purpose: Enable users to create/join video-chat rooms (peer-to-peer via WebRTC), plus a “random call” mode.
- Tech highlights: React, Context API, Firebase (signaling), WebRTC, Tailwind CSS (via CRACO), static hosting (Netlify/Vercel).

##### File Structure
– Top-level:
- public/ → static HTML, manifest, redirects (Netlify)
- src/ → React code
– src/components → UI elements (chat, video layout, controls, modals)
– src/contexts → global state (AppContext for user/room data)
– src/firebase.js → Firebase app initialization
– src/pages → page views (Home, CallRoom)
– tailwind.config.js, craco.config.js → styling/build overrides
– No custom backend code — relies on Firebase and direct browser-to-browser connections.

##### Extract Key Architecture Insights from README
– Peer-to-peer video calling → WebRTC data & media channels
– “Random call” matchmaking → probably managed by Firebase functions or Realtime Database
– Esperanto support / X-System translation → may use an external translation API (if implemented).

##### Main Components & How They Interact
a. Frontend (React SPA)
- AppContext for user identity, current room, settings
- Pages: Home (landing + create/join), CallRoom (video + chat UI)
b. Signaling & Matchmaking (Firebase)
- Auth (anonymous or email?)
- Firestore/Realtime DB for exchanging SDP offers/answers & ICE candidates
- Optional Cloud Functions for random pairing
c. Peer-to-Peer WebRTC
- Browser A ↔ Browser B media streams (video/audio)
- STUN/TURN servers (public or custom) configured in code
d. External Services
- Translation API (for X-System auto-translation in chat)
- Hosting/CDN (Netlify/Vercel) serving static bundle
e. Asset Hosting
- Static assets (fonts, sounds, images) in public/ and src/assets

##### Architectural Patterns & Design Principles
– Component-based UI (atomic React components)
– Context API for global state (avoids prop drilling)
– Single Page Application (client-side routing with React Router)
– Event-driven signaling (Firebase triggers client WebRTC setup)
– Separation of concerns: UI vs. signaling vs. media plane

– Component labels (e.g., “CallRoom.jsx”) where helpful for clarity.
– Group related components inside boundaries (e.g., “src/components/*” cluster).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hosting Layer
    subgraph "Hosting / CDN"
        CDN["Netlify/Vercel CDN"]:::hosting
    end

    %% External Services Layer
    subgraph "External Services"
        Trans["Translation API"]:::external
    end

    %% Signaling Layer
    subgraph "Firebase Signaling"
        Auth["Firebase Auth"]:::backend
        DB["Firestore / RTDB"]:::backend
        Func["Cloud Functions<br/>(random matchmaking)"]:::backend
    end

    %% Media Plane
    subgraph "Media Plane"
        STUN["STUN / TURN Servers"]:::media
    end

    %% Client Browsers
    subgraph "Client Browser Instances"
        subgraph "Browser A"
            AppA["App<br/>(src/App.js)"]:::frontend
            ContextA["AppContext<br/>(src/contexts/AppContext/AppContext.jsx)"]:::frontend
            HomeA["Home Page<br/>(src/pages/Home/Home.jsx)"]:::frontend
            CallA["CallRoom Page<br/>(src/pages/CallRoom/CallRoom.jsx)"]:::frontend
            UICmpA["UI Components<br/>(src/components/)"]:::frontend
        end
        subgraph "Browser B"
            AppB["App<br/>(src/App.js)"]:::frontend
            ContextB["AppContext<br/>(src/contexts/AppContext/AppContext.jsx)"]:::frontend
            HomeB["Home Page<br/>(src/pages/Home/Home.jsx)"]:::frontend
            CallB["CallRoom Page<br/>(src/pages/CallRoom/CallRoom.jsx)"]:::frontend
            UICmpB["UI Components<br/>(src/components/)"]:::frontend
        end
    end

    %% Connections
    CDN -->|"Fetch Static Bundle (HTTPS)"| AppA
    CDN -->|"Fetch Static Bundle (HTTPS)"| AppB

    AppA -->|"Auth / Signaling (Firebase SDK)"| Auth
    AppB -->|"Auth / Signaling (Firebase SDK)"| Auth

    AppA -->|"Read/Write SDP & ICE (WebSocket/Firebase SDK)"| DB
    AppB -->|"Read/Write SDP & ICE (WebSocket/Firebase SDK)"| DB

    Func -->|"Write pairing data"| DB
    DB -->|"Trigger pairing"| Func

    AppA -->|"Invoke matchmaking"| Func
    AppB -->|"Invoke matchmaking"| Func

    AppA -->|"Translation Request"| Trans
    AppA -->|"Translation Response"| Trans
    AppB -->|"Translation Request"| Trans
    AppB -->|"Translation Response"| Trans

    AppA -->|"Connect media (SDP & ICE negotiation)"| STUN
    AppB -->|"Connect media (SDP & ICE negotiation)"| STUN

    STUN -->|"Relay Media Streams (RTP)"| AppA
    STUN -->|"Relay Media Streams (RTP)"| AppB

    AppA -->|"Peer-to-Peer Media Stream"| AppB
    AppB -->|"Peer-to-Peer Media Stream"| AppA

    %% Click Events for component mapping
    click AppA "https://github.com/vokuorg/voku/blob/main/src/App.js"
    click AppB "https://github.com/vokuorg/voku/blob/main/src/App.js"
    click ContextA "https://github.com/vokuorg/voku/blob/main/src/contexts/AppContext/AppContext.jsx"
    click ContextB "https://github.com/vokuorg/voku/blob/main/src/contexts/AppContext/AppContext.jsx"
    click HomeA "https://github.com/vokuorg/voku/blob/main/src/pages/Home/Home.jsx"
    click HomeB "https://github.com/vokuorg/voku/blob/main/src/pages/Home/Home.jsx"
    click CallA "https://github.com/vokuorg/voku/blob/main/src/pages/CallRoom/CallRoom.jsx"
    click CallB "https://github.com/vokuorg/voku/blob/main/src/pages/CallRoom/CallRoom.jsx"
    click UICmpA "https://github.com/vokuorg/voku/tree/main/src/components/"
    click UICmpB "https://github.com/vokuorg/voku/tree/main/src/components/"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#64B5F6,color:#0D47A1;
    classDef backend fill:#E8F5E9,stroke:#66BB6A,color:#1B5E20;
    classDef media fill:#FFF3E0,stroke:#FFA726,color:#E65100;
    classDef external fill:#F3E5F5,stroke:#BA68C8,color:#4A148C;
    classDef hosting fill:#ECEFF1,stroke:#90A4AE,color:#263238;
```
