# sultvnnnn/lyrarium architecture

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

- Interactive diagram: https://gitdiagram.com/sultvnnnn/lyrarium
- Repository: https://github.com/sultvnnnn/lyrarium

## Overview

Lyrarium is a lyrics archive and discovery site. Visitors search songs and artists, browse catalog and artist pages, then open lyric entries with credits and related media. The home search supports fuzzy suggestions and voice transcription; Lyra provides song insights. Artist and song add/edit routes indicate editorial maintenance, while changelog pages expose archive updates. The sampled sources establish home and lyric-page database reads, search behavior, transcription forwarding, and Lyra caching/streaming; other route wiring is left unspecified where source excerpts were unavailable.

Main entry points: [`src/db/index.ts`](https://github.com/sultvnnnn/lyrarium/blob/main/src/db/index.ts) (Database Client), [`src/app/page.tsx`](https://github.com/sultvnnnn/lyrarium/blob/main/src/app/page.tsx) (Home), [`src/components/hero-search.tsx`](https://github.com/sultvnnnn/lyrarium/blob/main/src/components/hero-search.tsx) (Search Interface), [`src/app/lyrics/[id]/page.tsx`](https://github.com/sultvnnnn/lyrarium/blob/main/src/app/lyrics/%5Bid%5D/page.tsx) (Lyrics Entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Discovery & Catalog"]
  node_home["Home<br/>[page.tsx]"]
  node_search_ui["Search Interface<br/>[hero-search.tsx]"]
  node_song_catalog["Song Catalog<br/>[page.tsx]"]
  node_artist_catalog["Artist Catalog<br/>[page.tsx]"]
  node_artist_profile["Artist Profile<br/>[page.tsx]"]
end

subgraph group_entries["Lyrics &amp; Editorial"]
  node_song_detail["Lyrics Entry<br/>[page.tsx]"]
  node_song_forms["Song Editing<br/>[edit-song-form.tsx]"]
  node_artist_forms["Artist Editing"]
  node_song_actions["Song Actions<br/>[songs.tsx]"]
  node_artist_actions["Artist Actions<br/>[artists.ts]"]
  node_changelog["Changelog<br/>[page.tsx]"]
  node_youtube_parser["Video Link Parser<br/>[youtube.ts]"]
end

subgraph group_intelligence["Search &amp; Insights"]
  node_search_engine["Fuzzy Search<br/>[search-engine.ts]"]
  node_fuzzy["Trigram Matching<br/>[fuzzy.ts]"]
  node_transcription["Voice Transcription<br/>[route.ts]"]
  node_lyra_ui["Lyra Interface<br/>[ask-lyra.tsx]"]
  node_lyra_api["Lyra Endpoint<br/>[route.ts]"]
  node_lyra_service["Lyra Provider<br/>[lyra.ts]"]
end

subgraph group_persistence["Data &amp; Media"]
  node_db_client["Database Client<br/>[index.ts]"]
  node_archive_db[("Archive Database<br/>[schema.ts]")]
  node_image_storage["Image Storage"]
end

node_visitor(("Visitor"))
node_groq{{"Groq Whisper"}}
node_ai_provider{{"AI Provider"}}
node_supabase{{"Supabase Storage"}}

node_visitor -->|"opens"| node_home
node_visitor -->|"browses"| node_song_catalog
node_visitor -->|"browses"| node_artist_catalog
node_visitor -->|"opens"| node_artist_profile
node_visitor -->|"opens"| node_song_detail
node_visitor -->|"queries"| node_search_ui
node_home -->|"reads archive"| node_db_client
node_home -->|"searches results"| node_search_engine
node_search_ui -->|"matches query"| node_search_engine
node_search_engine -->|"builds suggestions"| node_fuzzy
node_search_ui -->|"posts audio"| node_transcription
node_transcription -->|"forwards audio"| node_groq
node_song_detail -->|"reads entry"| node_db_client
node_song_detail -->|"parses video links"| node_youtube_parser
node_lyra_ui -->|"requests insight"| node_lyra_api
node_lyra_api -->|"reads and caches"| node_db_client
node_lyra_api -->|"streams response"| node_lyra_service
node_lyra_service -.->|"requests generation"| node_ai_provider
node_db_client -->|"queries"| node_archive_db
node_image_storage -->|"uploads images"| node_supabase

click node_home "https://github.com/sultvnnnn/lyrarium/blob/main/src/app/page.tsx"
click node_search_ui "https://github.com/sultvnnnn/lyrarium/blob/main/src/components/hero-search.tsx"
click node_song_catalog "https://github.com/sultvnnnn/lyrarium/blob/main/src/app/songs/page.tsx"
click node_artist_catalog "https://github.com/sultvnnnn/lyrarium/blob/main/src/app/artists/page.tsx"
click node_artist_profile "https://github.com/sultvnnnn/lyrarium/blob/main/src/app/artist/%5Bslug%5D/page.tsx"
click node_song_detail "https://github.com/sultvnnnn/lyrarium/blob/main/src/app/lyrics/%5Bid%5D/page.tsx"
click node_song_forms "https://github.com/sultvnnnn/lyrarium/blob/main/src/components/edit-song-form.tsx"
click node_artist_forms "https://github.com/sultvnnnn/lyrarium/blob/main/src/components/edit-artist-form.tsx"
click node_song_actions "https://github.com/sultvnnnn/lyrarium/blob/main/src/app/actions/songs.tsx"
click node_artist_actions "https://github.com/sultvnnnn/lyrarium/blob/main/src/app/actions/artists.ts"
click node_changelog "https://github.com/sultvnnnn/lyrarium/blob/main/src/app/changelog/page.tsx"
click node_search_engine "https://github.com/sultvnnnn/lyrarium/blob/main/src/lib/search-engine.ts"
click node_fuzzy "https://github.com/sultvnnnn/lyrarium/blob/main/src/lib/fuzzy.ts"
click node_transcription "https://github.com/sultvnnnn/lyrarium/blob/main/src/app/api/transcribe/route.ts"
click node_lyra_ui "https://github.com/sultvnnnn/lyrarium/blob/main/src/components/ask-lyra.tsx"
click node_lyra_api "https://github.com/sultvnnnn/lyrarium/blob/main/src/app/api/lyra/route.ts"
click node_lyra_service "https://github.com/sultvnnnn/lyrarium/blob/main/src/lib/lyra.ts"
click node_db_client "https://github.com/sultvnnnn/lyrarium/blob/main/src/db/index.ts"
click node_archive_db "https://github.com/sultvnnnn/lyrarium/blob/main/src/db/schema.ts"
click node_image_storage "https://github.com/sultvnnnn/lyrarium/blob/main/src/lib/supabase-storage.ts"
click node_youtube_parser "https://github.com/sultvnnnn/lyrarium/blob/main/src/lib/youtube.ts"

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_ui,node_song_catalog,node_artist_catalog,node_artist_profile toneBlue
class node_song_detail,node_song_forms,node_artist_forms,node_song_actions,node_artist_actions,node_changelog,node_youtube_parser,node_supabase toneAmber
class node_search_engine,node_fuzzy,node_transcription,node_lyra_ui,node_lyra_api,node_lyra_service toneMint
class node_db_client,node_archive_db,node_image_storage toneRose
class node_visitor,node_groq,node_ai_provider toneIndigo
```

## Components

### Discovery & Catalog

- [Home](https://github.com/sultvnnnn/lyrarium/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Search Interface](https://github.com/sultvnnnn/lyrarium/blob/main/src/components/hero-search.tsx): `src/components/hero-search.tsx`
- [Song Catalog](https://github.com/sultvnnnn/lyrarium/blob/main/src/app/songs/page.tsx): `src/app/songs/page.tsx`
- [Artist Catalog](https://github.com/sultvnnnn/lyrarium/blob/main/src/app/artists/page.tsx): `src/app/artists/page.tsx`
- [Artist Profile](https://github.com/sultvnnnn/lyrarium/blob/main/src/app/artist/%5Bslug%5D/page.tsx): `src/app/artist/[slug]/page.tsx`

### Lyrics & Editorial

- [Lyrics Entry](https://github.com/sultvnnnn/lyrarium/blob/main/src/app/lyrics/%5Bid%5D/page.tsx): `src/app/lyrics/[id]/page.tsx`
- [Song Editing](https://github.com/sultvnnnn/lyrarium/blob/main/src/components/edit-song-form.tsx): `src/components/edit-song-form.tsx`
- [Artist Editing](https://github.com/sultvnnnn/lyrarium/blob/main/src/components/edit-artist-form.tsx): `src/components/edit-artist-form.tsx`
- [Song Actions](https://github.com/sultvnnnn/lyrarium/blob/main/src/app/actions/songs.tsx): `src/app/actions/songs.tsx`
- [Artist Actions](https://github.com/sultvnnnn/lyrarium/blob/main/src/app/actions/artists.ts): `src/app/actions/artists.ts`
- [Changelog](https://github.com/sultvnnnn/lyrarium/blob/main/src/app/changelog/page.tsx): `src/app/changelog/page.tsx`
- [Video Link Parser](https://github.com/sultvnnnn/lyrarium/blob/main/src/lib/youtube.ts): `src/lib/youtube.ts`

### Search & Insights

- [Fuzzy Search](https://github.com/sultvnnnn/lyrarium/blob/main/src/lib/search-engine.ts): `src/lib/search-engine.ts`
- [Trigram Matching](https://github.com/sultvnnnn/lyrarium/blob/main/src/lib/fuzzy.ts): `src/lib/fuzzy.ts`
- [Voice Transcription](https://github.com/sultvnnnn/lyrarium/blob/main/src/app/api/transcribe/route.ts): `src/app/api/transcribe/route.ts`
- [Lyra Interface](https://github.com/sultvnnnn/lyrarium/blob/main/src/components/ask-lyra.tsx): `src/components/ask-lyra.tsx`
- [Lyra Endpoint](https://github.com/sultvnnnn/lyrarium/blob/main/src/app/api/lyra/route.ts): `src/app/api/lyra/route.ts`
- [Lyra Provider](https://github.com/sultvnnnn/lyrarium/blob/main/src/lib/lyra.ts): `src/lib/lyra.ts`

### Data & Media

- [Database Client](https://github.com/sultvnnnn/lyrarium/blob/main/src/db/index.ts): `src/db/index.ts`
- [Archive Database](https://github.com/sultvnnnn/lyrarium/blob/main/src/db/schema.ts): `src/db/schema.ts`
- [Image Storage](https://github.com/sultvnnnn/lyrarium/blob/main/src/lib/supabase-storage.ts): `src/lib/supabase-storage.ts`

### Other components

- **Visitor**
- **Groq Whisper**
- **AI Provider**
- **Supabase Storage**

## Connections

- Visitor → Home: opens
- Visitor → Song Catalog: browses
- Visitor → Artist Catalog: browses
- Visitor → Artist Profile: opens
- Visitor → Lyrics Entry: opens
- Visitor → Search Interface: queries
- Home → Database Client: reads archive
- Home → Fuzzy Search: searches results
- Search Interface → Fuzzy Search: matches query
- Fuzzy Search → Trigram Matching: builds suggestions
- Search Interface → Voice Transcription: posts audio
- Voice Transcription → Groq Whisper: forwards audio
- Lyrics Entry → Database Client: reads entry
- Lyrics Entry → Video Link Parser: parses video links
- Lyra Interface → Lyra Endpoint: requests insight
- Lyra Endpoint → Database Client: reads and caches
- Lyra Endpoint → Lyra Provider: streams response
- Lyra Provider → AI Provider: requests generation
- Database Client → Archive Database: queries
- Image Storage → Supabase Storage: uploads images