# mkcodes4/the-swift-journal architecture

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

- Interactive diagram: https://gitdiagram.com/mkcodes4/the-swift-journal
- Repository: https://github.com/mkcodes4/the-swift-journal

## Overview

Taylor Swift Discography Analysis combines a lyric-and-album exploration website with a Python API for semantic search and AI-assisted chat. Users can explore sentiment and era patterns, search lyrics by meaning, or ask the chat agent a question; the backend routes chat queries to lyric or statistics tools, gathers evidence, and synthesizes a response. The graph includes documented analysis and discovery capabilities, but sampled evidence does not establish how the Next.js API routes connect to the Python service or which datasets power every page.

Main entry points: [`server/main.py`](https://github.com/mkcodes4/the-swift-journal/blob/main/server/main.py) (Python API), [`server/agents/coordinator.py`](https://github.com/mkcodes4/the-swift-journal/blob/main/server/agents/coordinator.py) (Query coordinator), [`app/sentiment/page.tsx`](https://github.com/mkcodes4/the-swift-journal/blob/main/app/sentiment/page.tsx) (Sentiment explorer), [`server/agents/lyrics_agent.py`](https://github.com/mkcodes4/the-swift-journal/blob/main/server/agents/lyrics_agent.py) (Lyrics agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_home["Discography home<br/>[page.tsx]"]
  node_search_page["Vault search page<br/>[page.tsx]"]
  node_sentiment_page["Sentiment explorer<br/>[page.tsx]"]
  node_trends_page["Era trends page<br/>[page.tsx]"]
  node_chat_ui["Chat interface<br/>[ChatAgent.tsx]"]
  node_exhibit["Song exhibit modal<br/>[ExhibitModal.tsx]"]
  node_header["Site navigation<br/>[Header.tsx]"]
end

subgraph group_api["API layer"]
  node_chat_route["Chat API route<br/>[route.ts]"]
  node_sentiment_route["Sentiment API route<br/>[route.ts]"]
  node_songs_route["Songs API route<br/>[route.ts]"]
  node_vault_route["Vault search route<br/>[route.ts]"]
  node_fastapi["Python API<br/>[main.py]"]
end

subgraph group_agents["Chat agents"]
  node_memory["Chat memory<br/>[memory.py]"]
  node_coordinator["Query coordinator<br/>[coordinator.py]"]
  node_intent_router["Intent router<br/>[router.py]"]
  node_response_cache["Response cache<br/>[cache.py]"]
  node_lyrics_agent["Lyrics agent<br/>[lyrics_agent.py]"]
  node_stats_agent["Statistics agent<br/>[stats_agent.py]"]
end

subgraph group_analysis["Analysis and data"]
  node_lyrics_tools["Lyrics search tools<br/>[lyrics_tools.py]"]
  node_stats_tools["Album statistics tools<br/>[stats_tools.py]"]
  node_analysis_engine["Analysis engine"]
  node_web_data[("Web analysis data")]
  node_server_data[("Server analysis data")]
end

node_visitor(("Visitor"))
node_gemini["Google Gemini"]

node_visitor -->|"opens"| node_home
node_visitor -->|"searches"| node_search_page
node_visitor -->|"explores"| node_sentiment_page
node_visitor -->|"explores"| node_trends_page
node_home -.->|"renders"| node_header
node_chat_ui -->|"submits chat"| node_chat_route
node_sentiment_page -->|"fetches songs"| node_songs_route
node_search_page -->|"opens exhibits"| node_exhibit
node_sentiment_page -->|"opens exhibits"| node_exhibit
node_fastapi -->|"reads and updates"| node_memory
node_fastapi -->|"searches lyrics"| node_lyrics_tools
node_fastapi -->|"initializes tools"| node_stats_tools
node_fastapi -->|"initializes agent"| node_lyrics_agent
node_fastapi -->|"initializes agent"| node_stats_agent
node_fastapi -->|"handles chat"| node_coordinator
node_coordinator -->|"checks and saves"| node_response_cache
node_coordinator -->|"routes query"| node_intent_router
node_coordinator -->|"dispatches lyrics"| node_lyrics_agent
node_coordinator -->|"dispatches stats"| node_stats_agent
node_coordinator -->|"synthesizes answer"| node_gemini
node_lyrics_agent -->|"searches content"| node_lyrics_tools
node_stats_agent -->|"gets album stats"| node_stats_tools
node_lyrics_tools -.->|"loads lyrics"| node_server_data
node_stats_tools -.->|"loads album records"| node_server_data
node_analysis_engine -.->|"produces analysis"| node_web_data
node_vault_route -.->|"forwards search"| node_fastapi
node_chat_route -.->|"forwards chat"| node_fastapi

click node_home "https://github.com/mkcodes4/the-swift-journal/blob/main/app/page.tsx"
click node_search_page "https://github.com/mkcodes4/the-swift-journal/blob/main/app/search/page.tsx"
click node_sentiment_page "https://github.com/mkcodes4/the-swift-journal/blob/main/app/sentiment/page.tsx"
click node_trends_page "https://github.com/mkcodes4/the-swift-journal/blob/main/app/trends/page.tsx"
click node_chat_ui "https://github.com/mkcodes4/the-swift-journal/blob/main/components/ChatAgent.tsx"
click node_exhibit "https://github.com/mkcodes4/the-swift-journal/blob/main/components/ExhibitModal.tsx"
click node_header "https://github.com/mkcodes4/the-swift-journal/blob/main/components/Header.tsx"
click node_chat_route "https://github.com/mkcodes4/the-swift-journal/blob/main/app/api/chat/route.ts"
click node_sentiment_route "https://github.com/mkcodes4/the-swift-journal/blob/main/app/api/sentiment/route.ts"
click node_songs_route "https://github.com/mkcodes4/the-swift-journal/blob/main/app/api/songs/route.ts"
click node_vault_route "https://github.com/mkcodes4/the-swift-journal/blob/main/app/api/vault-search/route.ts"
click node_fastapi "https://github.com/mkcodes4/the-swift-journal/blob/main/server/main.py"
click node_memory "https://github.com/mkcodes4/the-swift-journal/blob/main/server/core/memory.py"
click node_coordinator "https://github.com/mkcodes4/the-swift-journal/blob/main/server/agents/coordinator.py"
click node_intent_router "https://github.com/mkcodes4/the-swift-journal/blob/main/server/core/router.py"
click node_response_cache "https://github.com/mkcodes4/the-swift-journal/blob/main/server/core/cache.py"
click node_lyrics_agent "https://github.com/mkcodes4/the-swift-journal/blob/main/server/agents/lyrics_agent.py"
click node_stats_agent "https://github.com/mkcodes4/the-swift-journal/blob/main/server/agents/stats_agent.py"
click node_lyrics_tools "https://github.com/mkcodes4/the-swift-journal/blob/main/server/tools/lyrics_tools.py"
click node_stats_tools "https://github.com/mkcodes4/the-swift-journal/blob/main/server/tools/stats_tools.py"
click node_analysis_engine "https://github.com/mkcodes4/the-swift-journal/blob/main/fusion_analysis_engine.py"
click node_web_data "https://github.com/mkcodes4/the-swift-journal/blob/main/data/taylor_swift_roberta_analysis_v3.json"
click node_server_data "https://github.com/mkcodes4/the-swift-journal/blob/main/server/data/taylor_swift_roberta_analysis_v3.json"

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_search_page,node_sentiment_page,node_trends_page,node_chat_ui,node_exhibit,node_header toneBlue
class node_chat_route,node_sentiment_route,node_songs_route,node_vault_route,node_fastapi toneAmber
class node_memory,node_coordinator,node_intent_router,node_response_cache,node_lyrics_agent,node_stats_agent toneMint
class node_lyrics_tools,node_stats_tools,node_analysis_engine,node_web_data,node_server_data toneRose
class node_visitor,node_gemini toneIndigo
```

## Components

### Web experience

- [Discography home](https://github.com/mkcodes4/the-swift-journal/blob/main/app/page.tsx): `app/page.tsx`
- [Vault search page](https://github.com/mkcodes4/the-swift-journal/blob/main/app/search/page.tsx): `app/search/page.tsx`
- [Sentiment explorer](https://github.com/mkcodes4/the-swift-journal/blob/main/app/sentiment/page.tsx): `app/sentiment/page.tsx`
- [Era trends page](https://github.com/mkcodes4/the-swift-journal/blob/main/app/trends/page.tsx): `app/trends/page.tsx`
- [Chat interface](https://github.com/mkcodes4/the-swift-journal/blob/main/components/ChatAgent.tsx): `components/ChatAgent.tsx`
- [Song exhibit modal](https://github.com/mkcodes4/the-swift-journal/blob/main/components/ExhibitModal.tsx): `components/ExhibitModal.tsx`
- [Site navigation](https://github.com/mkcodes4/the-swift-journal/blob/main/components/Header.tsx): `components/Header.tsx`

### API layer

- [Chat API route](https://github.com/mkcodes4/the-swift-journal/blob/main/app/api/chat/route.ts): `app/api/chat/route.ts`
- [Sentiment API route](https://github.com/mkcodes4/the-swift-journal/blob/main/app/api/sentiment/route.ts): `app/api/sentiment/route.ts`
- [Songs API route](https://github.com/mkcodes4/the-swift-journal/blob/main/app/api/songs/route.ts): `app/api/songs/route.ts`
- [Vault search route](https://github.com/mkcodes4/the-swift-journal/blob/main/app/api/vault-search/route.ts): `app/api/vault-search/route.ts`
- [Python API](https://github.com/mkcodes4/the-swift-journal/blob/main/server/main.py): `server/main.py`

### Chat agents

- [Chat memory](https://github.com/mkcodes4/the-swift-journal/blob/main/server/core/memory.py): `server/core/memory.py`
- [Query coordinator](https://github.com/mkcodes4/the-swift-journal/blob/main/server/agents/coordinator.py): `server/agents/coordinator.py`
- [Intent router](https://github.com/mkcodes4/the-swift-journal/blob/main/server/core/router.py): `server/core/router.py`
- [Response cache](https://github.com/mkcodes4/the-swift-journal/blob/main/server/core/cache.py): `server/core/cache.py`
- [Lyrics agent](https://github.com/mkcodes4/the-swift-journal/blob/main/server/agents/lyrics_agent.py): `server/agents/lyrics_agent.py`
- [Statistics agent](https://github.com/mkcodes4/the-swift-journal/blob/main/server/agents/stats_agent.py): `server/agents/stats_agent.py`

### Analysis and data

- [Lyrics search tools](https://github.com/mkcodes4/the-swift-journal/blob/main/server/tools/lyrics_tools.py): `server/tools/lyrics_tools.py`
- [Album statistics tools](https://github.com/mkcodes4/the-swift-journal/blob/main/server/tools/stats_tools.py): `server/tools/stats_tools.py`
- [Analysis engine](https://github.com/mkcodes4/the-swift-journal/blob/main/fusion_analysis_engine.py): `fusion_analysis_engine.py`
- [Web analysis data](https://github.com/mkcodes4/the-swift-journal/blob/main/data/taylor_swift_roberta_analysis_v3.json): `data/taylor_swift_roberta_analysis_v3.json`
- [Server analysis data](https://github.com/mkcodes4/the-swift-journal/blob/main/server/data/taylor_swift_roberta_analysis_v3.json): `server/data/taylor_swift_roberta_analysis_v3.json`

### Other components

- **Visitor**
- **Google Gemini**

## Connections

- Visitor → Discography home: opens (evidence: `README.md`)
- Visitor → Vault search page: searches (evidence: `README.md`)
- Visitor → Sentiment explorer: explores (evidence: `README.md`)
- Visitor → Era trends page: explores (evidence: `README.md`)
- Discography home → Site navigation: renders
- Chat interface → Chat API route: submits chat (evidence: `components/ChatAgent.tsx`)
- Sentiment explorer → Songs API route: fetches songs (evidence: `app/sentiment/page.tsx`)
- Vault search page → Song exhibit modal: opens exhibits (evidence: `app/search/page.tsx`)
- Sentiment explorer → Song exhibit modal: opens exhibits (evidence: `app/sentiment/page.tsx`)
- Python API → Chat memory: reads and updates (evidence: `server/main.py`)
- Python API → Lyrics search tools: searches lyrics (evidence: `server/main.py`)
- Python API → Album statistics tools: initializes tools (evidence: `server/main.py`)
- Python API → Lyrics agent: initializes agent (evidence: `server/main.py`)
- Python API → Statistics agent: initializes agent (evidence: `server/main.py`)
- Python API → Query coordinator: handles chat (evidence: `server/main.py`)
- Query coordinator → Response cache: checks and saves (evidence: `server/agents/coordinator.py`)
- Query coordinator → Intent router: routes query (evidence: `server/agents/coordinator.py`)
- Query coordinator → Lyrics agent: dispatches lyrics (evidence: `server/agents/coordinator.py`)
- Query coordinator → Statistics agent: dispatches stats (evidence: `server/agents/coordinator.py`)
- Query coordinator → Google Gemini: synthesizes answer (evidence: `server/agents/coordinator.py`)
- Lyrics agent → Lyrics search tools: searches content (evidence: `server/agents/lyrics_agent.py`)
- Statistics agent → Album statistics tools: gets album stats (evidence: `server/agents/stats_agent.py`)
- Lyrics search tools → Server analysis data: loads lyrics
- Album statistics tools → Server analysis data: loads album records
- Analysis engine → Web analysis data: produces analysis
- Vault search route → Python API: forwards search
- Chat API route → Python API: forwards chat
