# bundit/kord architecture

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

- Interactive diagram: https://gitdiagram.com/bundit/kord
- Repository: https://github.com/bundit/kord

## Overview

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`](https://github.com/bundit/kord/blob/master/server.ts) (API server), [`client/src/App.js`](https://github.com/bundit/kord/blob/master/client/src/App.js) (App shell), [`client/src/components/library-router.js`](https://github.com/bundit/kord/blob/master/client/src/components/library-router.js) (Route layer), [`routes/api-routes.ts`](https://github.com/bundit/kord/blob/master/routes/api-routes.ts) (Route modules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_landing["Landing site"]
  node_landing_site["Landing site<br/>Gatsby marketing"]
  node_landing_login["Login panel<br/>auth entry<br/>[login-panel.js]"]
  node_landing_auth_provider["Auth helper<br/>landing util<br/>[auth-provider.js]"]
end

subgraph group_client["React app"]
  node_client_shell["App shell<br/>React SPA<br/>[App.js]"]
  node_client_router["Route layer<br/>SPA routing<br/>[library-router.js]"]
  node_client_redux[("Redux store<br/>state hub<br/>[store.js]")]
  node_client_search["Search flow<br/>feature area"]
  node_client_library["Library flow<br/>feature area"]
  node_client_player_ui["Player UI<br/>playback UI<br/>[player.js]"]
  node_client_player_adapters["Player adapters<br/>provider playback<br/>[spotify-player.js]"]
  node_client_storage["Client storage<br/>persistence<br/>[sync.js]"]
end

subgraph group_backend["API backend"]
  node_backend_server["API server<br/>Express/TS<br/>[server.ts]"]
  node_backend_routes["Route modules<br/>HTTP routes<br/>[api-routes.ts]"]
  node_backend_controllers["Controllers<br/>request handlers<br/>[api-controller.ts]"]
  node_backend_middleware["Middleware<br/>guards"]
  node_backend_auth["Auth setup<br/>passport/JWT<br/>[passport-setup.ts]"]
  node_backend_db[("Database setup<br/>PostgreSQL<br/>[database-setup.ts]")]
  node_backend_services["Auth services<br/>credentials/token logic<br/>[auth.ts]"]
end

subgraph group_external["External services"]
  node_external_providers(("Music providers<br/>Spotify/SoundCloud/YouTube"))
  node_external_db[("PostgreSQL<br/>data store")]
end

node_landing_site -->|"contains"| node_landing_login
node_landing_login -->|"uses"| node_landing_auth_provider
node_landing_site -.->|"auth handoff"| node_backend_server
node_client_shell -->|"navigates"| node_client_router
node_client_shell -->|"state"| node_client_redux
node_client_router -->|"routes"| node_client_search
node_client_router -->|"routes"| node_client_library
node_client_shell -->|"renders"| node_client_player_ui
node_client_player_ui -->|"drives playback"| node_client_player_adapters
node_client_redux -.->|"persists"| node_client_storage
node_client_search -.->|"queries"| node_backend_server
node_client_library -.->|"loads"| node_backend_server
node_client_player_adapters -.->|"embed/sdk"| node_external_providers
node_backend_server -->|"mounts"| node_backend_routes
node_backend_routes -->|"delegates"| node_backend_controllers
node_backend_routes -->|"protects"| node_backend_middleware
node_backend_controllers -->|"uses"| node_backend_auth
node_backend_auth -->|"secrets"| node_backend_services
node_backend_server -->|"connects"| node_backend_db
node_backend_db -->|"stores"| node_external_db
node_backend_server -.->|"brokered access"| node_external_providers

click node_landing_site "https://github.com/bundit/kord/tree/master/landing"
click node_landing_login "https://github.com/bundit/kord/blob/master/landing/src/components/login-panel.js"
click node_landing_auth_provider "https://github.com/bundit/kord/blob/master/landing/src/utils/auth-provider.js"
click node_client_shell "https://github.com/bundit/kord/blob/master/client/src/App.js"
click node_client_router "https://github.com/bundit/kord/blob/master/client/src/components/library-router.js"
click node_client_redux "https://github.com/bundit/kord/blob/master/client/src/redux/store.js"
click node_client_search "https://github.com/bundit/kord/blob/master/client/src/components/search-results-page.js"
click node_client_library "https://github.com/bundit/kord/blob/master/client/src/components/library-view-page.js"
click node_client_player_ui "https://github.com/bundit/kord/blob/master/client/src/components/player.js"
click node_client_player_adapters "https://github.com/bundit/kord/blob/master/client/src/components/spotify-player.js"
click node_client_storage "https://github.com/bundit/kord/blob/master/client/src/redux/sync.js"
click node_backend_server "https://github.com/bundit/kord/blob/master/server.ts"
click node_backend_routes "https://github.com/bundit/kord/blob/master/routes/api-routes.ts"
click node_backend_controllers "https://github.com/bundit/kord/blob/master/controllers/api-controller.ts"
click node_backend_middleware "https://github.com/bundit/kord/blob/master/middleware/ensureAuthenticated.ts"
click node_backend_auth "https://github.com/bundit/kord/blob/master/config/passport-setup.ts"
click node_backend_db "https://github.com/bundit/kord/blob/master/config/database-setup.ts"
click node_backend_services "https://github.com/bundit/kord/blob/master/services/auth.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_landing_site,node_landing_login,node_landing_auth_provider toneBlue
class node_client_shell,node_client_router,node_client_redux,node_client_search,node_client_library,node_client_player_ui,node_client_player_adapters,node_client_storage toneAmber
class node_backend_server,node_backend_routes,node_backend_controllers,node_backend_middleware,node_backend_auth,node_backend_db,node_backend_services toneMint
class node_external_providers,node_external_db toneRose
```

## Components

### Landing site

Public Gatsby surface for marketing and auth entry

- [Landing site](https://github.com/bundit/kord/tree/master/landing): Gatsby marketing · Public pages for login, signup, privacy, and terms; hands off auth entry to backend · `landing`
- [Login panel](https://github.com/bundit/kord/blob/master/landing/src/components/login-panel.js): auth entry · Landing-page auth entry component that routes users into sign-in/signup flows · `landing/src/components/login-panel.js`
- [Auth helper](https://github.com/bundit/kord/blob/master/landing/src/utils/auth-provider.js): landing util · 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](https://github.com/bundit/kord/blob/master/client/src/App.js): React SPA · Main browser application for search, library, playlists, queue, and playback · `client/src/App.js`
- [Route layer](https://github.com/bundit/kord/blob/master/client/src/components/library-router.js): SPA routing · Client-side routing for library and search views with deployment fallback · `client/src/components/library-router.js`
- [Redux store](https://github.com/bundit/kord/blob/master/client/src/redux/store.js): state hub · Central state layer with reducers, actions, and persistence sync · `client/src/redux/store.js`
- [Search flow](https://github.com/bundit/kord/blob/master/client/src/components/search-results-page.js): feature area · Search bar, history, results, and track-list views · `client/src/components/search-results-page.js`
- [Library flow](https://github.com/bundit/kord/blob/master/client/src/components/library-view-page.js): feature area · Playlists, artists, tracks, and library pages · `client/src/components/library-view-page.js`
- [Player UI](https://github.com/bundit/kord/blob/master/client/src/components/player.js): playback UI · Shared controls, track info, queue, volume, and minified/expanded player views · `client/src/components/player.js`
- [Player adapters](https://github.com/bundit/kord/blob/master/client/src/components/spotify-player.js): provider playback · Provider-specific playback implementations for Spotify, SoundCloud, and YouTube · `client/src/components/spotify-player.js`
- [Client storage](https://github.com/bundit/kord/blob/master/client/src/redux/sync.js): persistence · 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](https://github.com/bundit/kord/blob/master/server.ts): Express/TS · Root Express backend that serves auth, app, API, and user routes · `server.ts`
- [Route modules](https://github.com/bundit/kord/blob/master/routes/api-routes.ts): HTTP routes · Auth, API, app, index, user, and provider-specific route modules · `routes/api-routes.ts`
- [Controllers](https://github.com/bundit/kord/blob/master/controllers/api-controller.ts): request handlers · Auth, API, and user controllers coordinating request handling · `controllers/api-controller.ts`
- [Middleware](https://github.com/bundit/kord/blob/master/middleware/ensureAuthenticated.ts): guards · Authentication enforcement and production host/HTTPS normalization · `middleware/ensureAuthenticated.ts`
- [Auth setup](https://github.com/bundit/kord/blob/master/config/passport-setup.ts): passport/JWT · Passport configuration plus secret and token handling · `config/passport-setup.ts`
- [Database setup](https://github.com/bundit/kord/blob/master/config/database-setup.ts): PostgreSQL · Database connection and persistence setup for backend data · `config/database-setup.ts`
- [Auth services](https://github.com/bundit/kord/blob/master/services/auth.ts): credentials/token logic · 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**: Spotify/SoundCloud/YouTube · Upstream APIs and OAuth targets used for search, linking, and playback
- **PostgreSQL**: data store · Persistent backend database for user and linked-account data

## Connections

- 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