# fazalpm/spotiai architecture

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

- Interactive diagram: https://gitdiagram.com/fazalpm/spotiai
- Repository: https://github.com/fazalpm/spotiai

## Overview

SpotiAI is a proposal for turning Spotify listening history into conversational reflection and learning, not an implemented application: the tree contains only product documents. The documented journey is a user chatting through a UI, with a proposed backend using Spotify data and OpenAI to produce personalized answers and episode summaries. Additional planned capabilities include mood tracking, podcast knowledge graphs, sharing, session sync, recommendations, assistant mode, and proactive reports. Paths point to documents describing these concepts, not source implementations; relationships are limited to those stated in the README.

Main entry points: [`README.md`](https://github.com/fazalpm/spotiai/blob/main/README.md) (Listening History)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_chat["Chat UI<br/>[README.md]"]
  node_oauth["Spotify OAuth<br/>[README.md]"]
  node_backend["Backend<br/>[README.md]"]
end

subgraph group_data["Listening Data"]
  node_spotify["Spotify API"]
  node_history[("Listening History<br/>[README.md]")]
  node_securedata["Secure Data Layer<br/>[README.md]"]
end

subgraph group_intelligence["AI Insights"]
  node_responses["Response Engine<br/>[README.md]"]
  node_openai["OpenAI API"]
  node_insights["Listening Insights<br/>[README.md]"]
  node_summaries["Podcast Micro-summaries<br/>[README.md]"]
  node_moods["Mood Tracking<br/>[README.md]"]
  node_knowledge["Podcast Knowledge Graphs<br/>[README.md]"]
end

subgraph group_engagement["Extended Engagement"]
  node_sharing["Sharable Stats<br/>[README.md]"]
  node_sync["Session Sync<br/>[README.md]"]
  node_recommendations["Predictive Recommendations<br/>[README.md]"]
  node_assistant["AI Assistant<br/>[README.md]"]
  node_reports["Weekly AI Reports<br/>[README.md]"]
end

node_listener(("Listener"))

node_listener -->|"asks questions"| node_chat
node_listener -->|"logs in"| node_oauth
node_chat -->|"sends chat"| node_backend
node_backend -->|"integrates with"| node_spotify
node_backend -->|"integrates with"| node_openai
node_backend -->|"handles history"| node_securedata
node_securedata -->|"stores securely"| node_history
node_responses -->|"returns answers"| node_chat
node_history -->|"informs"| node_insights
node_history -->|"qualifies episodes"| node_summaries
node_history -.->|"supports tracking"| node_moods
node_history -.->|"supports graphs"| node_knowledge
node_insights -.->|"enables sharing"| node_sharing
node_history -.->|"supports sync"| node_sync
node_history -.->|"informs"| node_recommendations
node_assistant -.->|"offers assistance"| node_listener
node_reports -.->|"delivers reports"| node_listener

click node_chat "https://github.com/fazalpm/spotiai/blob/main/README.md"
click node_oauth "https://github.com/fazalpm/spotiai/blob/main/README.md"
click node_backend "https://github.com/fazalpm/spotiai/blob/main/README.md"
click node_history "https://github.com/fazalpm/spotiai/blob/main/README.md"
click node_securedata "https://github.com/fazalpm/spotiai/blob/main/README.md"
click node_responses "https://github.com/fazalpm/spotiai/blob/main/README.md"
click node_insights "https://github.com/fazalpm/spotiai/blob/main/README.md"
click node_summaries "https://github.com/fazalpm/spotiai/blob/main/README.md"
click node_moods "https://github.com/fazalpm/spotiai/blob/main/README.md"
click node_knowledge "https://github.com/fazalpm/spotiai/blob/main/README.md"
click node_sharing "https://github.com/fazalpm/spotiai/blob/main/README.md"
click node_sync "https://github.com/fazalpm/spotiai/blob/main/README.md"
click node_recommendations "https://github.com/fazalpm/spotiai/blob/main/README.md"
click node_assistant "https://github.com/fazalpm/spotiai/blob/main/README.md"
click node_reports "https://github.com/fazalpm/spotiai/blob/main/README.md"

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_chat,node_oauth,node_backend toneBlue
class node_spotify,node_history,node_securedata toneAmber
class node_responses,node_openai,node_insights,node_summaries,node_moods,node_knowledge toneMint
class node_sharing,node_sync,node_recommendations,node_assistant,node_reports toneRose
class node_listener toneIndigo
```

## Components

### User Experience

- [Chat UI](https://github.com/fazalpm/spotiai/blob/main/README.md): `README.md`
- [Spotify OAuth](https://github.com/fazalpm/spotiai/blob/main/README.md): `README.md`
- [Backend](https://github.com/fazalpm/spotiai/blob/main/README.md): `README.md`

### Listening Data

- **Spotify API**
- [Listening History](https://github.com/fazalpm/spotiai/blob/main/README.md): `README.md`
- [Secure Data Layer](https://github.com/fazalpm/spotiai/blob/main/README.md): `README.md`

### AI Insights

- [Response Engine](https://github.com/fazalpm/spotiai/blob/main/README.md): `README.md`
- **OpenAI API**
- [Listening Insights](https://github.com/fazalpm/spotiai/blob/main/README.md): `README.md`
- [Podcast Micro-summaries](https://github.com/fazalpm/spotiai/blob/main/README.md): `README.md`
- [Mood Tracking](https://github.com/fazalpm/spotiai/blob/main/README.md): `README.md`
- [Podcast Knowledge Graphs](https://github.com/fazalpm/spotiai/blob/main/README.md): `README.md`

### Extended Engagement

- [Sharable Stats](https://github.com/fazalpm/spotiai/blob/main/README.md): `README.md`
- [Session Sync](https://github.com/fazalpm/spotiai/blob/main/README.md): `README.md`
- [Predictive Recommendations](https://github.com/fazalpm/spotiai/blob/main/README.md): `README.md`
- [AI Assistant](https://github.com/fazalpm/spotiai/blob/main/README.md): `README.md`
- [Weekly AI Reports](https://github.com/fazalpm/spotiai/blob/main/README.md): `README.md`

### Other components

- **Listener**

## Connections

- Listener → Chat UI: asks questions (evidence: `README.md`)
- Listener → Spotify OAuth: logs in (evidence: `README.md`)
- Chat UI → Backend: sends chat (evidence: `README.md`)
- Backend → Spotify API: integrates with (evidence: `README.md`)
- Backend → OpenAI API: integrates with (evidence: `README.md`)
- Backend → Secure Data Layer: handles history (evidence: `README.md`)
- Secure Data Layer → Listening History: stores securely (evidence: `README.md`)
- Response Engine → Chat UI: returns answers (evidence: `README.md`)
- Listening History → Listening Insights: informs (evidence: `README.md`)
- Listening History → Podcast Micro-summaries: qualifies episodes (evidence: `README.md`)
- Listening History → Mood Tracking: supports tracking (evidence: `README.md`)
- Listening History → Podcast Knowledge Graphs: supports graphs (evidence: `README.md`)
- Listening Insights → Sharable Stats: enables sharing (evidence: `README.md`)
- Listening History → Session Sync: supports sync (evidence: `README.md`)
- Listening History → Predictive Recommendations: informs (evidence: `README.md`)
- AI Assistant → Listener: offers assistance (evidence: `README.md`)
- Weekly AI Reports → Listener: delivers reports (evidence: `README.md`)
