# xiao-yan19/sound_sphere_v1 architecture

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

- Interactive diagram: https://gitdiagram.com/xiao-yan19/sound_sphere_v1
- Repository: https://github.com/xiao-yan19/sound_sphere_v1

## Overview

SoundSphere is described as a music social-streaming application; the available implementation evidence is its Express backend, not the Flutter application code. The principal API workflow is a client request routed through the API to authentication, profile/activity, or music handlers, which use domain models or the Jamendo integration. Registration/login and token refresh, profile management, activity retrieval, and music search/trending/track lookup are distinct capabilities. Backend routing and service calls are evidenced; the client-to-API relationship is shown as unverified because no client source is provided.

Main entry points: [`backend/src/controllers/auth.controller.js`](https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/controllers/auth.controller.js) (Auth handlers), [`backend/src/controllers/user.controller.js`](https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/controllers/user.controller.js) (Profile and activity), [`backend/src/app.js`](https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/app.js) (HTTP API), [`backend/src/routes/auth.routes.js`](https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/routes/auth.routes.js) (Auth routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API runtime"]
  node_server["API startup<br/>[server.js]"]
  node_app["HTTP API<br/>[app.js]"]
  node_auth_routes["Auth routes<br/>[auth.routes.js]"]
  node_user_routes["User routes<br/>[user.routes.js]"]
  node_music_routes["Music routes<br/>[music.routes.js]"]
end

subgraph group_identity["Identity and profiles"]
  node_auth_mw["Auth middleware<br/>[auth.middleware.js]"]
  node_auth_ctrl["Auth handlers<br/>[auth.controller.js]"]
  node_user_ctrl["Profile and activity<br/>[user.controller.js]"]
  node_jwt["Token utilities<br/>[jwt.js]"]
  node_validators["Input validation<br/>[validators.js]"]
end

subgraph group_music["Music discovery"]
  node_music_ctrl["Music handlers"]
  node_jamendo["Jamendo service<br/>[jamendo.service.js]"]
end

subgraph group_persistence["Persistence"]
  node_user_model["User records<br/>[user.model.js]"]
  node_session_model["Sessions<br/>[session.model.js]"]
  node_activity_model["Activity records<br/>[activity.model.js]"]
  node_db_config["Database connection<br/>[database.js]"]
end

node_client(("App client"))
node_jamendo_api{{"Jamendo API"}}

node_client -.->|"sends requests"| node_app
node_server -->|"starts"| node_app
node_server -->|"connects database"| node_db_config
node_app -->|"mounts routes"| node_auth_routes
node_app -->|"mounts routes"| node_user_routes
node_app -->|"mounts routes"| node_music_routes
node_auth_routes -->|"dispatches to"| node_auth_ctrl
node_auth_routes -->|"protects endpoint"| node_auth_mw
node_user_routes -->|"dispatches to"| node_user_ctrl
node_user_routes -->|"protects endpoints"| node_auth_mw
node_music_routes -->|"dispatches to"| node_music_ctrl
node_auth_ctrl -->|"reads and writes"| node_user_model
node_auth_ctrl -->|"manages sessions"| node_session_model
node_auth_ctrl -->|"creates tokens"| node_jwt
node_auth_ctrl -->|"validates input"| node_validators
node_auth_mw -->|"verifies tokens"| node_jwt
node_user_ctrl -->|"reads and updates"| node_user_model
node_user_ctrl -->|"deletes sessions"| node_session_model
node_user_ctrl -->|"reads and deletes"| node_activity_model
node_user_ctrl -->|"validates input"| node_validators
node_music_ctrl -->|"requests tracks"| node_jamendo
node_jamendo -->|"fetches track data"| node_jamendo_api

click node_server "https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/server.js"
click node_app "https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/app.js"
click node_auth_routes "https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/routes/auth.routes.js"
click node_user_routes "https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/routes/user.routes.js"
click node_music_routes "https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/routes/music.routes.js"
click node_auth_mw "https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/middleware/auth.middleware.js"
click node_auth_ctrl "https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/controllers/auth.controller.js"
click node_user_ctrl "https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/controllers/user.controller.js"
click node_jwt "https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/utils/jwt.js"
click node_validators "https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/utils/validators.js"
click node_user_model "https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/models/user.model.js"
click node_session_model "https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/models/session.model.js"
click node_activity_model "https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/models/activity.model.js"
click node_db_config "https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/config/database.js"
click node_music_ctrl "https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/controllers/music.controller.js"
click node_jamendo "https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/services/jamendo.service.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_app,node_auth_routes,node_user_routes,node_music_routes,node_client toneBlue
class node_auth_mw,node_auth_ctrl,node_user_ctrl,node_jwt,node_validators toneAmber
class node_music_ctrl,node_jamendo,node_jamendo_api toneMint
class node_user_model,node_session_model,node_activity_model,node_db_config toneRose
```

## Components

### API runtime

- [API startup](https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/server.js): `backend/src/server.js`
- [HTTP API](https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/app.js): `backend/src/app.js`
- [Auth routes](https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/routes/auth.routes.js): `backend/src/routes/auth.routes.js`
- [User routes](https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/routes/user.routes.js): `backend/src/routes/user.routes.js`
- [Music routes](https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/routes/music.routes.js): `backend/src/routes/music.routes.js`

### Identity and profiles

- [Auth middleware](https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/middleware/auth.middleware.js): `backend/src/middleware/auth.middleware.js`
- [Auth handlers](https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/controllers/auth.controller.js): `backend/src/controllers/auth.controller.js`
- [Profile and activity](https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/controllers/user.controller.js): `backend/src/controllers/user.controller.js`
- [Token utilities](https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/utils/jwt.js): `backend/src/utils/jwt.js`
- [Input validation](https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/utils/validators.js): `backend/src/utils/validators.js`

### Music discovery

- [Music handlers](https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/controllers/music.controller.js): `backend/src/controllers/music.controller.js`
- [Jamendo service](https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/services/jamendo.service.js): `backend/src/services/jamendo.service.js`

### Persistence

- [User records](https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/models/user.model.js): `backend/src/models/user.model.js`
- [Sessions](https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/models/session.model.js): `backend/src/models/session.model.js`
- [Activity records](https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/models/activity.model.js): `backend/src/models/activity.model.js`
- [Database connection](https://github.com/xiao-yan19/sound_sphere_v1/blob/master/backend/src/config/database.js): `backend/src/config/database.js`

### Other components

- **App client**
- **Jamendo API**

## Connections

- App client → HTTP API: sends requests
- API startup → HTTP API: starts (evidence: `backend/src/server.js`)
- API startup → Database connection: connects database (evidence: `backend/src/server.js`)
- HTTP API → Auth routes: mounts routes (evidence: `backend/src/app.js`)
- HTTP API → User routes: mounts routes (evidence: `backend/src/app.js`)
- HTTP API → Music routes: mounts routes (evidence: `backend/src/app.js`)
- Auth routes → Auth handlers: dispatches to (evidence: `backend/src/routes/auth.routes.js`)
- Auth routes → Auth middleware: protects endpoint (evidence: `backend/src/routes/auth.routes.js`)
- User routes → Profile and activity: dispatches to (evidence: `backend/src/routes/user.routes.js`)
- User routes → Auth middleware: protects endpoints (evidence: `backend/src/routes/user.routes.js`)
- Music routes → Music handlers: dispatches to (evidence: `backend/src/routes/music.routes.js`)
- Auth handlers → User records: reads and writes (evidence: `backend/src/controllers/auth.controller.js`)
- Auth handlers → Sessions: manages sessions (evidence: `backend/src/controllers/auth.controller.js`)
- Auth handlers → Token utilities: creates tokens (evidence: `backend/src/controllers/auth.controller.js`)
- Auth handlers → Input validation: validates input (evidence: `backend/src/controllers/auth.controller.js`)
- Auth middleware → Token utilities: verifies tokens (evidence: `backend/src/middleware/auth.middleware.js`)
- Profile and activity → User records: reads and updates (evidence: `backend/src/controllers/user.controller.js`)
- Profile and activity → Sessions: deletes sessions (evidence: `backend/src/controllers/user.controller.js`)
- Profile and activity → Activity records: reads and deletes (evidence: `backend/src/controllers/user.controller.js`)
- Profile and activity → Input validation: validates input (evidence: `backend/src/controllers/user.controller.js`)
- Music handlers → Jamendo service: requests tracks (evidence: `backend/src/controllers/music.controller.js`)
- Jamendo service → Jamendo API: fetches track data (evidence: `backend/src/services/jamendo.service.js`)