# bartolomeorusso9/spotiflac-module-version architecture

> Architecture diagram of the GitHub repository bartolomeorusso9/spotiflac-module-version, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bartolomeorusso9/spotiflac-module-version
- Repository: https://github.com/bartolomeorusso9/spotiflac-module-version

## Overview

SpotiFLAC is an embeddable Python music-metadata and lossless-download module, with optional GUI, web API, and terminal UI. A typical request resolves Spotify URLs to track metadata, selects an installed extension provider, retrieves audio, and applies configured post-processing before saving the result. The README also documents independent features such as library management, subscriptions, statistics, and authenticated multi-user web access. The graph uses documented capabilities and SOURCE INDEX references; unsampled subsystems are represented conservatively, and their internal wiring is not inferred.

Main entry points: [`SpotiFLAC/application/download_service.py`](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/application/download_service.py) (Download service), [`SpotiFLAC/webapi/routes.py`](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/webapi/routes.py) (REST API), [`SpotiFLAC/application/pipeline.py`](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/application/pipeline.py) (Download pipeline), [`SpotiFLAC/extensions/provider.py`](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/extensions/provider.py) (Extension provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_client["Python API<br/>[client.py]"]
  node_desktop["GUI app<br/>[app.py]"]
  node_tui["Terminal UI<br/>[app.py]"]
end

subgraph group_download["Download workflow"]
  node_metadata["Spotify metadata"]
  node_download_service["Download service"]
  node_pipeline["Download pipeline<br/>[pipeline.py]"]
  node_download_engine["Download engine<br/>[download_engine.py]"]
  node_config["Configuration<br/>[__init__.py]"]
  node_tagging["Tagging and lyrics<br/>[tagger.py]"]
  node_transcode["Audio transcoding<br/>[transcode.py]"]
end

subgraph group_extensions["Providers and extensions"]
  node_provider_manager["Extension manager<br/>[manager.py]"]
  node_provider["Extension provider<br/>[provider.py]"]
  node_registry["Registry settings<br/>[registry_config.py]"]
end

subgraph group_library["Library features"]
  node_library_dedup["Library deduplication<br/>[library_dedup.py]"]
  node_subscriptions["Artist subscriptions<br/>[subscriptions.py]"]
  node_library_upgrade["Library upgrade<br/>[library_upgrade.py]"]
end

subgraph group_platform["Web and persistence"]
  node_webapi["REST API<br/>[routes.py]"]
  node_job_queue[("Durable job queue<br/>[job_queue.py]")]
  node_download_log[("Download log<br/>[download_log.py]")]
  node_stats["Download statistics<br/>[stats.py]"]
  node_notifications["Outbound notifications<br/>[notifiers.py]"]
end

node_user(("Integrating user"))
node_services{{"Music services"}}

node_user -->|"calls API"| node_client
node_user -->|"uses GUI"| node_desktop
node_user -->|"uses TUI"| node_tui
node_user -->|"calls API"| node_webapi
node_client -->|"submits downloads"| node_download_service
node_client -->|"resolves tracks"| node_metadata
node_download_service -->|"runs pipeline"| node_pipeline
node_download_service -->|"resolves metadata"| node_metadata
node_download_service -->|"tries candidates"| node_provider
node_pipeline -->|"resolves candidates"| node_provider
node_download_service -->|"adapts legacy downloads"| node_download_engine
node_download_service -->|"uses settings"| node_config
node_provider_manager -->|"loads settings"| node_registry
node_provider_manager -.->|"sets up providers"| node_provider
node_provider -->|"fetches audio"| node_services
node_pipeline -.->|"tags and writes lyrics"| node_tagging
node_pipeline -.->|"transcodes audio"| node_transcode
node_user -->|"checks library"| node_library_dedup
node_user -->|"follows artists"| node_subscriptions
node_user -->|"upgrades files"| node_library_upgrade
node_webapi -->|"resolves URLs"| node_metadata
node_webapi -->|"queues work"| node_job_queue
node_webapi -->|"reads download log"| node_download_log
node_webapi -->|"reads statistics"| node_stats
node_user -->|"configures alerts"| node_notifications

click node_client "https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/client.py"
click node_desktop "https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/app.py"
click node_tui "https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/tui/app.py"
click node_webapi "https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/webapi/routes.py"
click node_metadata "https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/core/spotify_metadata.py"
click node_download_service "https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/application/download_service.py"
click node_pipeline "https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/application/pipeline.py"
click node_download_engine "https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/application/download_engine.py"
click node_provider_manager "https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/extensions/manager.py"
click node_provider "https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/extensions/provider.py"
click node_registry "https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/extensions/registry_config.py"
click node_config "https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/core/config/__init__.py"
click node_tagging "https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/core/tagger.py"
click node_transcode "https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/core/transcode.py"
click node_library_dedup "https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/core/library_dedup.py"
click node_subscriptions "https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/core/subscriptions.py"
click node_library_upgrade "https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/core/library_upgrade.py"
click node_job_queue "https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/core/job_queue.py"
click node_download_log "https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/core/download_log.py"
click node_stats "https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/core/stats.py"
click node_notifications "https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/core/notifiers.py"

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_client,node_desktop,node_tui,node_user toneBlue
class node_metadata,node_download_service,node_pipeline,node_download_engine,node_config,node_tagging,node_transcode toneAmber
class node_provider_manager,node_provider,node_registry toneMint
class node_library_dedup,node_subscriptions,node_library_upgrade toneRose
class node_webapi,node_job_queue,node_download_log,node_stats,node_notifications,node_services toneIndigo
```

## Components

### User interfaces

- [Python API](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/client.py): `SpotiFLAC/client.py`
- [GUI app](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/app.py): `SpotiFLAC/app.py`
- [Terminal UI](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/tui/app.py): `SpotiFLAC/tui/app.py`

### Download workflow

- [Spotify metadata](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/core/spotify_metadata.py): `SpotiFLAC/core/spotify_metadata.py`
- [Download service](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/application/download_service.py): `SpotiFLAC/application/download_service.py`
- [Download pipeline](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/application/pipeline.py): `SpotiFLAC/application/pipeline.py`
- [Download engine](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/application/download_engine.py): `SpotiFLAC/application/download_engine.py`
- [Configuration](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/core/config/__init__.py): `SpotiFLAC/core/config/__init__.py`
- [Tagging and lyrics](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/core/tagger.py): `SpotiFLAC/core/tagger.py`
- [Audio transcoding](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/core/transcode.py): `SpotiFLAC/core/transcode.py`

### Providers and extensions

- [Extension manager](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/extensions/manager.py): `SpotiFLAC/extensions/manager.py`
- [Extension provider](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/extensions/provider.py): `SpotiFLAC/extensions/provider.py`
- [Registry settings](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/extensions/registry_config.py): `SpotiFLAC/extensions/registry_config.py`

### Library features

- [Library deduplication](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/core/library_dedup.py): `SpotiFLAC/core/library_dedup.py`
- [Artist subscriptions](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/core/subscriptions.py): `SpotiFLAC/core/subscriptions.py`
- [Library upgrade](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/core/library_upgrade.py): `SpotiFLAC/core/library_upgrade.py`

### Web and persistence

- [REST API](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/webapi/routes.py): `SpotiFLAC/webapi/routes.py`
- [Durable job queue](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/core/job_queue.py): `SpotiFLAC/core/job_queue.py`
- [Download log](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/core/download_log.py): `SpotiFLAC/core/download_log.py`
- [Download statistics](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/core/stats.py): `SpotiFLAC/core/stats.py`
- [Outbound notifications](https://github.com/bartolomeorusso9/spotiflac-module-version/blob/main/SpotiFLAC/core/notifiers.py): `SpotiFLAC/core/notifiers.py`

### Other components

- **Integrating user**
- **Music services**

## Connections

- Integrating user → Python API: calls API
- Integrating user → GUI app: uses GUI
- Integrating user → Terminal UI: uses TUI
- Integrating user → REST API: calls API
- Python API → Download service: submits downloads (evidence: `SpotiFLAC/client.py`)
- Python API → Spotify metadata: resolves tracks (evidence: `SpotiFLAC/client.py`)
- Download service → Download pipeline: runs pipeline (evidence: `SpotiFLAC/application/download_service.py`)
- Download service → Spotify metadata: resolves metadata (evidence: `SpotiFLAC/application/download_service.py`)
- Download service → Extension provider: tries candidates (evidence: `SpotiFLAC/application/download_service.py`)
- Download pipeline → Extension provider: resolves candidates (evidence: `SpotiFLAC/application/pipeline.py`)
- Download service → Download engine: adapts legacy downloads (evidence: `SpotiFLAC/application/download_service.py`)
- Download service → Configuration: uses settings (evidence: `SpotiFLAC/application/download_service.py`)
- Extension manager → Registry settings: loads settings (evidence: `SpotiFLAC/extensions/manager.py`)
- Extension manager → Extension provider: sets up providers (evidence: `SpotiFLAC/extensions/provider.py`)
- Extension provider → Music services: fetches audio
- Download pipeline → Tagging and lyrics: tags and writes lyrics
- Download pipeline → Audio transcoding: transcodes audio
- Integrating user → Library deduplication: checks library
- Integrating user → Artist subscriptions: follows artists
- Integrating user → Library upgrade: upgrades files
- REST API → Spotify metadata: resolves URLs (evidence: `SpotiFLAC/webapi/routes.py`)
- REST API → Durable job queue: queues work (evidence: `SpotiFLAC/webapi/routes.py`)
- REST API → Download log: reads download log (evidence: `SpotiFLAC/webapi/routes.py`)
- REST API → Download statistics: reads statistics (evidence: `SpotiFLAC/webapi/routes.py`)
- Integrating user → Outbound notifications: configures alerts
