# anson10124/lyricsdb architecture

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

## Overview

LyricsDB is a synced-lyrics service with a web player and public API. The main workflow resolves a song from a platform link or search, fetches and ranks lyrics from multiple providers, stores the result for later lookups, and serves playback or export formats. The graph also includes documented verification, live progress/activity, library statistics, and optional object storage. Some subsystem links are based on README statements or SOURCE INDEX references; unsampled internals are not expanded into unverified call chains.

Main entry points: [`apps/api/src/tracks/tracks.service.ts`](https://github.com/anson10124/lyricsdb/blob/main/apps/api/src/tracks/tracks.service.ts) (Track lookup and sync), [`packages/lyrics/src/engine.ts`](https://github.com/anson10124/lyricsdb/blob/main/packages/lyrics/src/engine.ts) (Lyrics sourcing), [`apps/api/src/tracks/tracks.controller.ts`](https://github.com/anson10124/lyricsdb/blob/main/apps/api/src/tracks/tracks.controller.ts) (Track endpoints), [`apps/api/src/resolver/resolver.service.ts`](https://github.com/anson10124/lyricsdb/blob/main/apps/api/src/resolver/resolver.service.ts) (Cross-platform resolver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Web pages<br/>[page.tsx]"]
  node_player["Lyrics player<br/>[amll-player.tsx]"]
  node_statsui["Stats views<br/>[page.tsx]"]
  node_apiclient["Web API client<br/>[api-client.ts]"]
end

subgraph group_api["API services"]
  node_tracksapi["Track endpoints"]
  node_trackservice["Track lookup and sync<br/>[tracks.service.ts]"]
  node_resolverapi["Resolver endpoint"]
  node_activity["Live activity"]
  node_stats["Library statistics<br/>[stats.service.ts]"]
  node_verify["Verification challenge"]
end

subgraph group_lyrics["Resolution and lyrics"]
  node_resolver["Cross-platform resolver"]
  node_lyricsengine["Lyrics sourcing<br/>[engine.ts]"]
  node_lyricify["Lyricify fetch and parse<br/>[lyricify.ts]"]
end

subgraph group_data["Persistence and integrations"]
  node_db[("Track database<br/>[tracks.ts]")]
  node_storage["Lyrics object storage<br/>[storage.service.ts]"]
end

node_visitor(("User"))
node_s3[("S3-compatible storage")]
node_musicplatforms(("Music platforms"))
node_lyricproviders(("Lyrics providers"))

node_visitor -->|"searches or opens"| node_webapp
node_webapp -.->|"requests data"| node_apiclient
node_apiclient -->|"calls track routes"| node_tracksapi
node_visitor -->|"uses API"| node_tracksapi
node_tracksapi -->|"delegates to"| node_trackservice
node_trackservice -->|"resolves tracks"| node_resolver
node_trackservice -->|"fetches lyrics"| node_lyricsengine
node_trackservice -->|"reads and writes"| node_db
node_trackservice -->|"announces additions"| node_activity
node_trackservice -->|"stores lyric payloads"| node_storage
node_resolverapi -->|"delegates resolution"| node_resolver
node_resolver -->|"matches metadata"| node_musicplatforms
node_lyricsengine -->|"queries providers"| node_lyricproviders
node_lyricsengine -->|"fetches and parses"| node_lyricify
node_lyricsengine -.->|"returns candidates"| node_trackservice
node_trackservice -->|"checks verification"| node_verify
node_storage -->|"reads and writes"| node_s3
node_activity -->|"streams additions"| node_visitor
node_statsui -.->|"views library stats"| node_stats
node_stats -->|"aggregates library"| node_db
node_visitor -->|"plays synced lyrics"| node_player

click node_webapp "https://github.com/anson10124/lyricsdb/blob/main/apps/web/app/page.tsx"
click node_player "https://github.com/anson10124/lyricsdb/blob/main/apps/web/components/amll-player.tsx"
click node_statsui "https://github.com/anson10124/lyricsdb/blob/main/apps/web/app/stats/page.tsx"
click node_apiclient "https://github.com/anson10124/lyricsdb/blob/main/apps/web/lib/api-client.ts"
click node_tracksapi "https://github.com/anson10124/lyricsdb/blob/main/apps/api/src/tracks/tracks.controller.ts"
click node_trackservice "https://github.com/anson10124/lyricsdb/blob/main/apps/api/src/tracks/tracks.service.ts"
click node_resolverapi "https://github.com/anson10124/lyricsdb/blob/main/apps/api/src/resolver/resolver.controller.ts"
click node_resolver "https://github.com/anson10124/lyricsdb/blob/main/apps/api/src/resolver/resolver.service.ts"
click node_lyricsengine "https://github.com/anson10124/lyricsdb/blob/main/packages/lyrics/src/engine.ts"
click node_lyricify "https://github.com/anson10124/lyricsdb/blob/main/packages/lyrics/src/parsers/lyricify.ts"
click node_activity "https://github.com/anson10124/lyricsdb/blob/main/apps/api/src/activity/activity.service.ts"
click node_stats "https://github.com/anson10124/lyricsdb/blob/main/apps/api/src/stats/stats.service.ts"
click node_verify "https://github.com/anson10124/lyricsdb/blob/main/apps/api/src/turnstile/turnstile.service.ts"
click node_db "https://github.com/anson10124/lyricsdb/blob/main/packages/database/src/schema/tracks.ts"
click node_storage "https://github.com/anson10124/lyricsdb/blob/main/apps/api/src/storage/storage.service.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_webapp,node_player,node_statsui,node_apiclient,node_visitor toneBlue
class node_tracksapi,node_trackservice,node_resolverapi,node_activity,node_stats,node_verify,node_s3 toneAmber
class node_resolver,node_lyricsengine,node_lyricify toneMint
class node_db,node_storage toneRose
class node_musicplatforms,node_lyricproviders toneIndigo
```

## Components

### Web experience

- [Web pages](https://github.com/anson10124/lyricsdb/blob/main/apps/web/app/page.tsx): `apps/web/app/page.tsx`
- [Lyrics player](https://github.com/anson10124/lyricsdb/blob/main/apps/web/components/amll-player.tsx): `apps/web/components/amll-player.tsx`
- [Stats views](https://github.com/anson10124/lyricsdb/blob/main/apps/web/app/stats/page.tsx): `apps/web/app/stats/page.tsx`
- [Web API client](https://github.com/anson10124/lyricsdb/blob/main/apps/web/lib/api-client.ts): `apps/web/lib/api-client.ts`

### API services

- [Track endpoints](https://github.com/anson10124/lyricsdb/blob/main/apps/api/src/tracks/tracks.controller.ts): `apps/api/src/tracks/tracks.controller.ts`
- [Track lookup and sync](https://github.com/anson10124/lyricsdb/blob/main/apps/api/src/tracks/tracks.service.ts): `apps/api/src/tracks/tracks.service.ts`
- [Resolver endpoint](https://github.com/anson10124/lyricsdb/blob/main/apps/api/src/resolver/resolver.controller.ts): `apps/api/src/resolver/resolver.controller.ts`
- [Live activity](https://github.com/anson10124/lyricsdb/blob/main/apps/api/src/activity/activity.service.ts): `apps/api/src/activity/activity.service.ts`
- [Library statistics](https://github.com/anson10124/lyricsdb/blob/main/apps/api/src/stats/stats.service.ts): `apps/api/src/stats/stats.service.ts`
- [Verification challenge](https://github.com/anson10124/lyricsdb/blob/main/apps/api/src/turnstile/turnstile.service.ts): `apps/api/src/turnstile/turnstile.service.ts`

### Resolution and lyrics

- [Cross-platform resolver](https://github.com/anson10124/lyricsdb/blob/main/apps/api/src/resolver/resolver.service.ts): `apps/api/src/resolver/resolver.service.ts`
- [Lyrics sourcing](https://github.com/anson10124/lyricsdb/blob/main/packages/lyrics/src/engine.ts): `packages/lyrics/src/engine.ts`
- [Lyricify fetch and parse](https://github.com/anson10124/lyricsdb/blob/main/packages/lyrics/src/parsers/lyricify.ts): `packages/lyrics/src/parsers/lyricify.ts`

### Persistence and integrations

- [Track database](https://github.com/anson10124/lyricsdb/blob/main/packages/database/src/schema/tracks.ts): `packages/database/src/schema/tracks.ts`
- [Lyrics object storage](https://github.com/anson10124/lyricsdb/blob/main/apps/api/src/storage/storage.service.ts): `apps/api/src/storage/storage.service.ts`

### Other components

- **User**
- **S3-compatible storage**
- **Music platforms**
- **Lyrics providers**

## Connections

- User → Web pages: searches or opens
- Web pages → Web API client: requests data
- Web API client → Track endpoints: calls track routes (evidence: `apps/web/lib/api-client.ts`)
- User → Track endpoints: uses API
- Track endpoints → Track lookup and sync: delegates to (evidence: `apps/api/src/tracks/tracks.controller.ts`)
- Track lookup and sync → Cross-platform resolver: resolves tracks (evidence: `apps/api/src/tracks/tracks.service.ts`)
- Track lookup and sync → Lyrics sourcing: fetches lyrics (evidence: `apps/api/src/tracks/tracks.service.ts`)
- Track lookup and sync → Track database: reads and writes (evidence: `apps/api/src/tracks/tracks.service.ts`)
- Track lookup and sync → Live activity: announces additions (evidence: `apps/api/src/tracks/tracks.service.ts`)
- Track lookup and sync → Lyrics object storage: stores lyric payloads (evidence: `apps/api/src/tracks/tracks.service.ts`)
- Resolver endpoint → Cross-platform resolver: delegates resolution (evidence: `apps/api/src/resolver/resolver.controller.ts`)
- Cross-platform resolver → Music platforms: matches metadata
- Lyrics sourcing → Lyrics providers: queries providers
- Lyrics sourcing → Lyricify fetch and parse: fetches and parses (evidence: `packages/lyrics/src/engine.ts`)
- Lyrics sourcing → Track lookup and sync: returns candidates
- Track lookup and sync → Verification challenge: checks verification (evidence: `apps/api/src/tracks/tracks.controller.ts`)
- Lyrics object storage → S3-compatible storage: reads and writes (evidence: `apps/api/src/storage/storage.service.ts`)
- Live activity → User: streams additions
- Stats views → Library statistics: views library stats
- Library statistics → Track database: aggregates library (evidence: `apps/api/src/stats/stats.service.ts`)
- User → Lyrics player: plays synced lyrics
