# freeman-jiang/beatsync architecture

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

- Interactive diagram: https://gitdiagram.com/freeman-jiang/beatsync
- Repository: https://github.com/freeman-jiang/beatsync

## Overview

##### Project type and purpose
- Beatsync is a full-stack, real-time web audio player built for millisecond-accurate multi-device synchronization.
- The monorepo uses Turborepo, with three workspaces: a Next.js client (`apps/client`), a Bun HTTP/WebSocket server (`apps/server`), and a shared types-and-utils package (`packages/shared`).

##### File structure
- Top-level “apps” folder splits frontend (`apps/client`) from backend (`apps/server`).
- A “packages/shared” folder contains TypeScript schemas/types used by both client and server.
- The frontend uses Next.js, Tailwind, Shadcn/ui, PostHog integration, WebSocket manager, NTP-inspired sync, and audio components.
- The backend uses Bun, exposes REST routes (`audio`, `upload`, `stats`) and a WebSocket route (`/ws`), plus room management, spatial audio logic, and file storage under the server.

##### README for additional insights
- REST endpoints are used for uploading and retrieving audio files.
- WebSocket is used for real-time clock synchronization, playback commands, and peer status.
- Shared code ensures type safety between client and server (e.g., WSRequest/WSResponse schemas).

##### Detailed capture of essential architectural elements
- NTP sync: the client’s NTP utils call the server’s `/ws` time sync handler, calculate offset, and feed into audio scheduling.
- Upload flow: AudioUploaderMinimal → REST POST `/upload` → server stores file → server notifies other clients via WebSocket broadcast.
- Spatial audio: Client sends pointer position → server’s spatial.ts computes per-device volume → server broadcasts volume adjustments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client (Next.js)" 
        direction TB
        ClientApp["Next.js Client"]:::frontend
        EntryPage["app/page.tsx"]:::frontend
        EntryLayout["app/layout.tsx"]:::frontend
        UIComponents["UI Components"]:::frontend
        RoomPage["Room Page"]:::frontend
        WSManager["WebSocketManager"]:::frontend
        NTPUtils["NTP Sync Utils"]:::frontend
        Player["Player (Audio Playback)"]:::frontend
        MusicControls["MusicControls"]:::frontend
        AudioUploader["AudioUploaderMinimal"]:::frontend
        APIHelpers["HTTP API Helpers"]:::frontend
        GlobalStore["Global Store"]:::frontend
        RoomStore["Room Store"]:::frontend
        PostHogProvider["PostHogProvider"]:::frontend
        ClientPublic["Public Assets"]:::storage

        ClientApp --> EntryPage
        ClientApp --> EntryLayout
        EntryPage --> RoomPage
        RoomPage --> WSManager
        RoomPage --> Player
        RoomPage --> MusicControls
        RoomPage --> NTPUtils
        EntryPage --> AudioUploader
        UIComponents --> AudioUploader
        UIComponents --> Player
        UIComponents --> MusicControls
        UIComponents --> WSManager
        AudioUploader --> APIHelpers
        APIHelpers -->|HTTP GET/POST| RESTRoutes
        RoomPage -->|Type Imports| SharedPkg
        ClientApp -->|Analytics Events| PostHog
        ClientApp --> PostHogProvider
        ClientApp --> ClientPublic
        EntryPage --> UIComponents
        ClientApp --> GlobalStore
        ClientApp --> RoomStore
    end

    %% Server Side
    subgraph "Server (Bun)" 
        direction TB
        ServerApp["Bun Server"]:::backend
        ServerIndex["index.ts"]:::backend
        AudioRoute["audio.ts"]:::backend
        UploadRoute["upload.ts"]:::backend
        StatsRoute["stats.ts"]:::backend
        WebsocketRoute["websocket.ts"]:::backend
        WebsocketHandlers["websocketHandlers.ts"]:::backend
        RoomManagerNode["roomManager.ts"]:::backend
        SpatialCore["spatial.ts"]:::backend
        SpatialUtils["utils/spatial.ts"]:::backend
        WSUtilsNode["utils/websocket.ts"]:::backend
        FileStorage["Audio Storage"]:::storage

        ServerApp --> ServerIndex
        ServerIndex --> AudioRoute
        ServerIndex --> UploadRoute
        ServerIndex --> StatsRoute
        ServerIndex --> WebsocketRoute
        WebsocketRoute --> WebsocketHandlers
        ServerIndex --> RoomManagerNode
        RoomManagerNode --> SpatialCore
        SpatialCore --> SpatialUtils
        ServerIndex --> WSUtilsNode
        ServerIndex --> FileStorage
        ServerIndex -->|Type Imports| SharedPkg
    end

    %% Shared Package
    subgraph "Shared Types & Utils" 
        direction TB
        SharedPkg["packages/shared"]:::shared
        HTTPSchema["HTTPRequest.ts"]:::shared
        WSSchema["WSRequest.ts"]:::shared
        SharedPkg --> HTTPSchema
        SharedPkg --> WSSchema
    end

    %% External Services
    PostHog["PostHog Analytics"]:::external

    %% Interactions
    ClientApp -->|HTTP| AudioRoute
    ClientApp -->|HTTP| UploadRoute
    ClientApp -->|HTTP| StatsRoute
    ClientApp ---|WebSocket| WebsocketRoute
    WebsocketRoute ---|Broadcast| WSManager
    ServerApp ---|Broadcast| WSManager
    WebsocketHandlers ---|Realtime| RoomPage

    %% Click Events
    click ClientApp "https://github.com/freeman-jiang/beatsync/tree/main/apps/client"
    click EntryPage "https://github.com/freeman-jiang/beatsync/blob/main/apps/client/src/app/page.tsx"
    click EntryLayout "https://github.com/freeman-jiang/beatsync/blob/main/apps/client/src/app/layout.tsx"
    click RoomPage "https://github.com/freeman-jiang/beatsync/blob/main/apps/client/src/app/room/[roomId]/page.tsx"
    click UIComponents "https://github.com/freeman-jiang/beatsync/tree/main/apps/client/src/components"
    click WSManager "https://github.com/freeman-jiang/beatsync/blob/main/apps/client/src/components/room/WebSocketManager.tsx"
    click NTPUtils "https://github.com/freeman-jiang/beatsync/blob/main/apps/client/src/utils/ntp.ts"
    click Player "https://github.com/freeman-jiang/beatsync/blob/main/apps/client/src/components/room/Player.tsx"
    click MusicControls "https://github.com/freeman-jiang/beatsync/blob/main/apps/client/src/components/room/MusicControls.tsx"
    click AudioUploader "https://github.com/freeman-jiang/beatsync/blob/main/apps/client/src/components/AudioUploaderMinimal.tsx"
    click APIHelpers "https://github.com/freeman-jiang/beatsync/blob/main/apps/client/src/lib/api.ts"
    click GlobalStore "https://github.com/freeman-jiang/beatsync/blob/main/apps/client/src/store/global.tsx"
    click RoomStore "https://github.com/freeman-jiang/beatsync/blob/main/apps/client/src/store/room.tsx"
    click PostHogProvider "https://github.com/freeman-jiang/beatsync/blob/main/apps/client/src/components/PostHogProvider.tsx"
    click ClientPublic "https://github.com/freeman-jiang/beatsync/tree/main/apps/client/public"
    click ServerIndex "https://github.com/freeman-jiang/beatsync/blob/main/apps/server/src/index.ts"
    click AudioRoute "https://github.com/freeman-jiang/beatsync/blob/main/apps/server/src/routes/audio.ts"
    click UploadRoute "https://github.com/freeman-jiang/beatsync/blob/main/apps/server/src/routes/upload.ts"
    click StatsRoute "https://github.com/freeman-jiang/beatsync/blob/main/apps/server/src/routes/stats.ts"
    click WebsocketRoute "https://github.com/freeman-jiang/beatsync/blob/main/apps/server/src/routes/websocket.ts"
    click WebsocketHandlers "https://github.com/freeman-jiang/beatsync/blob/main/apps/server/src/routes/websocketHandlers.ts"
    click RoomManagerNode "https://github.com/freeman-jiang/beatsync/blob/main/apps/server/src/roomManager.ts"
    click SpatialCore "https://github.com/freeman-jiang/beatsync/blob/main/apps/server/src/spatial.ts"
    click SpatialUtils "https://github.com/freeman-jiang/beatsync/blob/main/apps/server/src/utils/spatial.ts"
    click WSUtilsNode "https://github.com/freeman-jiang/beatsync/blob/main/apps/server/src/utils/websocket.ts"
    click SharedPkg "https://github.com/freeman-jiang/beatsync/tree/main/packages/shared"
    click HTTPSchema "https://github.com/freeman-jiang/beatsync/blob/main/packages/shared/types/HTTPRequest.ts"
    click WSSchema "https://github.com/freeman-jiang/beatsync/blob/main/packages/shared/types/WSRequest.ts"

    %% Styles
    classDef frontend fill:#aecbfa,stroke:#333,stroke-width:1px
    classDef backend fill:#a5d6a7,stroke:#333,stroke-width:1px
    classDef shared fill:#fff59d,stroke:#333,stroke-width:1px
    classDef storage fill:#ffe082,stroke:#333,stroke-width:1px
    classDef external fill:#cfd8dc,stroke:#333,stroke-width:1px
```
