# presburger/qmc-decoder architecture

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

- Interactive diagram: https://gitdiagram.com/presburger/qmc-decoder
- Repository: https://github.com/presburger/qmc-decoder

## Overview

##### Main Components
- Command-line Interface (CLI): The starting point—users invoke the executable with the path to the QMC file(s).
- Decoder Engine: The core functionality, implemented primarily in “src/decoder.cpp” and backed by utility functions/definitions in “src/seed.hpp”.
- File I/O and Filesystem Abstraction: Although it’s a simple tool, note the reliance on a third-party filesystem library (in “3rdparty/filesystem”) to manage cross-platform file operations.
- Build System: CMake is used as the build automation tool (as evidenced by CMakeLists.txt). The presence of configuration files like “.clang-format” and CI configurations in “.github/workflows/build.yml” signals additional layers of process and quality control.
- Platform-specific Handling: The project provides specific instructions for Linux, macOS, and Windows execution (e.g., “decoder.command” for macOS, different build commands for Windows).

##### Relationships and Interactions
- CLI → Decoder Engine: Illustrate how the CLI passes the file path to the main decoding function (found in “decoder.cpp”).
- Build & Deployment Process: Optionally, include a separate “Build Process” component that incorporates CMake, indicating how source files are compiled and linked into the final binary.

##### Architectural Patterns and Design Principles
- Modularity: Even though the project is small, separate the decoder’s logic from file handling. This will help clarify potential extension points (e.g., adding support for auto fetch albums or metadata fix).

##### Technology References and Tools
- C++: Mention that the core implementation uses C++.
- CMake: Note the use of CMake for building the project.
- 3rdparty/filesystem: Flag this library as a key dependency for filesystem operations.
- GitHub Workflows: Optionally indicate the CI/CD integration for automated builds and tests.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U("User/Terminal"):::user

    subgraph "Command-line Interface"
        CLI1("CLI (Executable)"):::cli
        CLI2("macOS CLI"):::cli
    end

    subgraph "Decoder Engine"
        DE1("Decoder Core"):::decoder
        DE2("Seed Definitions"):::decoder
    end

    FI("File I/O Handler"):::fileio
    QS("QMC Source Files"):::fileio
    OX("Converted Audio (MP3/FLAC)"):::fileio
    TP("Filesystem Library"):::thirdparty

    subgraph "Build & Deployment Process"
        B1("CMakeLists.txt"):::build
        B2(".clang-format"):::build
        B3("GitHub CI Workflow"):::build
    end

    U --> CLI1
    CLI1 --> DE1
    CLI1 --- CLI2
    DE1 <--> FI
    QS --> FI
    FI --> OX
    FI --> TP
    B1 -->|"builds"| CLI1
    B2 -->|"formats"| CLI1
    B3 -->|"CI"| CLI1

    click CLI1 "https://github.com/presburger/qmc-decoder/blob/master/src/decoder.cpp"
    click CLI2 "https://github.com/presburger/qmc-decoder/blob/master/decoder.command"
    click DE1 "https://github.com/presburger/qmc-decoder/blob/master/src/decoder.cpp"
    click DE2 "https://github.com/presburger/qmc-decoder/blob/master/src/seed.hpp"
    click TP "https://github.com/presburger/qmc-decoder/tree/master/3rdparty/filesystem"
    click B1 "https://github.com/presburger/qmc-decoder/blob/master/CMakeLists.txt"
    click B2 "https://github.com/presburger/qmc-decoder/blob/master/.clang-format"
    click B3 "https://github.com/presburger/qmc-decoder/blob/master/.github/workflows/build.yml"

    classDef user fill:#d9edf7,stroke:#31708f,stroke-width:2px;
    classDef cli fill:#dff0d8,stroke:#3c763d,stroke-width:2px;
    classDef decoder fill:#f2dede,stroke:#a94442,stroke-width:2px;
    classDef fileio fill:#fcf8e3,stroke:#8a6d3b,stroke-width:2px;
    classDef build fill:#d9d9f2,stroke:#6666cc,stroke-width:2px;
    classDef thirdparty fill:#f5e6cc,stroke:#cc6600,stroke-width:2px;
```
