# alexk-cloud/multilyrical architecture

> Architecture diagram of the GitHub repository alexk-cloud/multilyrical, 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/alexk-cloud/multilyrical
- Repository: https://github.com/alexk-cloud/multilyrical

## Overview

Multilyrical is a web app for identifying songs, finding lyrics and song details, exploring lyric insights, and translating lyrics. A user can identify a song from a short recording or search by text, then view a results page with lyrics, artwork, album information, and AI-generated insights; translation is available from that page. The browser also supports saved songs and playlists, while recently viewed songs are kept in the Flask session. Source excerpts show the main route-to-service calls; connections for browser storage and external services are grounded in the JavaScript and service implementations.

Main entry points: [`src/Multilyrical/song.py`](https://github.com/alexk-cloud/multilyrical/blob/main/src/Multilyrical/song.py) (Song services), [`src/Multilyrical/app.py`](https://github.com/alexk-cloud/multilyrical/blob/main/src/Multilyrical/app.py) (Flask routes), [`src/Multilyrical/static/script.js`](https://github.com/alexk-cloud/multilyrical/blob/main/src/Multilyrical/static/script.js) (Browser interactions), [`src/Multilyrical/lyric.py`](https://github.com/alexk-cloud/multilyrical/blob/main/src/Multilyrical/lyric.py) (Lyrics translation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["Flask routes<br/>[app.py]"]
  node_views["Page templates"]
  node_browser["Browser interactions<br/>[script.js]"]
  node_styles["Page styling<br/>[style.css]"]
end

subgraph group_catalog["Song discovery"]
  node_song["Song services<br/>[song.py]"]
  node_http["HTTP session<br/>[api_client.py]"]
  node_recent["Recent songs<br/>[app.py]"]
end

subgraph group_lyrics["Lyrics and insights"]
  node_lyrics["Lyrics translation<br/>[lyric.py]"]
end

subgraph group_integrations["External services"]
  node_audio(("Microphone capture"))
  node_shazam["Shazam recognition"]
  node_lrclib["LRCLIB catalog"]
  node_coverpy["CoverPy artwork"]
  node_gemini["Gemini analysis"]
  node_translateapi["Google Translate"]
  node_storage[("Browser storage")]
end

node_user(("Listener"))

node_user -->|"uses"| node_browser
node_browser -->|"requests routes"| node_app
node_app -->|"calls song services"| node_song
node_app -->|"calls translation"| node_lyrics
node_app -->|"renders pages"| node_views
node_browser -->|"reads and writes"| node_storage
node_app -->|"updates session"| node_recent
node_song -->|"records audio"| node_audio
node_song -->|"recognizes track"| node_shazam
node_song -->|"uses session"| node_http
node_lyrics -->|"uses session"| node_http
node_song -->|"searches catalog"| node_lrclib
node_lyrics -->|"fetches lyrics"| node_lrclib
node_song -->|"fetches artwork"| node_coverpy
node_song -->|"generates insights"| node_gemini
node_lyrics -->|"translates lyrics"| node_translateapi
node_browser -.->|"displays styled pages"| node_styles

click node_app "https://github.com/alexk-cloud/multilyrical/blob/main/src/Multilyrical/app.py"
click node_views "https://github.com/alexk-cloud/multilyrical/tree/main/src/Multilyrical/templates"
click node_browser "https://github.com/alexk-cloud/multilyrical/blob/main/src/Multilyrical/static/script.js"
click node_styles "https://github.com/alexk-cloud/multilyrical/blob/main/src/Multilyrical/static/style.css"
click node_song "https://github.com/alexk-cloud/multilyrical/blob/main/src/Multilyrical/song.py"
click node_http "https://github.com/alexk-cloud/multilyrical/blob/main/src/Multilyrical/api_client.py"
click node_recent "https://github.com/alexk-cloud/multilyrical/blob/main/src/Multilyrical/app.py"
click node_lyrics "https://github.com/alexk-cloud/multilyrical/blob/main/src/Multilyrical/lyric.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_app,node_views,node_browser,node_styles toneBlue
class node_song,node_http,node_recent toneAmber
class node_lyrics toneMint
class node_audio,node_shazam,node_lrclib,node_coverpy,node_gemini,node_translateapi,node_storage toneRose
class node_user toneIndigo
```

## Components

### Web experience

- [Flask routes](https://github.com/alexk-cloud/multilyrical/blob/main/src/Multilyrical/app.py): `src/Multilyrical/app.py`
- [Page templates](https://github.com/alexk-cloud/multilyrical/tree/main/src/Multilyrical/templates): `src/Multilyrical/templates`
- [Browser interactions](https://github.com/alexk-cloud/multilyrical/blob/main/src/Multilyrical/static/script.js): `src/Multilyrical/static/script.js`
- [Page styling](https://github.com/alexk-cloud/multilyrical/blob/main/src/Multilyrical/static/style.css): `src/Multilyrical/static/style.css`

### Song discovery

- [Song services](https://github.com/alexk-cloud/multilyrical/blob/main/src/Multilyrical/song.py): `src/Multilyrical/song.py`
- [HTTP session](https://github.com/alexk-cloud/multilyrical/blob/main/src/Multilyrical/api_client.py): `src/Multilyrical/api_client.py`
- [Recent songs](https://github.com/alexk-cloud/multilyrical/blob/main/src/Multilyrical/app.py): `src/Multilyrical/app.py`

### Lyrics and insights

- [Lyrics translation](https://github.com/alexk-cloud/multilyrical/blob/main/src/Multilyrical/lyric.py): `src/Multilyrical/lyric.py`

### External services

- **Microphone capture**
- **Shazam recognition**
- **LRCLIB catalog**
- **CoverPy artwork**
- **Gemini analysis**
- **Google Translate**
- **Browser storage**

### Other components

- **Listener**

## Connections

- Listener → Browser interactions: uses (evidence: `src/Multilyrical/static/script.js`)
- Browser interactions → Flask routes: requests routes (evidence: `src/Multilyrical/static/script.js`)
- Flask routes → Song services: calls song services (evidence: `src/Multilyrical/app.py`)
- Flask routes → Lyrics translation: calls translation (evidence: `src/Multilyrical/app.py`)
- Flask routes → Page templates: renders pages (evidence: `src/Multilyrical/app.py`)
- Browser interactions → Browser storage: reads and writes (evidence: `src/Multilyrical/static/script.js`)
- Flask routes → Recent songs: updates session (evidence: `src/Multilyrical/app.py`)
- Song services → Microphone capture: records audio (evidence: `src/Multilyrical/song.py`)
- Song services → Shazam recognition: recognizes track (evidence: `src/Multilyrical/song.py`)
- Song services → HTTP session: uses session (evidence: `src/Multilyrical/song.py`)
- Lyrics translation → HTTP session: uses session (evidence: `src/Multilyrical/lyric.py`)
- Song services → LRCLIB catalog: searches catalog (evidence: `src/Multilyrical/song.py`)
- Lyrics translation → LRCLIB catalog: fetches lyrics (evidence: `src/Multilyrical/lyric.py`)
- Song services → CoverPy artwork: fetches artwork (evidence: `src/Multilyrical/song.py`)
- Song services → Gemini analysis: generates insights (evidence: `src/Multilyrical/song.py`)
- Lyrics translation → Google Translate: translates lyrics (evidence: `src/Multilyrical/lyric.py`)
- Browser interactions → Page styling: displays styled pages
