How bundit/kord works
1. Repository shape
- This is a monorepo for a music aggregation product, split into three deployable surfaces:
- landing/: Gatsby marketing/auth entry site
- client/: React single-page application for the actual product
- root backend: Express/TypeScript API and auth server
- The README indicates the local dev topology: backend on 8888, landing on 8000, app on 3000/app.
2. Primary product boundary
- The main application lets a user search, browse, and play music across Spotify, SoundCloud, and YouTube from one UI.
- The app is browser-only and explicitly targets Chromium and Firefox, which matters because playback and OAuth flows depend on browser capabilities.
3. Landing site subsystem
- landing/ is a separate Gatsby site used for public pages like login, signup, privacy, and terms.
- It is mostly presentational and routing/content oriented, with auth-related entry points that hand off to the backend.
4. Main React application
- client/ is the interactive app shell built with React.
- The UI is organized by feature area: library, search, playlist, artist, settings, queue, and player.
- The presence of public/_redirects and route-specific components suggests client-side routing with deployment-time fallback for SPA paths.
5. State management and app data flow
- The app uses Redux as the central state layer.
- redux/actions, redux/reducers, and redux/store split state by domain: player, search, library, and user.
- redux/sync.js plus localStorage.js / sessionStorage.js indicate persistence of selected client state across refreshes and sessions.
6. Playback subsystem
- Playback is provider-adapted rather than monolithic:
- spotify-player.js
- soundcloud-player.tsx
- youtube-player.tsx
- Shared player UI is composed from controls like seek bar, volume, queue, track info, expanded/minified player variants, and overlays/modals.
- This is the core boundary where external media SDKs or embeds meet the Redux player state.
7. Music domain features
- Library management includes playlists, artists, tracks, and user queue, with separate list/item/page components for each.
- Search is its own subsystem with search bar, search results, search history, and track list views.
- This implies a workflow of: user input → search Redux actions → API/provider lookup → normalized results → UI lists.
8. Backend API and auth server
- The root server is an Express.js backend written in TypeScript.
- Route modules are separated by concern:
- auth-routes.ts
- api-routes.ts
- user-routes.ts
- app-routes.ts
- index-routes.ts
- provider-specific auth routes for Spotify, YouTube, SoundCloud
- Controllers mirror those concerns and contain request handling for auth, API behavior, and user operations.
9. Authentication and account linking
- Auth is built on Passport.js plus JWT/session-style token handling.
- The server supports OAuth flows for Spotify and YouTube, including separate “login” and “link” callbacks, which suggests both account sign-in and provider-account linking.
- middleware/ensureAuthenticated.ts enforces protected API access.
10. Persistence and infrastructure
- The backend persists data in PostgreSQL via config/database-setup.ts.
- services/keys.ts and services/auth.ts centralize secret/JWT/OAuth-related logic.
- Environment variables drive client API keys and server credentials/callback URLs, which means the system is heavily configured by deployment environment.
11. Request/response boundary
- Typical flow is:
- browser hits landing or client
- client dispatches Redux actions
- actions call backend routes or third-party APIs
- backend authenticates, exchanges tokens, and stores user data
- results are reduced into client state and rendered by feature components
- The backend is the trust boundary for user identity and linked provider access; the client handles interaction and playback UI.
12. Cross-cutting middleware and deployment concerns
- middleware/ssl.ts and middleware/www.ts indicate production host normalization and HTTPS enforcement.
- public/_redirects and SPA routing modules suggest deployment behind a static host or proxy that must forward app routes correctly.
13. Code organization signal
- The repo uses TypeScript where backend and shared typing matter, and JavaScript/SCSS modules for most client UI.
- types/common, types/models, and client/src/types show that domain types are shared or duplicated to keep provider/user models consistent across server and client.
14. Architecture summary for diagramming
- A good diagram would show three top-level surfaces:
- Landing site
- React app
- Express API/auth backend
- Connect the app to external services:
- Spotify, SoundCloud, YouTube, and Last.fm-related data
- Show PostgreSQL behind the backend, with OAuth/JWT as the authentication layer, and Redux as the client-side state hub.
Main entry points: server.ts API server · App.js App shell · library-router.js Route layer · api-routes.ts Route modules
Components 20
Landing site
Public Gatsby surface for marketing and auth entry
- Landing site · Public pages for login, signup, privacy, and terms; hands off auth entry to backend
landing - Login panel · Landing-page auth entry component that routes users into sign-in/signup flows
landing/src/components/login-panel.js - Auth helper · Helper for provider-specific auth entry and mobile detection
landing/src/utils/auth-provider.js
React app
Browser product surface with Redux state and playback UI
- App shell · Main browser application for search, library, playlists, queue, and playback
client/src/App.js - Route layer · Client-side routing for library and search views with deployment fallback
client/src/components/library-router.js - Redux store · Central state layer with reducers, actions, and persistence sync
client/src/redux/store.js - Search flow · Search bar, history, results, and track-list views
client/src/components/search-results-page.js - Library flow · Playlists, artists, tracks, and library pages
client/src/components/library-view-page.js - Player UI · Shared controls, track info, queue, volume, and minified/expanded player views
client/src/components/player.js - Player adapters · Provider-specific playback implementations for Spotify, SoundCloud, and YouTube
client/src/components/spotify-player.js - Client storage · Local and session storage plus Redux sync for client state persistence
client/src/redux/sync.js
API backend
Express/TypeScript auth and data server
- API server · Root Express backend that serves auth, app, API, and user routes
server.ts - Route modules · Auth, API, app, index, user, and provider-specific route modules
routes/api-routes.ts - Controllers · Auth, API, and user controllers coordinating request handling
controllers/api-controller.ts - Middleware · Authentication enforcement and production host/HTTPS normalization
middleware/ensureAuthenticated.ts - Auth setup · Passport configuration plus secret and token handling
config/passport-setup.ts - Database setup · Database connection and persistence setup for backend data
config/database-setup.ts - Auth services · Shared auth and key management for JWT, OAuth secrets, and callbacks
services/auth.ts
External services
Third-party providers and persistent data store
- Music providers · Upstream APIs and OAuth targets used for search, linking, and playback
- PostgreSQL · Persistent backend database for user and linked-account data
Connections 21
- Landing site → Login panel: contains · Landing site exposes auth entry and public pages
- Login panel → Auth helper: uses · Login/signup entry uses provider-aware auth helpers
- Landing site → API server: auth handoff · Public auth flows redirect into backend routes
- App shell → Route layer: navigates · App shell delegates to routed feature areas
- App shell → Redux store: state · UI reads and dispatches through Redux
- Route layer → Search flow: routes · Search pages are mounted through client routing
- Route layer → Library flow: routes · Library pages are mounted through client routing
- App shell → Player UI: renders · Player controls stay visible across the app
- Player UI → Player adapters: drives playback · Shared controls talk to provider-specific players
- Redux store → Client storage: persists · Selected state is synced to browser storage
- Search flow → API server: queries · Search actions fetch data through backend endpoints
- Library flow → API server: loads · Library and user data are loaded from backend APIs
- Player adapters → Music providers: embed/sdk · Playback adapters integrate with provider SDKs and embeds
- API server → Route modules: mounts · Server composes the route surface from modules
- Route modules → Controllers: delegates · Routes forward work to controllers
- Route modules → Middleware: protects · Protected routes enforce authentication and host rules
- Controllers → Auth setup: uses · Controllers rely on auth/session/token setup
- Auth setup → Auth services: secrets · Auth setup uses shared key and token services
- API server → Database setup: connects · Backend initializes PostgreSQL persistence
- Database setup → PostgreSQL: stores · Database layer persists application data
- API server → Music providers: brokered access · Backend mediates OAuth and API interactions with providers