# folty7/lyra architecture

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

- Interactive diagram: https://gitdiagram.com/folty7/lyra
- Repository: https://github.com/folty7/lyra

## Overview

Lyra turns a Spotify library into user-curated playlists: users authenticate, load library and listening data, ask Gemini to group tracks by selected criteria, review and save suggestions, then create playlists in Spotify. The map includes the dashboard’s analytics and settings as supporting capabilities. API routes and several screens were not sampled; their paths and responsibilities are supported by the tree and README, so uncertain internal wiring is omitted.

Main entry points: [`fe/src/layouts/DashboardLayout.jsx`](https://github.com/folty7/lyra/blob/main/fe/src/layouts/DashboardLayout.jsx) (Dashboard shell), [`fe/src/api/axios.js`](https://github.com/folty7/lyra/blob/main/fe/src/api/axios.js) (API client), [`be/server.js`](https://github.com/folty7/lyra/blob/main/be/server.js) (Express server), [`fe/src/store/useTracksStore.js`](https://github.com/folty7/lyra/blob/main/fe/src/store/useTracksStore.js) (Library cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend experience"]
  node_app["App routes<br/>[App.jsx]"]
  node_dashboard["Dashboard shell"]
  node_overview["Library overview<br/>[Overview.jsx]"]
  node_library["Library browser<br/>[Library.jsx]"]
  node_sort["AI sort<br/>[Sort.jsx]"]
  node_settings["Settings<br/>[Settings.jsx]"]
  node_tracks_store[("Library cache<br/>[useTracksStore.js]")]
  node_playlist_store[("Saved suggestions<br/>[useStore.js]")]
  node_api_client["API client<br/>[axios.js]"]
end

subgraph group_backend["Backend API"]
  node_server["Express server<br/>[server.js]"]
  node_auth["Session auth<br/>[auth.js]"]
  node_api_routes["API endpoints<br/>[api.js]"]
end

subgraph group_services["Domain services"]
  node_spotify_service["Spotify operations<br/>[spotifyService.js]"]
  node_gemini_service["AI grouping<br/>[geminiService.js]"]
end

subgraph group_integrations["External services"]
  node_spotify["Spotify API"]
  node_gemini["Google Gemini"]
end

node_user(("Spotify user"))

node_user -->|"navigates"| node_app
node_app -->|"routes dashboard"| node_dashboard
node_dashboard -->|"renders"| node_overview
node_dashboard -->|"routes library"| node_library
node_dashboard -->|"routes sorting"| node_sort
node_dashboard -->|"routes settings"| node_settings
node_dashboard -->|"loads profile"| node_api_client
node_dashboard -->|"loads library"| node_tracks_store
node_overview -->|"reads analytics"| node_tracks_store
node_overview -->|"reads saved playlists"| node_playlist_store
node_library -->|"reads tracks"| node_tracks_store
node_sort -->|"uses tracks"| node_tracks_store
node_sort -->|"requests grouping"| node_api_client
node_sort -->|"saves suggestions"| node_playlist_store
node_playlist_store -->|"submits playlists"| node_api_client
node_settings -->|"uses API key"| node_api_client
node_tracks_store -->|"fetches library and top data"| node_api_client
node_api_client -->|"sends API requests"| node_server
node_server -->|"applies auth"| node_auth
node_server -->|"dispatches API"| node_api_routes
node_auth -->|"refreshes tokens"| node_spotify
node_api_routes -->|"requests track and playlist operations"| node_spotify_service
node_api_routes -->|"requests track grouping"| node_gemini_service
node_spotify_service -->|"reads tracks and creates playlists"| node_spotify
node_gemini_service -->|"generates groups"| node_gemini
node_user -->|"starts OAuth"| node_server
node_server -->|"authorizes and exchanges code"| node_spotify

click node_app "https://github.com/folty7/lyra/blob/main/fe/src/App.jsx"
click node_dashboard "https://github.com/folty7/lyra/blob/main/fe/src/layouts/DashboardLayout.jsx"
click node_overview "https://github.com/folty7/lyra/blob/main/fe/src/pages/dashboard/Overview.jsx"
click node_library "https://github.com/folty7/lyra/blob/main/fe/src/pages/dashboard/Library.jsx"
click node_sort "https://github.com/folty7/lyra/blob/main/fe/src/pages/dashboard/Sort.jsx"
click node_settings "https://github.com/folty7/lyra/blob/main/fe/src/pages/dashboard/Settings.jsx"
click node_tracks_store "https://github.com/folty7/lyra/blob/main/fe/src/store/useTracksStore.js"
click node_playlist_store "https://github.com/folty7/lyra/blob/main/fe/src/store/useStore.js"
click node_api_client "https://github.com/folty7/lyra/blob/main/fe/src/api/axios.js"
click node_server "https://github.com/folty7/lyra/blob/main/be/server.js"
click node_auth "https://github.com/folty7/lyra/blob/main/be/middleware/auth.js"
click node_api_routes "https://github.com/folty7/lyra/blob/main/be/routes/api.js"
click node_spotify_service "https://github.com/folty7/lyra/blob/main/be/services/spotifyService.js"
click node_gemini_service "https://github.com/folty7/lyra/blob/main/be/services/geminiService.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_app,node_dashboard,node_overview,node_library,node_sort,node_settings,node_tracks_store,node_playlist_store,node_api_client,node_user toneBlue
class node_server,node_auth,node_api_routes toneAmber
class node_spotify_service,node_gemini_service toneMint
class node_spotify,node_gemini toneRose
```

## Components

### Frontend experience

- [App routes](https://github.com/folty7/lyra/blob/main/fe/src/App.jsx): `fe/src/App.jsx`
- [Dashboard shell](https://github.com/folty7/lyra/blob/main/fe/src/layouts/DashboardLayout.jsx): `fe/src/layouts/DashboardLayout.jsx`
- [Library overview](https://github.com/folty7/lyra/blob/main/fe/src/pages/dashboard/Overview.jsx): `fe/src/pages/dashboard/Overview.jsx`
- [Library browser](https://github.com/folty7/lyra/blob/main/fe/src/pages/dashboard/Library.jsx): `fe/src/pages/dashboard/Library.jsx`
- [AI sort](https://github.com/folty7/lyra/blob/main/fe/src/pages/dashboard/Sort.jsx): `fe/src/pages/dashboard/Sort.jsx`
- [Settings](https://github.com/folty7/lyra/blob/main/fe/src/pages/dashboard/Settings.jsx): `fe/src/pages/dashboard/Settings.jsx`
- [Library cache](https://github.com/folty7/lyra/blob/main/fe/src/store/useTracksStore.js): `fe/src/store/useTracksStore.js`
- [Saved suggestions](https://github.com/folty7/lyra/blob/main/fe/src/store/useStore.js): `fe/src/store/useStore.js`
- [API client](https://github.com/folty7/lyra/blob/main/fe/src/api/axios.js): `fe/src/api/axios.js`

### Backend API

- [Express server](https://github.com/folty7/lyra/blob/main/be/server.js): `be/server.js`
- [Session auth](https://github.com/folty7/lyra/blob/main/be/middleware/auth.js): `be/middleware/auth.js`
- [API endpoints](https://github.com/folty7/lyra/blob/main/be/routes/api.js): `be/routes/api.js`

### Domain services

- [Spotify operations](https://github.com/folty7/lyra/blob/main/be/services/spotifyService.js): `be/services/spotifyService.js`
- [AI grouping](https://github.com/folty7/lyra/blob/main/be/services/geminiService.js): `be/services/geminiService.js`

### External services

- **Spotify API**
- **Google Gemini**

### Other components

- **Spotify user**

## Connections

- Spotify user → App routes: navigates
- App routes → Dashboard shell: routes dashboard
- Dashboard shell → Library overview: renders
- Dashboard shell → Library browser: routes library
- Dashboard shell → AI sort: routes sorting
- Dashboard shell → Settings: routes settings
- Dashboard shell → API client: loads profile
- Dashboard shell → Library cache: loads library
- Library overview → Library cache: reads analytics
- Library overview → Saved suggestions: reads saved playlists
- Library browser → Library cache: reads tracks
- AI sort → Library cache: uses tracks
- AI sort → API client: requests grouping
- AI sort → Saved suggestions: saves suggestions
- Saved suggestions → API client: submits playlists
- Settings → API client: uses API key
- Library cache → API client: fetches library and top data
- API client → Express server: sends API requests
- Express server → Session auth: applies auth
- Express server → API endpoints: dispatches API
- Session auth → Spotify API: refreshes tokens
- API endpoints → Spotify operations: requests track and playlist operations
- API endpoints → AI grouping: requests track grouping
- Spotify operations → Spotify API: reads tracks and creates playlists
- AI grouping → Google Gemini: generates groups
- Spotify user → Express server: starts OAuth
- Express server → Spotify API: authorizes and exchanges code