How anson10124/lyricsdb works
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: tracks.service.ts Track lookup and sync · engine.ts Lyrics sourcing · tracks.controller.ts Track endpoints · resolver.service.ts Cross-platform resolver
Components 19
Web experience
- Web pages
apps/web/app/page.tsx - Lyrics player
apps/web/components/amll-player.tsx - Stats views
apps/web/app/stats/page.tsx - Web API client
apps/web/lib/api-client.ts
API services
- Track endpoints
apps/api/src/tracks/tracks.controller.ts - Track lookup and sync
apps/api/src/tracks/tracks.service.ts - Resolver endpoint
apps/api/src/resolver/resolver.controller.ts - Live activity
apps/api/src/activity/activity.service.ts - Library statistics
apps/api/src/stats/stats.service.ts - Verification challenge
apps/api/src/turnstile/turnstile.service.ts
Resolution and lyrics
- Cross-platform resolver
apps/api/src/resolver/resolver.service.ts - Lyrics sourcing
packages/lyrics/src/engine.ts - Lyricify fetch and parse
packages/lyrics/src/parsers/lyricify.ts
Persistence and integrations
- Track database
packages/database/src/schema/tracks.ts - Lyrics object storage
apps/api/src/storage/storage.service.ts
Other components
- User
- S3-compatible storage
- Music platforms
- Lyrics providers
Connections 21
- User → Web pages: searches or opens
- Web pages → Web API client: requests data
- Web API client → Track endpoints: calls track routes
apps/web/lib/api-client.ts - User → Track endpoints: uses API
- Track endpoints → Track lookup and sync: delegates to
apps/api/src/tracks/tracks.controller.ts - Track lookup and sync → Cross-platform resolver: resolves tracks
apps/api/src/tracks/tracks.service.ts - Track lookup and sync → Lyrics sourcing: fetches lyrics
apps/api/src/tracks/tracks.service.ts - Track lookup and sync → Track database: reads and writes
apps/api/src/tracks/tracks.service.ts - Track lookup and sync → Live activity: announces additions
apps/api/src/tracks/tracks.service.ts - Track lookup and sync → Lyrics object storage: stores lyric payloads
apps/api/src/tracks/tracks.service.ts - Resolver endpoint → Cross-platform resolver: delegates resolution
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
packages/lyrics/src/engine.ts - Lyrics sourcing → Track lookup and sync: returns candidates
- Track lookup and sync → Verification challenge: checks verification
apps/api/src/tracks/tracks.controller.ts - Lyrics object storage → S3-compatible storage: reads and writes
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
apps/api/src/stats/stats.service.ts - User → Lyrics player: plays synced lyrics