# syedmdabuhaider/jamsync_web_advanced architecture

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

- Interactive diagram: https://gitdiagram.com/syedmdabuhaider/jamsync_web_advanced
- Repository: https://github.com/syedmdabuhaider/jamsync_web_advanced

## Overview

**JamSync** is a **single-service web application** (Node.js + Express) serving a **static frontend** (HTML/CSS/JS) and a **realtime synchronization channel** via **Socket.io** so **two clients** can keep an **HTML5 audio player** in sync (play/pause/seek; chat planned).

From the tree + README, there’s **no separate frontend build system**, **no database**, and the “music library” is **local `.mp3` files** under `public/music/` plus a `playlists.json` file.

So the core architecture is:
- **Browser clients** (UI + audio element + Socket.io client)
- **Node/Express server** (static hosting + Socket.io server)
- **Static assets** (`public/…`) including **MP3 files**
- **Playlist metadata** (`playlists.json`)
- **Realtime event bus** (Socket.io over WebSocket / long-poll fallback)

##### Backend (runtime boundary: Node.js process)
- `server.js`
Likely: creates Express app, serves `public/` as static, mounts Socket.io, defines sync events (play/pause/seek), possibly exposes endpoints for playlists.
- `package.json`, `package-lock.json`, `node_modules/`
Confirms Node ecosystem; dependencies likely include `express` and `socket.io`.

##### Frontend (runtime boundary: browser tab)
- `public/index.html` – main UI shell
- `public/css/style.css` – styling
- `public/js/script.js` – client logic: audio controls, emits/receives Socket.io events, updates DOM/audio element

##### “Data” / content
- `public/music/*.mp3` – the actual audio content served over HTTP as static files

##### Main components to include (separate into many components)
When drawing, avoid one big “Server” and one big “Client”. Split them into concrete components that map to files/responsibilities.

##### UI Layer
- Playlist view
- Play/Pause button
- Seek bar / time scrubber
##### Audio Playback Engine
- HTML5 `<audio>` element
- Current track URL points to `/music/<file>.mp3`
##### Sync Controller (client)
- Captures user intents (play/pause/seek)
- Emits Socket.io events
- Applies remote events to the audio element (set currentTime, play(), pause())
##### Library/Playlist Loader
- Loads `playlists.json` (either from `/playlists.json` or via a server route)
- Renders available tracks / playlist order

##### HTTP Server (Express)
- Serves `index.html`, `style.css`, `script.js`
- Serves `/music/*.mp3` as static files
- Serves `playlists.json` (static or API route)
##### Socket.io Realtime Server
- Connection management (clients join/leave)
- Receives sync events from one client
- Broadcasts events to the other client(s)
##### Sync Event Router / Handler
- Event types: `PLAY`, `PAUSE`, `SEEK`, possibly `TRACK_CHANGE`
- Any server-side normalization you do (e.g., attach timestamp, room id)
- In-memory “current track / current time / playing” (per room)
- “Room” concept (even if it’s implicitly “everyone”)

- **Static File Store**
- MP3 assets under `public/music/`
- **JSON Metadata Store**
- `playlists.json` as a file-based “database”

- **Socket.io protocol** (WebSocket)
- No cloud services shown in tree; don’t invent S3/CDN/auth unless README/code says so.

##### Architectural patterns to highlight (only what’s evidenced)
- **Static frontend + Node backend** (no SPA framework implied; plain JS)
- **Realtime pub/sub fanout** using Socket.io (server as relay)
- **File-based library** (MP3s + JSON) instead of database
- **In-memory session/state** likely (if sync requires remembering current status for late joiners)

If “two users only” is a core constraint, show it as a **room with max 2 clients** (even if not enforced in code yet).

##### Client B sets `audio.currentTime = 120.5`

- Single Node.js process
- Serves static + Socket.io
- Clients connect over LAN/Internet
This prevents people from assuming multiple services.

##### Two parallel channels
- Media delivery channel (HTTP static MP3)
- Control/sync channel (Socket.io)

##### Source of truth
- Is the source of truth “initiator’s player state” (broadcast-only)?
- Or “server room state” (server stores current track/time)?
Whichever `server.js` implements, label it explicitly.

##### Playlist/library mechanics
- Where playlists are read from (root `playlists.json` vs `public/playlists.json`)
- That “uploading” is currently “copy MP3 into `public/music/`” (manual content management)

##### Practical checklist to ensure “most accurate” from this repo
- Actual Socket.io event names and payload fields (use them as labels)
- Whether there are “rooms” or a single global namespace
- Whether server tracks playback state in memory
- Exact routes used for playlists and music files

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% A) System Context (C4 L1)
  %% =========================
  subgraph "A) System Context"
    UA["User A"]:::person
    UB["User B"]:::person

    SYS["JamSync (Single-Service Web App)"]:::system

    UA -->|"uses"| SYS
    UB -->|"uses"| SYS

    note_sys["Purpose:Two clients keep an HTML5 audio player in sync (play/pause/seek).Chat planned."]:::note
    SYS --- note_sys
  end

  %% =========================
  %% B) Container Diagram (C4 L2)
  %% =========================
  subgraph "B) Containers"
    direction TB

    subgraph "Browser Client A (Tab)"
      direction TB
      A_UI["UI Layer (playlist view + controls)"]:::client
      A_AUDIO["Audio Playback Engine (HTML5 audio)"]:::client
      A_SYNC["Sync Controller (Socket.io client)"]:::client
      A_LOADER["Library/Playlist Loader (fetch + render)"]:::client
      A_UI -->|"controls"| A_AUDIO
      A_UI -->|"user_intents"| A_SYNC
      A_LOADER -->|"select_track"| A_AUDIO
      A_SYNC -->|"apply_remote_events"| A_AUDIO
    end

    subgraph "Browser Client B (Tab)"
      direction TB
      B_UI["UI Layer (playlist view + controls)"]:::client
      B_AUDIO["Audio Playback Engine (HTML5 audio)"]:::client
      B_SYNC["Sync Controller (Socket.io client)"]:::client
      B_LOADER["Library/Playlist Loader (fetch + render)"]:::client
      B_UI -->|"controls"| B_AUDIO
      B_UI -->|"user_intents"| B_SYNC
      B_LOADER -->|"select_track"| B_AUDIO
      B_SYNC -->|"apply_remote_events"| B_AUDIO
    end

    subgraph "Node.js Server (single process)"
      direction TB
      S_HTTP["Express HTTP Server (static + routes)"]:::server
      S_SIO["Socket.io Realtime Server"]:::realtime
      S_SYNC["Sync Event Router/Handlers (PLAY/PAUSE/SEEK/TRACK_CHANGE)"]:::server
      S_STATE["In-memory Room/Playback State (optional)"]:::state

      S_HTTP -->|"mounts"| S_SIO
      S_SIO -->|"dispatches_to"| S_SYNC
      S_SYNC <-->|"read/write"| S_STATE
    end

    subgraph "Storage (File-based; no DB)"
      direction TB
      STORE_PUBLIC[("Static Asset Store (public/)")]:::storage
      STORE_MP3[("MP3 Music Library (public/music/*.mp3)")]:::storage
      STORE_PLAYLISTS[("Playlist Metadata (playlists.json)")]:::storage
      STORE_PLAYLISTS_PUBLIC[("Client Playlist JSON (public/playlists.json)")]:::storage

      STORE_PUBLIC -->|"contains"| STORE_MP3
      STORE_PUBLIC -->|"may_contain"| STORE_PLAYLISTS_PUBLIC
    end

    CHAT_PLAN["Planned:Realtime Chat (Socket.io events)"]:::planned
  end

  %% -------------------------
  %% HTTP Flows
  %% -------------------------
  A_UI -->|"HTTP_GET / (index.html)"| S_HTTP
  A_UI -->|"HTTP_GET /css/style.css"| S_HTTP
  A_UI -->|"HTTP_GET /js/script.js"| S_HTTP
  A_LOADER -->|"HTTP_GET /playlists.json"| S_HTTP
  A_AUDIO -->|"HTTP_GET /music/<track>.mp3"| S_HTTP

  B_UI -->|"HTTP_GET / (index.html)"| S_HTTP
  B_UI -->|"HTTP_GET /css/style.css"| S_HTTP
  B_UI -->|"HTTP_GET /js/script.js"| S_HTTP
  B_LOADER -->|"HTTP_GET /playlists.json"| S_HTTP
  B_AUDIO -->|"HTTP_GET /music/<track>.mp3"| S_HTTP

  S_HTTP -->|"serves_static_assets"| STORE_PUBLIC
  S_HTTP -->|"serves_mp3_bytes"| STORE_MP3
  S_HTTP -->|"serves_playlists_json"| STORE_PLAYLISTS
  S_HTTP -->|"serves_public_playlists_json"| STORE_PLAYLISTS_PUBLIC

  %% -------------------------
  %% WebSocket / Socket.io Flows
  %% -------------------------
  A_SYNC <-->|"WebSocket/Socket.io connect"| S_SIO
  B_SYNC <-->|"WebSocket/Socket.io connect"| S_SIO

  A_SYNC -->|"emit play/pause/seek/trackChange"| S_SIO
  S_SIO -->|"broadcast to other client(s)"| B_SYNC

  B_SYNC -->|"emit play/pause/seek/trackChange"| S_SIO
  S_SIO -->|"broadcast to other client(s)"| A_SYNC

  S_SIO -.->|"planned_events:chat"| CHAT_PLAN

  %% =========================
  %% C) Component Diagram (inside Node.js Server)
  %% =========================
  subgraph "C) Node.js Server Components (server.js)"
    direction TB
    C_BOOT["Process Bootstrap (create HTTP + attach Socket.io)"]:::server
    C_STATIC["Express Static Middleware (serve public/)"]:::server
    C_PLAYLISTS["Playlist JSON Handler (static or route)"]:::server
    C_SIO["Socket.io Server (connection mgmt)"]:::realtime
    C_HANDLERS["Sync Handlers (PLAY/PAUSE/SEEK/TRACK_CHANGE)"]:::server
    C_ROOMS["Room/State Manager (max 2 clients; optional)"]:::state

    C_BOOT -->|"configures"| C_STATIC
    C_BOOT -->|"configures"| C_PLAYLISTS
    C_BOOT -->|"attaches"| C_SIO
    C_SIO -->|"routes_events_to"| C_HANDLERS
    C_HANDLERS <-->|"uses"| C_ROOMS

    C_STATIC -->|"reads_files"| STORE_PUBLIC
    C_PLAYLISTS -->|"reads_file"| STORE_PLAYLISTS
    C_PLAYLISTS -->|"may_read"| STORE_PLAYLISTS_PUBLIC
  end

  %% =========================
  %% D) Sequence Overview (sync)
  %% (Rendered as flow nodes to keep single-diagram output)
  %% =========================
  subgraph "D) Sync Sequences (high-level)"
    direction TB

    subgraph "1) Play/Pause"
      direction TB
      SP1["User A clicks Play/Pause"]:::seq
      SP2["Client A emits PLAY/PAUSE {trackId,currentTime,clientTimestamp}"]:::seq
      SP3["Server relays/broadcasts event"]:::seq
      SP4["Client B applies: load track (if needed), seek, play()/pause()"]:::seq
      SP1 --> SP2 --> SP3 --> SP4
    end

    subgraph "2) Seek"
      direction TB
      SS1["User A drags seek bar to t=120.5"]:::seq
      SS2["Client A emits SEEK {t:120.5}"]:::seq
      SS3["Server broadcasts SEEK"]:::seq
      SS4["Client B sets audio.currentTime=120.5"]:::seq
      SS1 --> SS2 --> SS3 --> SS4
    end
  end

  %% =========================
  %% E) Deployment View
  %% =========================
  subgraph "E) Deployment (single service)"
    direction TB
    D_CLIENTS["Client Devices (LAN/Internet)"]:::external
    D_NODE["Host running Node.js process (Express + Socket.io)"]:::server
    D_FILES["Local Project Files (public/, playlists.json)"]:::storage

    D_CLIENTS -->|"HTTP + WebSocket"| D_NODE
    D_NODE -->|"reads/serves"| D_FILES
  end

  %% =========================
  %% Click Events (from component_mapping)
  %% =========================
  click S_HTTP "https://github.com/syedmdabuhaider/jamsync_web_advanced/blob/main/server.js"
  click S_SIO "https://github.com/syedmdabuhaider/jamsync_web_advanced/blob/main/server.js"
  click S_SYNC "https://github.com/syedmdabuhaider/jamsync_web_advanced/blob/main/server.js"

  click C_BOOT "https://github.com/syedmdabuhaider/jamsync_web_advanced/blob/main/server.js"
  click C_STATIC "https://github.com/syedmdabuhaider/jamsync_web_advanced/blob/main/server.js"
  click C_PLAYLISTS "https://github.com/syedmdabuhaider/jamsync_web_advanced/blob/main/server.js"
  click C_SIO "https://github.com/syedmdabuhaider/jamsync_web_advanced/blob/main/server.js"
  click C_HANDLERS "https://github.com/syedmdabuhaider/jamsync_web_advanced/blob/main/server.js"
  click C_ROOMS "https://github.com/syedmdabuhaider/jamsync_web_advanced/blob/main/server.js"

  click A_UI "https://github.com/syedmdabuhaider/jamsync_web_advanced/blob/main/public/index.html"
  click A_AUDIO "https://github.com/syedmdabuhaider/jamsync_web_advanced/blob/main/public/index.html"
  click B_UI "https://github.com/syedmdabuhaider/jamsync_web_advanced/blob/main/public/index.html"
  click B_AUDIO "https://github.com/syedmdabuhaider/jamsync_web_advanced/blob/main/public/index.html"

  click A_SYNC "https://github.com/syedmdabuhaider/jamsync_web_advanced/blob/main/public/js/script.js"
  click A_LOADER "https://github.com/syedmdabuhaider/jamsync_web_advanced/blob/main/public/js/script.js"
  click B_SYNC "https://github.com/syedmdabuhaider/jamsync_web_advanced/blob/main/public/js/script.js"
  click B_LOADER "https://github.com/syedmdabuhaider/jamsync_web_advanced/blob/main/public/js/script.js"

  click STORE_PUBLIC "https://github.com/syedmdabuhaider/jamsync_web_advanced/tree/main/public/"
  click STORE_MP3 "https://github.com/syedmdabuhaider/jamsync_web_advanced/tree/main/public/music/"
  click STORE_PLAYLISTS "https://github.com/syedmdabuhaider/jamsync_web_advanced/blob/main/playlists.json"
  click STORE_PLAYLISTS_PUBLIC "https://github.com/syedmdabuhaider/jamsync_web_advanced/blob/main/public/playlists.json"

  click note_sys "https://github.com/syedmdabuhaider/jamsync_web_advanced/blob/main/package.json"

  %% =========================
  %% Styles (color required)
  %% =========================
  classDef person fill:#E3F2FD,stroke:#1565C0,stroke-width:1px,color:#0D47A1
  classDef system fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px,color:#0D47A1
  classDef client fill:#D6ECFF,stroke:#1E88E5,stroke-width:1px,color:#0D47A1
  classDef server fill:#DFF5E1,stroke:#2E7D32,stroke-width:1px,color:#1B5E20
  classDef realtime fill:#E9D7FF,stroke:#6A1B9A,stroke-width:2px,color:#4A148C
  classDef state fill:#C8E6C9,stroke:#1B5E20,stroke-dasharray:4 3,color:#1B5E20
  classDef storage fill:#FFE6C7,stroke:#EF6C00,stroke-width:1px,color:#E65100
  classDef planned fill:#F5F5F5,stroke:#757575,stroke-dasharray:5 4,color:#424242
  classDef external fill:#FFF3E0,stroke:#FB8C00,stroke-width:1px,color:#E65100
  classDef note fill:#FFFDE7,stroke:#F9A825,stroke-width:1px,color:#6D4C41
  classDef seq fill:#FFFFFF,stroke:#90A4AE,stroke-width:1px,color:#263238
```
