# chenmozhijin/lddc architecture

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

- Interactive diagram: https://gitdiagram.com/chenmozhijin/lddc
- Repository: https://github.com/chenmozhijin/lddc

## Overview

##### Project type and purpose
- LDDC is a desktop application (cross-platform Windows/macOS/Linux) written in Python 3.10+.
- It provides precise, per-character lyrics download, matching, conversion, translation, and desktop–lyrics display via a PyQt GUI or CLI.

##### File structure and technical stack
- Top-level modules:
- LDDC/common: shared utilities, config, caching, logging, versioning
- LDDC/core: core engine
– algorithm.py (matching orchestrator)
– api/lyrics & api/translate (adapters to QQMusic, Kugou, NetEase, Lrclib, Bing/Google/OpenAI)
– auto_fetch, converter (LRC/SRT/ASS), decryptor (e.g. eapi, qmc1), parser (parser for various lyric formats), song_info
- LDDC/gui: PyQt-based UI
– ui (QtDesigner .ui files + generated code)
– view (controllers for each dialog/window)
– workers (background tasks for conversion, matching)
- Auxiliary files:
- build_helper.py, pyproject.toml (packaging)
- requirements*.txt (dependencies)
- .github/workflows (CI build/test)
- tests (unit/UI tests using pytest + PyQt test harness)

##### Information from README.md
- Emphasizes multi-threaded matching, per-character timing, multiple formats, translation, desktop-lyrics plugin compatibility.
- Lists external platforms (QQ音乐, 酷狗, 网易云, Lrclib) and translation APIs.

##### Main components
a. Frontends
- CLI interface (LDDC/__main__.py → common/args → core)
- GUI (PyQt layers: UI files → view controllers → service module → core)
b. Core Engine
- TaskManager / ThreadManager (multi-thread orchestration)
- Algorithm module (matching logic)
- API Adapters (lyrics fetch, translation fetch)
- Decryptors (encrypted local lyric formats)
- Parsers (input lyric‐format parsing)
- Converters (output format generation)
- SongInfo (metadata extraction)
c. Data layer
- Cache (common/data/cache.py)
- Local DB (common/data/local_song_lyrics_db.py)
- Config (common/data/config.py)
- File system (read/write lyric files, song tags)
d. External services
- Music platforms (QQMusic API, Kugou API, NetEase API, Lrclib)
- Translation APIs (Bing, Google, OpenAI)
e. Resources
- Qt resource file (res/resource.qrc)
- Images and translations (res/img, res/i18n)

##### Relationships and data flow
- User trigger → Frontend (CLI or GUI) → Service layer
- Service layer invokes Core Engine →
1. Fetch song metadata (SongInfo)
2. Request lyrics via API adapters (multi-threaded)
3. If encrypted, pass through decryptor → parser
4. Optionally request translation via translation adapters
5. Assemble per-character sync data → converter to desired format
6. Save to file system or local DB; optionally tag audio file
- Desktop-lyrics plugin subscribes to matching results via GUI service
- Cache layer avoids redundant external calls

##### Architectural patterns and design principles
- Layered architecture: Presentation (CLI/GUI) → Application service → Core engine → Data → External
- Adapter pattern for external APIs (lyrics & translation)
- Strategy pattern for parsing/converter modules
- Multi-threading concerns isolated in TaskManager/ThreadManager
- MVC-ish separation in GUI: .ui → view → service

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    CLI["CLI"]:::frontend
    CLIArgs["Args Parser"]:::frontend
    GUI["GUI (PyQt)"]:::frontend
    GUIService["GUI Service"]:::frontend
    GUIComponents["Components"]:::frontend
    GUIUI["UI Definitions"]:::frontend
    GUIView["View Controllers"]:::frontend
    GUIWorkers["Background Workers"]:::frontend

    click CLI "https://github.com/chenmozhijin/lddc/blob/main/LDDC/__main__.py"
    click CLIArgs "https://github.com/chenmozhijin/lddc/blob/main/LDDC/common/args.py"
    click GUIService "https://github.com/chenmozhijin/lddc/blob/main/LDDC/gui/service.py"
    click GUIComponents "https://github.com/chenmozhijin/lddc/tree/main/LDDC/gui/components/"
    click GUIUI "https://github.com/chenmozhijin/lddc/tree/main/LDDC/gui/ui/"
    click GUIView "https://github.com/chenmozhijin/lddc/tree/main/LDDC/gui/view/"
    click GUIWorkers "https://github.com/chenmozhijin/lddc/tree/main/LDDC/gui/workers/"

    CLI --> Service
    CLIArgs --> Service
    GUI --> Service
    GUIService --> Service
    GUIComponents --> Service
    GUIUI --> Service
    GUIView --> Service
    GUIWorkers --> Service

    %% Service Layer
    Service["Service Layer"]:::core

    %% Core Engine Layer
    subgraph "Core Engine"
        direction TB
        TaskMgr["Task/Thread Manager"]:::core
        Algorithm["Matching Algorithm"]:::core
        subgraph "API Adapters"
            direction TB
            subgraph "Lyrics Adapters"
                QM["QQMusic Adapter"]:::core
                KG["Kugou Adapter"]:::core
                NE["NetEase Adapter"]:::core
                LR["Lrclib Adapter"]:::core
                LocalA["Local File Adapter"]:::core
            end
            subgraph "Translation Adapters"
                Bing["Bing Translator"]:::core
                Google["Google Translator"]:::core
                OpenAI["OpenAI Translator"]:::core
            end
        end
        Decrypt["Decryptors"]:::core
        Parser["Parsers"]:::core
        Convert["Converters"]:::core
        SongInfo["Song Metadata"]:::core
    end

    click TaskMgr "https://github.com/chenmozhijin/lddc/blob/main/LDDC/common/task_manager.py"
    click TaskMgr "https://github.com/chenmozhijin/lddc/blob/main/LDDC/common/thread.py"
    click Algorithm "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/algorithm.py"
    click QM "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/api/lyrics/qm.py"
    click KG "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/api/lyrics/kg.py"
    click NE "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/api/lyrics/ne.py"
    click LR "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/api/lyrics/lrclib.py"
    click LocalA "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/api/lyrics/local.py"
    click Bing "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/api/translate/bing.py"
    click Google "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/api/translate/google.py"
    click OpenAI "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/api/translate/openai.py"
    click Decrypt "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/decryptor/eapi.py"
    click Decrypt "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/decryptor/qmc1.py"
    click Decrypt "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/decryptor/tripledes.py"
    click Parser "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/parser/ass.py"
    click Parser "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/parser/cue.py"
    click Parser "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/parser/json_lrc.py"
    click Parser "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/parser/krc.py"
    click Parser "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/parser/lrc.py"
    click Parser "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/parser/qrc.py"
    click Parser "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/parser/srt.py"
    click Parser "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/parser/yrc.py"
    click Convert "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/converter/lrc.py"
    click Convert "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/converter/srt.py"
    click Convert "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/converter/ass.py"
    click SongInfo "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/song_info.py"

    Service --> TaskMgr
    Service --> Algorithm
    Algorithm --> QM & KG & NE & LR & LocalA
    Algorithm --> Bing & Google & OpenAI
    Algorithm --> Decrypt
    Decrypt --> Parser
    Parser --> Convert
    Convert --> FS
    Convert --> LocalDB
    Convert --> Cache
    Service --> SongInfo

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Cache[(Cache)]:::data
        LocalDB[(Local DB)]:::data
        Config[(Config)]:::data
        PathUtils["Path Utilities"]:::data
        FS[/"File System"/]:::data
    end

    click Cache "https://github.com/chenmozhijin/lddc/blob/main/LDDC/common/data/cache.py"
    click LocalDB "https://github.com/chenmozhijin/lddc/blob/main/LDDC/common/data/local_song_lyrics_db.py"
    click Config "https://github.com/chenmozhijin/lddc/blob/main/LDDC/common/data/config.py"
    click PathUtils "https://github.com/chenmozhijin/lddc/blob/main/LDDC/common/path_processor.py"
    click PathUtils "https://github.com/chenmozhijin/lddc/blob/main/LDDC/common/paths.py"

    TaskMgr --> Cache
    TaskMgr --> LocalDB
    Algorithm --> Cache

    %% External Services
    external_music((Music Platforms)):::external
    external_translate((Translation APIs)):::external

    click external_music "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/api/lyrics/models.py"
    click external_translate "https://github.com/chenmozhijin/lddc/blob/main/LDDC/core/api/translate/models.py"

    QM & KG & NE & LR --> external_music
    Bing & Google & OpenAI --> external_translate

    %% Styles
    classDef frontend fill:#add8e6,stroke:#000
    classDef core fill:#90ee90,stroke:#000
    classDef data fill:#f4f4f4,stroke:#000
    classDef external fill:#d3d3d3,stroke:#000
```
