# oskvr37/tiddl architecture

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

- Interactive diagram: https://gitdiagram.com/oskvr37/tiddl
- Repository: https://github.com/oskvr37/tiddl

## Overview

Tiddl is a command-line Tidal client for authenticating, finding catalog resources, and downloading tracks, videos, and collections. The main workflow is: select resources by URL or search, retrieve their metadata, expand collections into items, download media, then name files and optionally write metadata, covers, lyrics, and playlists. Authentication is a separate login/refresh/logout flow that stores credentials locally. The graph reflects documented capabilities and sampled call sites; some command registration and downloader internals were not included, so uncertain wiring is omitted.

Main entry points: [`tiddl/cli/commands/download/__init__.py`](https://github.com/oskvr37/tiddl/blob/main/tiddl/cli/commands/download/__init__.py) (Download command), [`tiddl/cli/commands/download/downloader.py`](https://github.com/oskvr37/tiddl/blob/main/tiddl/cli/commands/download/downloader.py) (Media downloader), [`tiddl/cli/commands/auth.py`](https://github.com/oskvr37/tiddl/blob/main/tiddl/cli/commands/auth.py) (Auth commands), [`tiddl/cli/commands/subcommands/search.py`](https://github.com/oskvr37/tiddl/blob/main/tiddl/cli/commands/subcommands/search.py) (Catalog search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and selection"]
  node_app["CLI app<br/>[app.py]"]
  node_search["Catalog search<br/>[search.py]"]
  node_resource["Resource parsing<br/>[resource.py]"]
end

subgraph group_auth["Authentication"]
  node_auth_commands["Auth commands<br/>[auth.py]"]
  node_auth_storage["Credential storage<br/>[core.py]"]
  node_auth_api["Auth API<br/>[api.py]"]
  node_auth_client["Auth client<br/>[client.py]"]
end

subgraph group_catalog["Tidal catalog"]
  node_api_facade["Catalog API<br/>[api.py]"]
  node_api_client["API client<br/>[client.py]"]
end

subgraph group_media["Download and output"]
  node_download_command["Download command<br/>[__init__.py]"]
  node_downloader["Media downloader<br/>[downloader.py]"]
  node_template["Path templates<br/>[format.py]"]
  node_download_utils["Download utilities<br/>[download.py]"]
  node_metadata["Track metadata<br/>[track.py]"]
  node_video_metadata["Video metadata<br/>[video.py]"]
  node_cover["Cover handling<br/>[cover.py]"]
  node_m3u["Playlist export<br/>[m3u.py]"]
  node_output["Download reporting<br/>[output.py]"]
end

node_user(("CLI user"))
node_tidal_auth{{"Tidal auth service"}}
node_tidal_api{{"Tidal catalog API"}}
node_media_service{{"Tidal media service"}}
node_filesystem["Local files"]

node_user -->|"runs"| node_app
node_user -->|"requests login"| node_auth_commands
node_auth_commands -->|"loads and saves"| node_auth_storage
node_auth_commands -->|"requests auth"| node_auth_api
node_auth_api -->|"delegates requests"| node_auth_client
node_auth_client -->|"requests tokens"| node_tidal_auth
node_user -->|"submits query"| node_search
node_search -->|"searches catalog"| node_api_facade
node_search -->|"adds selection"| node_resource
node_user -->|"provides URL"| node_resource
node_resource -->|"provides resource"| node_download_command
node_user -->|"starts download"| node_download_command
node_download_command -->|"refreshes token"| node_auth_commands
node_download_command -->|"retrieves resource data"| node_api_facade
node_api_facade -->|"fetches endpoints"| node_api_client
node_api_client -->|"requests catalog data"| node_tidal_api
node_download_command -->|"formats output paths"| node_template
node_download_command -->|"downloads items"| node_downloader
node_downloader -->|"fetches media"| node_media_service
node_downloader -->|"uses download helpers"| node_download_utils
node_downloader -->|"writes media"| node_filesystem
node_download_command -->|"tags tracks"| node_metadata
node_download_command -->|"tags videos"| node_video_metadata
node_download_command -->|"fetches cover data"| node_cover
node_cover -->|"saves cover"| node_filesystem
node_download_command -->|"writes playlists"| node_m3u
node_m3u -->|"writes playlist files"| node_filesystem
node_metadata -->|"updates media tags"| node_filesystem
node_video_metadata -->|"updates video tags"| node_filesystem
node_download_command -->|"reports progress"| node_output

click node_app "https://github.com/oskvr37/tiddl/blob/main/tiddl/cli/app.py"
click node_auth_commands "https://github.com/oskvr37/tiddl/blob/main/tiddl/cli/commands/auth.py"
click node_auth_storage "https://github.com/oskvr37/tiddl/blob/main/tiddl/cli/utils/auth/core.py"
click node_auth_api "https://github.com/oskvr37/tiddl/blob/main/tiddl/core/auth/api.py"
click node_auth_client "https://github.com/oskvr37/tiddl/blob/main/tiddl/core/auth/client.py"
click node_search "https://github.com/oskvr37/tiddl/blob/main/tiddl/cli/commands/subcommands/search.py"
click node_resource "https://github.com/oskvr37/tiddl/blob/main/tiddl/cli/utils/resource.py"
click node_download_command "https://github.com/oskvr37/tiddl/blob/main/tiddl/cli/commands/download/__init__.py"
click node_api_facade "https://github.com/oskvr37/tiddl/blob/main/tiddl/core/api/api.py"
click node_api_client "https://github.com/oskvr37/tiddl/blob/main/tiddl/core/api/client.py"
click node_downloader "https://github.com/oskvr37/tiddl/blob/main/tiddl/cli/commands/download/downloader.py"
click node_template "https://github.com/oskvr37/tiddl/blob/main/tiddl/core/utils/format.py"
click node_download_utils "https://github.com/oskvr37/tiddl/blob/main/tiddl/core/utils/download.py"
click node_metadata "https://github.com/oskvr37/tiddl/blob/main/tiddl/core/metadata/track.py"
click node_video_metadata "https://github.com/oskvr37/tiddl/blob/main/tiddl/core/metadata/video.py"
click node_cover "https://github.com/oskvr37/tiddl/blob/main/tiddl/core/metadata/cover.py"
click node_m3u "https://github.com/oskvr37/tiddl/blob/main/tiddl/core/utils/m3u.py"
click node_output "https://github.com/oskvr37/tiddl/blob/main/tiddl/cli/commands/download/output.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_app,node_search,node_resource,node_user toneBlue
class node_auth_commands,node_auth_storage,node_auth_api,node_auth_client toneAmber
class node_api_facade,node_api_client,node_tidal_api toneMint
class node_download_command,node_downloader,node_template,node_download_utils,node_metadata,node_video_metadata,node_cover,node_m3u,node_output toneRose
class node_tidal_auth,node_media_service,node_filesystem toneIndigo
```

## Components

### CLI and selection

- [CLI app](https://github.com/oskvr37/tiddl/blob/main/tiddl/cli/app.py): `tiddl/cli/app.py`
- [Catalog search](https://github.com/oskvr37/tiddl/blob/main/tiddl/cli/commands/subcommands/search.py): `tiddl/cli/commands/subcommands/search.py`
- [Resource parsing](https://github.com/oskvr37/tiddl/blob/main/tiddl/cli/utils/resource.py): `tiddl/cli/utils/resource.py`

### Authentication

- [Auth commands](https://github.com/oskvr37/tiddl/blob/main/tiddl/cli/commands/auth.py): `tiddl/cli/commands/auth.py`
- [Credential storage](https://github.com/oskvr37/tiddl/blob/main/tiddl/cli/utils/auth/core.py): `tiddl/cli/utils/auth/core.py`
- [Auth API](https://github.com/oskvr37/tiddl/blob/main/tiddl/core/auth/api.py): `tiddl/core/auth/api.py`
- [Auth client](https://github.com/oskvr37/tiddl/blob/main/tiddl/core/auth/client.py): `tiddl/core/auth/client.py`

### Tidal catalog

- [Catalog API](https://github.com/oskvr37/tiddl/blob/main/tiddl/core/api/api.py): `tiddl/core/api/api.py`
- [API client](https://github.com/oskvr37/tiddl/blob/main/tiddl/core/api/client.py): `tiddl/core/api/client.py`

### Download and output

- [Download command](https://github.com/oskvr37/tiddl/blob/main/tiddl/cli/commands/download/__init__.py): `tiddl/cli/commands/download/__init__.py`
- [Media downloader](https://github.com/oskvr37/tiddl/blob/main/tiddl/cli/commands/download/downloader.py): `tiddl/cli/commands/download/downloader.py`
- [Path templates](https://github.com/oskvr37/tiddl/blob/main/tiddl/core/utils/format.py): `tiddl/core/utils/format.py`
- [Download utilities](https://github.com/oskvr37/tiddl/blob/main/tiddl/core/utils/download.py): `tiddl/core/utils/download.py`
- [Track metadata](https://github.com/oskvr37/tiddl/blob/main/tiddl/core/metadata/track.py): `tiddl/core/metadata/track.py`
- [Video metadata](https://github.com/oskvr37/tiddl/blob/main/tiddl/core/metadata/video.py): `tiddl/core/metadata/video.py`
- [Cover handling](https://github.com/oskvr37/tiddl/blob/main/tiddl/core/metadata/cover.py): `tiddl/core/metadata/cover.py`
- [Playlist export](https://github.com/oskvr37/tiddl/blob/main/tiddl/core/utils/m3u.py): `tiddl/core/utils/m3u.py`
- [Download reporting](https://github.com/oskvr37/tiddl/blob/main/tiddl/cli/commands/download/output.py): `tiddl/cli/commands/download/output.py`

### Other components

- **CLI user**
- **Tidal auth service**
- **Tidal catalog API**
- **Tidal media service**
- **Local files**

## Connections

- CLI user → CLI app: runs
- CLI user → Auth commands: requests login
- Auth commands → Credential storage: loads and saves
- Auth commands → Auth API: requests auth
- Auth API → Auth client: delegates requests
- Auth client → Tidal auth service: requests tokens
- CLI user → Catalog search: submits query
- Catalog search → Catalog API: searches catalog
- Catalog search → Resource parsing: adds selection
- CLI user → Resource parsing: provides URL
- Resource parsing → Download command: provides resource
- CLI user → Download command: starts download
- Download command → Auth commands: refreshes token
- Download command → Catalog API: retrieves resource data
- Catalog API → API client: fetches endpoints
- API client → Tidal catalog API: requests catalog data
- Download command → Path templates: formats output paths
- Download command → Media downloader: downloads items
- Media downloader → Tidal media service: fetches media
- Media downloader → Download utilities: uses download helpers
- Media downloader → Local files: writes media
- Download command → Track metadata: tags tracks
- Download command → Video metadata: tags videos
- Download command → Cover handling: fetches cover data
- Cover handling → Local files: saves cover
- Download command → Playlist export: writes playlists
- Playlist export → Local files: writes playlist files
- Track metadata → Local files: updates media tags
- Video metadata → Local files: updates video tags
- Download command → Download reporting: reports progress