# sriharisrihari164-netizen/brotransfer architecture

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

- Interactive diagram: https://gitdiagram.com/sriharisrihari164-netizen/brotransfer
- Repository: https://github.com/sriharisrihari164-netizen/brotransfer

## Overview

##### Project type & purpose (from file tree + README)
This is a **frontend-only Single Page Application (SPA)** built with **React + Vite** (no backend code present). The component naming strongly indicates a **P2P file transfer app** running entirely in the browser:

- `src/components/Sender.jsx`, `Receiver.jsx`, `FileDrop.jsx` → sender/receiver UX and file selection
- `src/hooks/usePeer.js`, `useFileSender.js`, `useFileReceiver.js` → WebRTC peer/data-channel orchestration and file send/receive logic
- `src/workers/fileWorker.js` → heavy file processing off the main thread (chunking, hashing, assembling, etc.)
- Static hosting/deploy hints:
- `.github/workflows/github-pages.yml` → **GitHub Pages** deploy
- `public/CNAME`, `public/.nojekyll`, `public/404.html`, `sitemap.xml` → static site + custom domain + SPA routing behavior

So your “system” is primarily: **two browsers + WebRTC + optional external NAT traversal infrastructure + static hosting**.

##### UI / Pages (route-level)
- `src/pages/Home.jsx` – main flow (likely sender/receiver entry)
- `src/pages/PrivacyPolicy.jsx`, `TermsOfService.jsx` – legal pages
- Layout/branding:
- `src/components/Layout.jsx`, `Header.jsx`, `Logo.jsx`
- `src/components/Instructions.jsx`, `Features.jsx`

##### Core P2P features (high-value runtime components)
- **Peer Connection / Session**
- `src/hooks/usePeer.js`
- Responsibility: create/manage `RTCPeerConnection`, ICE candidates, DataChannel events, connection lifecycle
- **File Sending**
- `src/hooks/useFileSender.js`
- `src/components/Sender.jsx`, `FileDrop.jsx`
- Responsibility: select file, chunk/stream, backpressure, send over DataChannel
- **File Receiving**
- `src/hooks/useFileReceiver.js`
- `src/components/Receiver.jsx`
- Responsibility: receive chunks, validate/assemble, trigger download/save
- **Worker offload**
- `src/workers/fileWorker.js`
- Responsibility: CPU/memory-heavy operations off main thread (chunking, merging, hashing, etc.)
- **Debug / observability**
- `src/components/DebugLogger.jsx`
- `src/utils/debugLog.js`
- Responsibility: structured logging, toggles, UI visibility

Inside each browser runtime, show:
- `Sender.jsx` → `useFileSender.js` → `usePeer.js` → **WebRTC DataChannel**
- **Web Worker boundary**:
- `useFileSender.js` ↔ `fileWorker.js` (postMessage for chunking/processing)
- `useFileReceiver.js` ↔ `fileWorker.js` (postMessage for assembling/validation)
- `DebugLogger.jsx` ← `debugLog.js` called by hooks/components

##### WebRTC DataChannel opens

**Annotate clearly:** “Signaling is not the file transfer path.”

##### Flow 2: File transfer pipeline (data plane)
Sender side:
- File chosen in `FileDrop.jsx` / `Sender.jsx`
- `useFileSender.js` reads file (stream/chunks)
- `fileWorker.js` prepares chunks (optional compression/hashing)
- Chunks sent over DataChannel (backpressure / buffering)

Receiver side:
- DataChannel receives chunks (`usePeer.js` → `useFileReceiver.js`)
- `fileWorker.js` assembles chunks
- Receiver triggers browser download/save

- “binary chunks (ArrayBuffer/Blob)”
- “control messages (metadata: filename, size, chunk index)”

- Developer pushes to GitHub
- GitHub Actions (`.github/workflows/github-pages.yml`) runs:
- `npm ci` (from `package-lock.json`)
- `vite build`
- Output deployed to GitHub Pages
- DNS / custom domain via `public/CNAME`
- SPA routing support via `public/404.html` and `.nojekyll`

This is especially important because the “system” has no backend—availability is basically “static host + WebRTC infra”.

##### Diagramming conventions to enforce (for maximum clarity)

- **Boundaries**:
- “Sender Browser” boundary
- “Receiver Browser” boundary
- “Static Hosting” boundary
- “External WebRTC Services” boundary
- Rectangle: React component/hook/module
- Double-rectangle or “container”: Browser runtime / SPA container
- **Labels everywhere**:
- Protocol labels: HTTPS (hosting), WebRTC (P2P), STUN/TURN
- Data labels: SDP offer/answer, ICE candidates, chunked binary

##### Practical “don’t overthink it” decomposition (recommended final component list)
If your goal is “very detailed and capture essentials,” use this exact top-level decomposition:

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% ========= System Context =========
  subgraph "System Context (C4 L1)"
    direction TB

    UA["User A (Sender)"]:::person
    UB["User B (Receiver)"]:::person

    subgraph "Static Hosting"
      direction TB
      GH["GitHub Pages / CDN (Static Assets)"]:::external
      DNS["Custom Domain + SPA Routing\n(CNAME / 404.html / .nojekyll / sitemap.xml)"]:::external
      CI["GitHub Actions Deploy Pipeline\n(vite build → publish)"]:::external
    end

    subgraph "External WebRTC Services"
      direction TB
      STUN["STUN Server(s)\n(NAT discovery)"]:::cloud
      TURN["TURN Server\n(Optional relay)"]:::cloud
    end

    OOB["Signaling Channel\n(Manual copy/paste or out-of-band)"]:::external

    subgraph "Browser Runtimes (Two instances of the same SPA)"
      direction TB

      subgraph "Sender Browser Runtime"
        direction TB
        SA["Sender Browser\n(React SPA + Web APIs)"]:::container
      end

      subgraph "Receiver Browser Runtime"
        direction TB
        RB["Receiver Browser\n(React SPA + Web APIs)"]:::container
      end
    end

    UA -->|"uses"| SA
    UB -->|"uses"| RB

    SA <-->|"HTTPS GET index.html/assets"| GH
    RB <-->|"HTTPS GET index.html/assets"| GH
    GH -->|"serves via"| DNS
    CI -->|"deploys to"| GH

    SA <-->|"STUN/TURN (ICE traversal)"| STUN
    SA <-->|"TURN relay (if needed)"| TURN
    RB <-->|"STUN/TURN (ICE traversal)"| STUN
    RB <-->|"TURN relay (if needed)"| TURN

    SA -.->|"SDP offer/answer + ICE candidates\n(signaling, not data path)"| OOB
    RB -.->|"SDP offer/answer + ICE candidates\n(signaling, not data path)"| OOB

    SA ==>|"WebRTC DataChannel\n(file bytes)"| RB
  end

  %% ========= Container / Component View =========
  subgraph "SPA Internals (C4 L2 / Component view inside each Browser)"
    direction TB

    subgraph "SPA Shell"
      direction TB
      Entry["Vite + React Entrypoint\n(index.html → main.jsx → App.jsx)"]:::frontend
      Router["Routing / Pages"]:::frontend
      Layout["Layout / Branding Shell\n(Layout, Header, Logo)"]:::frontend
      Info["Instructions / Features Content\n(Instructions, Features)"]:::frontend
    end

    subgraph "Pages"
      direction TB
      Home["Home Page\n(Sender/Receiver entry flow)"]:::page
      Privacy["Privacy Policy Page"]:::page
      Terms["Terms of Service Page"]:::page
    end

    subgraph "P2P Core"
      direction TB
      SenderUI["Sender UI\n(Sender, FileDrop)"]:::ui
      ReceiverUI["Receiver UI\n(Receiver)"]:::ui

      Peer["Peer Connection / Session Core\n(usePeer)\nRTCPeerConnection + DataChannel"]:::core

      FileSend["File Send Pipeline\n(useFileSender)\nchunk/stream/backpressure"]:::core
      FileRecv["File Receive Pipeline\n(useFileReceiver)\nreceive/assemble/download"]:::core

      subgraph "Worker Thread"
        direction TB
        Worker["fileWorker\n(chunking/assembling/hashing)"]:::worker
      end

      DebugUI["Debug Logger UI\n(DebugLogger)"]:::debug
      DebugUtil["Debug Utility\n(debugLog)"]:::debug
    end

    %% Shell wiring
    Entry -->|"renders"| Router
    Router -->|"routes"| Home
    Router -->|"routes"| Privacy
    Router -->|"routes"| Terms

    Home -->|"uses"| Layout
    Layout -->|"includes"| Info
    Home -->|"shows"| SenderUI
    Home -->|"shows"| ReceiverUI

    %% Sender pipeline
    SenderUI -->|"selects file"| FileSend
    FileSend -->|"creates/controls"| Peer
    FileSend <-->|"postMessage (chunks/metadata)"| Worker

    %% Receiver pipeline
    Peer -->|"onmessage (chunks/control)"| FileRecv
    FileRecv <-->|"postMessage (assemble/validate)"| Worker
    ReceiverUI -->|"controls/observes"| FileRecv
    ReceiverUI -->|"session UI"| Peer

    %% Debug/observability
    SenderUI -->|"logs"| DebugUtil
    ReceiverUI -->|"logs"| DebugUtil
    Peer -->|"logs"| DebugUtil
    FileSend -->|"logs"| DebugUtil
    FileRecv -->|"logs"| DebugUtil
    DebugUI <-->|"renders logs"| DebugUtil
  end

  %% ========= Key Runtime Flows (annotated) =========
  subgraph "Key Runtime Flows (as labels on connections)"
    direction TB
    SigNote["Note: Signaling exchange is separate from file transfer.\nSignaling = SDP offer/answer + ICE.\nData plane = binary chunks over DataChannel."]:::note
  end

  OOB -.->|"signaling (SDP/ICE)"| SigNote
  SA ==>|"binary chunks (ArrayBuffer/Blob)\n+ control metadata"| RB

  %% ========= Click Events (mapped components) =========
  click CI "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/.github/workflows/github-pages.yml"
  click DNS "https://github.com/sriharisrihari164-netizen/brotransfer/tree/master/public/CNAME"
  click DNS "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/public/404.html"
  click DNS "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/public/.nojekyll"
  click DNS "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/public/sitemap.xml"

  click Entry "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/index.html"
  click Entry "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/src/main.jsx"
  click Entry "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/src/App.jsx"
  click Entry "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/vite.config.js"

  click Home "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/src/pages/Home.jsx"
  click Privacy "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/src/pages/PrivacyPolicy.jsx"
  click Terms "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/src/pages/TermsOfService.jsx"

  click Layout "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/src/components/Layout.jsx"
  click Layout "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/src/components/Header.jsx"
  click Layout "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/src/components/Logo.jsx"

  click Info "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/src/components/Instructions.jsx"
  click Info "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/src/components/Features.jsx"

  click SenderUI "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/src/components/Sender.jsx"
  click SenderUI "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/src/components/FileDrop.jsx"
  click ReceiverUI "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/src/components/Receiver.jsx"

  click Peer "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/src/hooks/usePeer.js"
  click FileSend "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/src/hooks/useFileSender.js"
  click FileRecv "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/src/hooks/useFileReceiver.js"
  click Worker "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/src/workers/fileWorker.js"

  click DebugUI "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/src/components/DebugLogger.jsx"
  click DebugUtil "https://github.com/sriharisrihari164-netizen/brotransfer/blob/master/src/utils/debugLog.js"

  %% ========= Styles =========
  classDef person fill:#FFE8A3,stroke:#8A6D00,stroke-width:1px,color:#2A1F00
  classDef external fill:#E6E6E6,stroke:#666,stroke-width:1px,color:#111
  classDef cloud fill:#E8F3FF,stroke:#2B6CB0,stroke-width:1px,color:#0B2A4A
  classDef container fill:#D9F2FF,stroke:#0077B6,stroke-width:2px,color:#06233B
  classDef frontend fill:#CFE8FF,stroke:#2F5DA8,stroke-width:1px,color:#0B1F3A
  classDef page fill:#E3D7FF,stroke:#5A3FB8,stroke-width:1px,color:#1E103A
  classDef ui fill:#D6F5D6,stroke:#2F7D32,stroke-width:1px,color:#0B2A0C
  classDef core fill:#BFEED0,stroke:#1B7F5A,stroke-width:2px,color:#06261A
  classDef worker fill:#FFE0CC,stroke:#C05621,stroke-width:2px,color:#3B1B0A
  classDef debug fill:#FFF2B2,stroke:#B7791F,stroke-width:1px,color:#3A2506
  classDef note fill:#F7FAFC,stroke:#4A5568,stroke-dasharray:4 3,color:#1A202C
```
