# beatfly-music/server architecture

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

- Interactive diagram: https://gitdiagram.com/beatfly-music/server
- Repository: https://github.com/beatfly-music/server

## Overview

BeatFly is a backend for a music-streaming service. Clients call the mounted /xrpc API; route modules apply authentication and upload handling where configured, then dispatch to controllers. The principal content workflow is album/track upload, audio compression and database storage, followed by track streaming; favourites, playlists, search, featured content, recommendations, profiles and reports are separate capabilities. Account recovery can send email, and image requests are optimized before delivery. The tree and excerpts support these boundaries, but most controllers and streaming internals were not sampled, so uncertain internal call paths are omitted.

Main entry points: [`server.js`](https://github.com/beatfly-music/server/blob/main/server.js) (Express server), [`utils/db.js`](https://github.com/beatfly-music/server/blob/main/utils/db.js) (Database client), [`controllers/albumController.js`](https://github.com/beatfly-music/server/blob/main/controllers/albumController.js) (Album management), [`routes/albumRoutes.js`](https://github.com/beatfly-music/server/blob/main/routes/albumRoutes.js) (Album routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_server["Express server<br/>[server.js]"]
  node_auth["Authentication<br/>[auth.js]"]
  node_account_routes["Account routes<br/>[accountRoutes.js]"]
  node_album_routes["Album routes<br/>[albumRoutes.js]"]
  node_track_routes["Track routes<br/>[trackRoutes.js]"]
  node_stream_routes["Stream routes<br/>[streamRoutes.js]"]
end

subgraph group_music["Music catalog"]
  node_album_controller["Album management<br/>[albumController.js]"]
  node_track_controller["Track management<br/>[trackController.js]"]
  node_compression["Audio compression<br/>[compressAudio.js]"]
  node_image_routes["Image optimization<br/>[imageRoutes.js]"]
  node_catalog_storage["Music uploads"]
end

subgraph group_listening["Listening features"]
  node_stream_controller["Track streaming"]
  node_playlist_controller["Playlists"]
  node_favourite_controller["Favourites"]
  node_search_controller["Search"]
  node_recommendation_controller["Recommendations"]
  node_featured_controller["Featured content"]
end

subgraph group_identity["Accounts and profiles"]
  node_account_controller["Account services"]
  node_profile_controller["Profiles"]
  node_user_controller["User preferences<br/>[userController.js]"]
end

subgraph group_operations["Administration"]
  node_admin_controller["Administration<br/>[adminController.js]"]
  node_report_controller["Artist reports"]
end

node_client(("API client"))
node_email(("SMTP email"))
node_database[("MySQL database<br/>[schema.sql]")]
node_db_client["Database client<br/>[db.js]"]

node_client -->|"sends requests"| node_server
node_server -->|"mounts routes"| node_account_routes
node_server -->|"mounts routes"| node_album_routes
node_server -->|"mounts routes"| node_track_routes
node_server -->|"mounts routes"| node_stream_routes
node_server -->|"mounts routes"| node_image_routes
node_album_routes -->|"authenticates"| node_auth
node_album_routes -->|"dispatches"| node_album_controller
node_track_routes -->|"authenticates"| node_auth
node_track_routes -->|"dispatches"| node_track_controller
node_stream_routes -->|"dispatches"| node_stream_controller
node_account_routes -->|"dispatches"| node_account_controller
node_album_controller -->|"compresses audio"| node_compression
node_album_controller -->|"stores uploads"| node_catalog_storage
node_album_controller -->|"queries"| node_db_client
node_track_controller -->|"queries"| node_db_client
node_stream_controller -->|"queries"| node_db_client
node_account_controller -->|"queries"| node_db_client
node_account_controller -.->|"sends reset mail"| node_email
node_image_routes -->|"reads images"| node_catalog_storage
node_server -->|"mounts routes"| node_playlist_controller
node_server -->|"mounts routes"| node_favourite_controller
node_server -->|"mounts routes"| node_search_controller
node_server -->|"mounts routes"| node_recommendation_controller
node_server -->|"mounts routes"| node_featured_controller
node_server -->|"mounts routes"| node_profile_controller
node_server -->|"mounts routes"| node_user_controller
node_server -->|"mounts routes"| node_admin_controller
node_server -->|"mounts routes"| node_report_controller
node_db_client -->|"queries"| node_database

click node_server "https://github.com/beatfly-music/server/blob/main/server.js"
click node_auth "https://github.com/beatfly-music/server/blob/main/middleware/auth.js"
click node_account_routes "https://github.com/beatfly-music/server/blob/main/routes/accountRoutes.js"
click node_album_routes "https://github.com/beatfly-music/server/blob/main/routes/albumRoutes.js"
click node_track_routes "https://github.com/beatfly-music/server/blob/main/routes/trackRoutes.js"
click node_stream_routes "https://github.com/beatfly-music/server/blob/main/routes/streamRoutes.js"
click node_album_controller "https://github.com/beatfly-music/server/blob/main/controllers/albumController.js"
click node_track_controller "https://github.com/beatfly-music/server/blob/main/controllers/trackController.js"
click node_compression "https://github.com/beatfly-music/server/blob/main/utils/compressAudio.js"
click node_image_routes "https://github.com/beatfly-music/server/blob/main/routes/imageRoutes.js"
click node_stream_controller "https://github.com/beatfly-music/server/blob/main/controllers/streamController.js"
click node_playlist_controller "https://github.com/beatfly-music/server/blob/main/controllers/playlistController.js"
click node_favourite_controller "https://github.com/beatfly-music/server/blob/main/controllers/favouriteController.js"
click node_search_controller "https://github.com/beatfly-music/server/blob/main/controllers/searchController.js"
click node_recommendation_controller "https://github.com/beatfly-music/server/blob/main/controllers/recommendationController.js"
click node_featured_controller "https://github.com/beatfly-music/server/blob/main/controllers/featuredController.js"
click node_account_controller "https://github.com/beatfly-music/server/blob/main/controllers/accountController.js"
click node_profile_controller "https://github.com/beatfly-music/server/blob/main/controllers/profileController.js"
click node_user_controller "https://github.com/beatfly-music/server/blob/main/controllers/userController.js"
click node_admin_controller "https://github.com/beatfly-music/server/blob/main/controllers/adminController.js"
click node_report_controller "https://github.com/beatfly-music/server/blob/main/controllers/reportController.js"
click node_database "https://github.com/beatfly-music/server/blob/main/schema.sql"
click node_db_client "https://github.com/beatfly-music/server/blob/main/utils/db.js"

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_server,node_auth,node_account_routes,node_album_routes,node_track_routes,node_stream_routes,node_client toneBlue
class node_album_controller,node_track_controller,node_compression,node_image_routes,node_catalog_storage,node_database,node_db_client toneAmber
class node_stream_controller,node_playlist_controller,node_favourite_controller,node_search_controller,node_recommendation_controller,node_featured_controller toneMint
class node_account_controller,node_profile_controller,node_user_controller toneRose
class node_admin_controller,node_report_controller,node_email toneIndigo
```

## Components

### API and access

- [Express server](https://github.com/beatfly-music/server/blob/main/server.js): `server.js`
- [Authentication](https://github.com/beatfly-music/server/blob/main/middleware/auth.js): `middleware/auth.js`
- [Account routes](https://github.com/beatfly-music/server/blob/main/routes/accountRoutes.js): `routes/accountRoutes.js`
- [Album routes](https://github.com/beatfly-music/server/blob/main/routes/albumRoutes.js): `routes/albumRoutes.js`
- [Track routes](https://github.com/beatfly-music/server/blob/main/routes/trackRoutes.js): `routes/trackRoutes.js`
- [Stream routes](https://github.com/beatfly-music/server/blob/main/routes/streamRoutes.js): `routes/streamRoutes.js`

### Music catalog

- [Album management](https://github.com/beatfly-music/server/blob/main/controllers/albumController.js): `controllers/albumController.js`
- [Track management](https://github.com/beatfly-music/server/blob/main/controllers/trackController.js): `controllers/trackController.js`
- [Audio compression](https://github.com/beatfly-music/server/blob/main/utils/compressAudio.js): `utils/compressAudio.js`
- [Image optimization](https://github.com/beatfly-music/server/blob/main/routes/imageRoutes.js): `routes/imageRoutes.js`
- **Music uploads**

### Listening features

- [Track streaming](https://github.com/beatfly-music/server/blob/main/controllers/streamController.js): `controllers/streamController.js`
- [Playlists](https://github.com/beatfly-music/server/blob/main/controllers/playlistController.js): `controllers/playlistController.js`
- [Favourites](https://github.com/beatfly-music/server/blob/main/controllers/favouriteController.js): `controllers/favouriteController.js`
- [Search](https://github.com/beatfly-music/server/blob/main/controllers/searchController.js): `controllers/searchController.js`
- [Recommendations](https://github.com/beatfly-music/server/blob/main/controllers/recommendationController.js): `controllers/recommendationController.js`
- [Featured content](https://github.com/beatfly-music/server/blob/main/controllers/featuredController.js): `controllers/featuredController.js`

### Accounts and profiles

- [Account services](https://github.com/beatfly-music/server/blob/main/controllers/accountController.js): `controllers/accountController.js`
- [Profiles](https://github.com/beatfly-music/server/blob/main/controllers/profileController.js): `controllers/profileController.js`
- [User preferences](https://github.com/beatfly-music/server/blob/main/controllers/userController.js): `controllers/userController.js`

### Administration

- [Administration](https://github.com/beatfly-music/server/blob/main/controllers/adminController.js): `controllers/adminController.js`
- [Artist reports](https://github.com/beatfly-music/server/blob/main/controllers/reportController.js): `controllers/reportController.js`

### Other components

- **API client**
- **SMTP email**
- [MySQL database](https://github.com/beatfly-music/server/blob/main/schema.sql): `schema.sql`
- [Database client](https://github.com/beatfly-music/server/blob/main/utils/db.js): `utils/db.js`

## Connections

- API client → Express server: sends requests
- Express server → Account routes: mounts routes
- Express server → Album routes: mounts routes
- Express server → Track routes: mounts routes
- Express server → Stream routes: mounts routes
- Express server → Image optimization: mounts routes
- Album routes → Authentication: authenticates
- Album routes → Album management: dispatches
- Track routes → Authentication: authenticates
- Track routes → Track management: dispatches
- Stream routes → Track streaming: dispatches
- Account routes → Account services: dispatches
- Album management → Audio compression: compresses audio
- Album management → Music uploads: stores uploads
- Album management → Database client: queries
- Track management → Database client: queries
- Track streaming → Database client: queries
- Account services → Database client: queries
- Account services → SMTP email: sends reset mail
- Image optimization → Music uploads: reads images
- Express server → Playlists: mounts routes
- Express server → Favourites: mounts routes
- Express server → Search: mounts routes
- Express server → Recommendations: mounts routes
- Express server → Featured content: mounts routes
- Express server → Profiles: mounts routes
- Express server → User preferences: mounts routes
- Express server → Administration: mounts routes
- Express server → Artist reports: mounts routes
- Database client → MySQL database: queries