How freeman-jiang/beatsync works
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.