# 05786k/moodify_applied-ai-system architecture

> Architecture diagram of the GitHub repository 05786k/moodify_applied-ai-system, 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/05786k/moodify_applied-ai-system
- Repository: https://github.com/05786k/moodify_applied-ai-system
- Video tour (about a minute): https://gitdiagram.com/05786k/moodify_applied-ai-system/video

## Overview

Moodify takes a listener’s taste profile through semantic retrieval, weighted ranking, and a grounded explanation, then presents recommendations in a Streamlit UI or CLI. The glossary extends retrieval for unfamiliar genre and mood terms; retrieval failures fall back to scoring the full catalog, and explanation failures use a rule-based summary. The sampled sources show the shared pipeline and front-end calls; unsampled code is represented only where the README documents its capability.

Main entry points: [`app.py`](https://github.com/05786k/moodify_applied-ai-system/blob/main/app.py) (Streamlit UI), [`src/retriever.py`](https://github.com/05786k/moodify_applied-ai-system/blob/main/src/retriever.py) (Semantic retrieval), [`src/main.py`](https://github.com/05786k/moodify_applied-ai-system/blob/main/src/main.py) (CLI), [`src/explainer.py`](https://github.com/05786k/moodify_applied-ai-system/blob/main/src/explainer.py) (Explanation generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_streamlit["Streamlit UI<br/>[app.py]"]
  node_cli["CLI<br/>[main.py]"]
end

subgraph group_recommendation["Recommendation pipeline"]
  node_pipeline["Shared pipeline<br/>[pipeline.py]"]
  node_retrieval["Semantic retrieval<br/>[retriever.py]"]
  node_embeddings["Song embeddings<br/>[retriever.py]"]
  node_scorer["Weighted scorer<br/>[recommender.py]"]
end

subgraph group_knowledge["Music knowledge"]
  node_catalog[("Song catalog<br/>[songs.csv]")]
  node_glossary["Genre/mood glossary<br/>[glossary.py]"]
end

subgraph group_generation["Explanation generation"]
  node_explainer["Explanation generator<br/>[explainer.py]"]
end

node_listener(("Listener"))
node_claude{{"Anthropic Claude"}}

node_listener -->|"enters preferences"| node_streamlit
node_listener -->|"selects profile"| node_cli
node_streamlit -->|"requests recommendations"| node_pipeline
node_cli -->|"requests recommendations"| node_pipeline
node_streamlit -->|"loads songs"| node_catalog
node_cli -->|"loads songs"| node_catalog
node_streamlit -->|"embeds songs"| node_embeddings
node_cli -->|"embeds songs"| node_embeddings
node_streamlit -->|"shows retrieval details"| node_retrieval
node_streamlit -->|"computes baseline"| node_scorer
node_pipeline -->|"retrieves and ranks"| node_retrieval
node_pipeline -->|"explains results"| node_explainer
node_retrieval -->|"compares vectors"| node_embeddings
node_retrieval -->|"enriches query"| node_glossary
node_retrieval -->|"scores shortlist"| node_scorer
node_retrieval -->|"retrieves candidates"| node_catalog
node_explainer -->|"generates explanation"| node_claude
node_explainer -->|"returns explanation"| node_streamlit
node_explainer -->|"returns explanation"| node_cli

click node_streamlit "https://github.com/05786k/moodify_applied-ai-system/blob/main/app.py"
click node_cli "https://github.com/05786k/moodify_applied-ai-system/blob/main/src/main.py"
click node_pipeline "https://github.com/05786k/moodify_applied-ai-system/blob/main/src/pipeline.py"
click node_retrieval "https://github.com/05786k/moodify_applied-ai-system/blob/main/src/retriever.py"
click node_embeddings "https://github.com/05786k/moodify_applied-ai-system/blob/main/src/retriever.py"
click node_scorer "https://github.com/05786k/moodify_applied-ai-system/blob/main/src/recommender.py"
click node_catalog "https://github.com/05786k/moodify_applied-ai-system/blob/main/data/songs.csv"
click node_glossary "https://github.com/05786k/moodify_applied-ai-system/blob/main/src/glossary.py"
click node_explainer "https://github.com/05786k/moodify_applied-ai-system/blob/main/src/explainer.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_streamlit,node_cli toneBlue
class node_pipeline,node_retrieval,node_embeddings,node_scorer toneAmber
class node_catalog,node_glossary toneMint
class node_explainer toneRose
class node_listener,node_claude toneIndigo
```

## Components

### User interfaces

- [Streamlit UI](https://github.com/05786k/moodify_applied-ai-system/blob/main/app.py): `app.py`
- [CLI](https://github.com/05786k/moodify_applied-ai-system/blob/main/src/main.py): `src/main.py`

### Recommendation pipeline

- [Shared pipeline](https://github.com/05786k/moodify_applied-ai-system/blob/main/src/pipeline.py): `src/pipeline.py`
- [Semantic retrieval](https://github.com/05786k/moodify_applied-ai-system/blob/main/src/retriever.py): `src/retriever.py`
- [Song embeddings](https://github.com/05786k/moodify_applied-ai-system/blob/main/src/retriever.py): `src/retriever.py`
- [Weighted scorer](https://github.com/05786k/moodify_applied-ai-system/blob/main/src/recommender.py): `src/recommender.py`

### Music knowledge

- [Song catalog](https://github.com/05786k/moodify_applied-ai-system/blob/main/data/songs.csv): `data/songs.csv`
- [Genre/mood glossary](https://github.com/05786k/moodify_applied-ai-system/blob/main/src/glossary.py): `src/glossary.py`

### Explanation generation

- [Explanation generator](https://github.com/05786k/moodify_applied-ai-system/blob/main/src/explainer.py): `src/explainer.py`

### Other components

- **Listener**
- **Anthropic Claude**

## Connections

- Listener → Streamlit UI: enters preferences (evidence: `README.md`)
- Listener → CLI: selects profile (evidence: `README.md`)
- Streamlit UI → Shared pipeline: requests recommendations (evidence: `app.py`)
- CLI → Shared pipeline: requests recommendations (evidence: `src/main.py`)
- Streamlit UI → Song catalog: loads songs (evidence: `app.py`)
- CLI → Song catalog: loads songs (evidence: `src/main.py`)
- Streamlit UI → Song embeddings: embeds songs (evidence: `app.py`)
- CLI → Song embeddings: embeds songs (evidence: `src/main.py`)
- Streamlit UI → Semantic retrieval: shows retrieval details (evidence: `app.py`)
- Streamlit UI → Weighted scorer: computes baseline (evidence: `app.py`)
- Shared pipeline → Semantic retrieval: retrieves and ranks (evidence: `src/pipeline.py`)
- Shared pipeline → Explanation generator: explains results (evidence: `src/pipeline.py`)
- Semantic retrieval → Song embeddings: compares vectors (evidence: `src/retriever.py`)
- Semantic retrieval → Genre/mood glossary: enriches query (evidence: `src/retriever.py`)
- Semantic retrieval → Weighted scorer: scores shortlist (evidence: `src/retriever.py`)
- Semantic retrieval → Song catalog: retrieves candidates (evidence: `README.md`)
- Explanation generator → Anthropic Claude: generates explanation (evidence: `src/explainer.py`)
- Explanation generator → Streamlit UI: returns explanation (evidence: `app.py`)
- Explanation generator → CLI: returns explanation (evidence: `src/main.py`)
