# alfarrizi-studio/liriqo architecture

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

- Interactive diagram: https://gitdiagram.com/alfarrizi-studio/liriqo
- Repository: https://github.com/alfarrizi-studio/liriqo

## Overview

LiriQo’s sampled runtime here is its JavaScript client parser, not the public API server. The workflow is a client request to retrieve lyrics, followed by provider-aware parsing, quality selection and normalized lyric results; the parser also supports translation attachment and LRC-oriented output. The README documents the broader provider and format coverage. Source excerpts are partial, so some internal wiring—particularly selection and word-synced LRC building—is not asserted beyond documented behavior.

Main entry points: [`lyrics-parser/src/index.js`](https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/index.js) (Parser entry), [`lyrics-parser/src/util.js`](https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/util.js) (Shared utilities), [`lyrics-parser/src/api.js`](https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/api.js) (API client), [`lyrics-parser/src/words.js`](https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/words.js) (Word LRC builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_retrieval["Retrieval"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_parsing["Format parsing"]
  node_ttml_parser["TTML parser<br/>[ttml.js]"]
  node_qrc_parser["QRC parser<br/>[qrc.js]"]
  node_provider_formats["Provider formats"]
  node_lrc_parser["LRC and plain<br/>[lrc.js]"]
end

subgraph group_results["Result shaping"]
  node_parser_entry["Parser entry<br/>[index.js]"]
  node_track_selection["Track selection<br/>[select.js]"]
  node_word_lrc["Word LRC builder<br/>[words.js]"]
  node_translations["Translations<br/>[translations.js]"]
  node_shared_utilities["Shared utilities<br/>[util.js]"]
  node_normalized_lyrics["Normalized lyrics"]
end

node_developer(("Client developer"))
node_liriqo_api{{"LiriQo API"}}

node_developer -->|"requests lyrics"| node_parser_entry
node_parser_entry -->|"fetches response"| node_api_client
node_api_client -->|"requests data"| node_liriqo_api
node_liriqo_api -->|"returns JSON"| node_api_client
node_parser_entry -->|"parses TTML"| node_ttml_parser
node_parser_entry -->|"parses QRC"| node_qrc_parser
node_parser_entry -->|"parses provider formats"| node_provider_formats
node_parser_entry -->|"parses LRC and plain"| node_lrc_parser
node_parser_entry -.->|"selects tracks"| node_track_selection
node_parser_entry -->|"attaches translations"| node_translations
node_parser_entry -->|"builds results"| node_shared_utilities
node_parser_entry -->|"returns results"| node_normalized_lyrics
node_word_lrc -->|"checks timing"| node_track_selection
node_word_lrc -->|"formats timestamps"| node_shared_utilities
node_ttml_parser -->|"produces timed lyrics"| node_normalized_lyrics
node_qrc_parser -->|"uses utilities"| node_shared_utilities
node_translations -->|"uses language helper"| node_shared_utilities

click node_api_client "https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/api.js"
click node_parser_entry "https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/index.js"
click node_ttml_parser "https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/ttml.js"
click node_qrc_parser "https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/qrc.js"
click node_provider_formats "https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/provider-formats.js"
click node_lrc_parser "https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/lrc.js"
click node_track_selection "https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/select.js"
click node_word_lrc "https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/words.js"
click node_translations "https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/translations.js"
click node_shared_utilities "https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/util.js"

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_api_client,node_developer toneBlue
class node_ttml_parser,node_qrc_parser,node_provider_formats,node_lrc_parser toneAmber
class node_parser_entry,node_track_selection,node_word_lrc,node_translations,node_shared_utilities,node_normalized_lyrics,node_liriqo_api toneMint
```

## Components

### Retrieval

- [API client](https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/api.js): `lyrics-parser/src/api.js`

### Format parsing

- [TTML parser](https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/ttml.js): `lyrics-parser/src/ttml.js`
- [QRC parser](https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/qrc.js): `lyrics-parser/src/qrc.js`
- [Provider formats](https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/provider-formats.js): `lyrics-parser/src/provider-formats.js`
- [LRC and plain](https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/lrc.js): `lyrics-parser/src/lrc.js`

### Result shaping

- [Parser entry](https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/index.js): `lyrics-parser/src/index.js`
- [Track selection](https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/select.js): `lyrics-parser/src/select.js`
- [Word LRC builder](https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/words.js): `lyrics-parser/src/words.js`
- [Translations](https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/translations.js): `lyrics-parser/src/translations.js`
- [Shared utilities](https://github.com/alfarrizi-studio/liriqo/blob/main/lyrics-parser/src/util.js): `lyrics-parser/src/util.js`
- **Normalized lyrics**

### Other components

- **Client developer**
- **LiriQo API**

## Connections

- Client developer → Parser entry: requests lyrics (evidence: `README.md`)
- Parser entry → API client: fetches response (evidence: `lyrics-parser/src/index.js`)
- API client → LiriQo API: requests data (evidence: `lyrics-parser/src/api.js`)
- LiriQo API → API client: returns JSON (evidence: `lyrics-parser/src/api.js`)
- Parser entry → TTML parser: parses TTML (evidence: `lyrics-parser/src/index.js`)
- Parser entry → QRC parser: parses QRC (evidence: `lyrics-parser/src/index.js`)
- Parser entry → Provider formats: parses provider formats (evidence: `lyrics-parser/src/index.js`)
- Parser entry → LRC and plain: parses LRC and plain (evidence: `lyrics-parser/src/index.js`)
- Parser entry → Track selection: selects tracks (evidence: `lyrics-parser/src/index.js`)
- Parser entry → Translations: attaches translations (evidence: `lyrics-parser/src/index.js`)
- Parser entry → Shared utilities: builds results (evidence: `lyrics-parser/src/index.js`)
- Parser entry → Normalized lyrics: returns results (evidence: `lyrics-parser/src/index.js`)
- Word LRC builder → Track selection: checks timing (evidence: `lyrics-parser/src/words.js`)
- Word LRC builder → Shared utilities: formats timestamps (evidence: `lyrics-parser/src/words.js`)
- TTML parser → Normalized lyrics: produces timed lyrics (evidence: `lyrics-parser/src/ttml.js`)
- QRC parser → Shared utilities: uses utilities (evidence: `lyrics-parser/src/qrc.js`)
- Translations → Shared utilities: uses language helper (evidence: `lyrics-parser/src/translations.js`)