# ahmedsheikh27/ai-mood-music architecture

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

- Interactive diagram: https://gitdiagram.com/ahmedsheikh27/ai-mood-music
- Repository: https://github.com/ahmedsheikh27/ai-mood-music

## Overview

Mood Music is a web app where a user connects Spotify, starts an AI chat, shares a mood, and receives a playlist suggestion. The frontend handles OAuth token handoff and chat; FastAPI routes coordinate authentication and agent requests, while the agent can search Spotify through a tool. The README also identifies Spotify recommendations and the modern web UI as core capabilities. Edges follow sampled calls and documented capabilities; unsampled internals are not expanded.

Main entry points: [`ai-mood-music-backend/app/api/routes.py`](https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-backend/app/api/routes.py) (Chat and auth routes), [`ai-mood-music-frontend/app/chat/page.tsx`](https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-frontend/app/chat/page.tsx) (Mood chat), [`ai-mood-music-backend/app/auth/spotify_oauth.py`](https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-backend/app/auth/spotify_oauth.py) (Spotify OAuth), [`ai-mood-music-backend/app/agents/chat_agent.py`](https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-backend/app/agents/chat_agent.py) (Chat agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web experience"]
  node_home["Connect screen<br/>[page.tsx]"]
  node_chatui["Mood chat<br/>[page.tsx]"]
  node_chatmessage["Chat message view<br/>[chat-message.tsx]"]
  node_apihelper["HTTP client<br/>[api.ts]"]
end

subgraph group_api["Backend API"]
  node_server["FastAPI app<br/>[main.py]"]
  node_routes["Chat and auth routes<br/>[routes.py]"]
  node_request["Mood request schema<br/>[request_models.py]"]
  node_oauth["Spotify OAuth<br/>[spotify_oauth.py]"]
  node_config["Credentials config<br/>[config.py]"]
end

subgraph group_recommendation["Recommendation"]
  node_agents["Chat agent<br/>[chat_agent.py]"]
  node_moodagent["Mood agent module<br/>[mood_agent.py]"]
  node_spotifyclient["Playlist search client<br/>[spotify_client.py]"]
end

subgraph group_integrations["External services"]
  node_spotify(("Spotify"))
  node_llm(("Gemini model service"))
end

node_user(("Music seeker"))

node_user -->|"connects Spotify"| node_home
node_home -->|"opens login"| node_routes
node_routes -->|"gets auth URL"| node_oauth
node_oauth -->|"reads settings"| node_config
node_oauth -->|"requests authorization"| node_spotify
node_routes -->|"exchanges code"| node_oauth
node_routes -->|"redirects token"| node_chatui
node_user -->|"shares mood"| node_chatui
node_chatui -->|"sends chat requests"| node_apihelper
node_apihelper -.->|"calls chat endpoints"| node_routes
node_server -->|"registers routes"| node_routes
node_routes -->|"validates mood"| node_request
node_routes -->|"starts and queries"| node_agents
node_agents -->|"runs model"| node_llm
node_agents -->|"invokes search tool"| node_spotifyclient
node_spotifyclient -->|"searches playlists"| node_spotify
node_chatui -->|"renders messages"| node_chatmessage
node_chatui -->|"shows playlist result"| node_user
node_moodagent -.->|"possible mood handling"| node_agents

click node_home "https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-frontend/app/page.tsx"
click node_chatui "https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-frontend/app/chat/page.tsx"
click node_chatmessage "https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-frontend/components/chat-message.tsx"
click node_apihelper "https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-frontend/lib/api.ts"
click node_server "https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-backend/app/main.py"
click node_routes "https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-backend/app/api/routes.py"
click node_request "https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-backend/app/models/request_models.py"
click node_oauth "https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-backend/app/auth/spotify_oauth.py"
click node_config "https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-backend/app/config.py"
click node_agents "https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-backend/app/agents/chat_agent.py"
click node_moodagent "https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-backend/app/agents/mood_agent.py"
click node_spotifyclient "https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-backend/app/services/spotify_client.py"

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_home,node_chatui,node_chatmessage,node_apihelper toneBlue
class node_server,node_routes,node_request,node_oauth,node_config toneAmber
class node_agents,node_moodagent,node_spotifyclient toneMint
class node_spotify,node_llm toneRose
class node_user toneIndigo
```

## Components

### Web experience

- [Connect screen](https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-frontend/app/page.tsx): `ai-mood-music-frontend/app/page.tsx`
- [Mood chat](https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-frontend/app/chat/page.tsx): `ai-mood-music-frontend/app/chat/page.tsx`
- [Chat message view](https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-frontend/components/chat-message.tsx): `ai-mood-music-frontend/components/chat-message.tsx`
- [HTTP client](https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-frontend/lib/api.ts): `ai-mood-music-frontend/lib/api.ts`

### Backend API

- [FastAPI app](https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-backend/app/main.py): `ai-mood-music-backend/app/main.py`
- [Chat and auth routes](https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-backend/app/api/routes.py): `ai-mood-music-backend/app/api/routes.py`
- [Mood request schema](https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-backend/app/models/request_models.py): `ai-mood-music-backend/app/models/request_models.py`
- [Spotify OAuth](https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-backend/app/auth/spotify_oauth.py): `ai-mood-music-backend/app/auth/spotify_oauth.py`
- [Credentials config](https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-backend/app/config.py): `ai-mood-music-backend/app/config.py`

### Recommendation

- [Chat agent](https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-backend/app/agents/chat_agent.py): `ai-mood-music-backend/app/agents/chat_agent.py`
- [Mood agent module](https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-backend/app/agents/mood_agent.py): `ai-mood-music-backend/app/agents/mood_agent.py`
- [Playlist search client](https://github.com/ahmedsheikh27/ai-mood-music/blob/main/ai-mood-music-backend/app/services/spotify_client.py): `ai-mood-music-backend/app/services/spotify_client.py`

### External services

- **Spotify**
- **Gemini model service**

### Other components

- **Music seeker**

## Connections

- Music seeker → Connect screen: connects Spotify (evidence: `ai-mood-music-frontend/app/page.tsx`)
- Connect screen → Chat and auth routes: opens login (evidence: `ai-mood-music-frontend/app/page.tsx`)
- Chat and auth routes → Spotify OAuth: gets auth URL (evidence: `ai-mood-music-backend/app/api/routes.py`)
- Spotify OAuth → Credentials config: reads settings (evidence: `ai-mood-music-backend/app/auth/spotify_oauth.py`)
- Spotify OAuth → Spotify: requests authorization (evidence: `ai-mood-music-backend/app/auth/spotify_oauth.py`)
- Chat and auth routes → Spotify OAuth: exchanges code (evidence: `ai-mood-music-backend/app/api/routes.py`)
- Chat and auth routes → Mood chat: redirects token (evidence: `ai-mood-music-backend/app/api/routes.py`)
- Music seeker → Mood chat: shares mood (evidence: `ai-mood-music-frontend/app/chat/page.tsx`)
- Mood chat → HTTP client: sends chat requests (evidence: `ai-mood-music-frontend/app/chat/page.tsx`)
- HTTP client → Chat and auth routes: calls chat endpoints
- FastAPI app → Chat and auth routes: registers routes (evidence: `ai-mood-music-backend/app/main.py`)
- Chat and auth routes → Mood request schema: validates mood (evidence: `ai-mood-music-backend/app/api/routes.py`)
- Chat and auth routes → Chat agent: starts and queries (evidence: `ai-mood-music-backend/app/api/routes.py`)
- Chat agent → Gemini model service: runs model (evidence: `ai-mood-music-backend/app/agents/chat_agent.py`)
- Chat agent → Playlist search client: invokes search tool (evidence: `ai-mood-music-backend/app/agents/chat_agent.py`)
- Playlist search client → Spotify: searches playlists (evidence: `ai-mood-music-backend/app/services/spotify_client.py`)
- Mood chat → Chat message view: renders messages (evidence: `ai-mood-music-frontend/app/chat/page.tsx`)
- Mood chat → Music seeker: shows playlist result (evidence: `ai-mood-music-frontend/app/chat/page.tsx`)
- Mood agent module → Chat agent: possible mood handling
