# googolplexed0/zotify architecture

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

- Interactive diagram: https://gitdiagram.com/googolplexed0/zotify
- Repository: https://github.com/googolplexed0/zotify

## Overview

Zotify is a command-line music and podcast downloader. Its main workflow accepts URLs or an interactive mode, obtains account-backed metadata, resolves requested content into tracks or episodes, downloads and converts audio, then writes tagged files and library records. The README also documents search, account-library downloads, synced lyrics, bulk URL input, dry runs, and library verification. The excerpts establish the CLI, query, metadata, configuration, and tagging layers; some feature wiring is documented but not visible in the sampled source, so those links are omitted where uncertain.

Main entry points: [`zotify/api.py`](https://github.com/googolplexed0/zotify/blob/main/zotify/api.py) (Query resolution), [`zotify/app.py`](https://github.com/googolplexed0/zotify/blob/main/zotify/app.py) (Query workflows), [`zotify/__main__.py`](https://github.com/googolplexed0/zotify/blob/main/zotify/__main__.py) (CLI arguments), [`zotify/metadata.py`](https://github.com/googolplexed0/zotify/blob/main/zotify/metadata.py) (Audio tagging)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and workflows"]
  node_cli["CLI arguments<br/>[__main__.py]"]
  node_workflow["Query workflows<br/>[app.py]"]
  node_search["Interactive search<br/>[app.py]"]
  node_account_modes["Account modes<br/>[app.py]"]
  node_bulk_input["Bulk URL input<br/>[app.py]"]
  node_verify["Library verification<br/>[app.py]"]
end

subgraph group_domain["Catalog and retrieval"]
  node_query["Query resolution<br/>[api.py]"]
  node_content["Catalog content<br/>[api.py]"]
  node_stream["Audio retrieval<br/>[api.py]"]
  node_metadata["Metadata parsing<br/>[metadata.py]"]
end

subgraph group_output["Files and library"]
  node_tagger["Audio tagging<br/>[metadata.py]"]
  node_archive[("Song archives<br/>[metadata.py]")]
  node_lyrics["Lyrics output<br/>[api.py]"]
end

subgraph group_support["Runtime support"]
  node_config["Settings and login<br/>[config.py]"]
  node_printer["Terminal interface<br/>[termoutput.py]"]
  node_utils["Path and input utilities<br/>[utils.py]"]
end

node_user(("User"))
node_spotify["Spotify services"]
node_partner["Podcast partner API"]
node_library[("Music files")]
node_ffmpeg["FFmpeg"]

node_user -->|"supplies options"| node_cli
node_cli -->|"loads settings"| node_config
node_cli -->|"dispatches"| node_workflow
node_workflow -->|"executes requests"| node_query
node_workflow -->|"runs search"| node_search
node_search -->|"searches catalog"| node_spotify
node_search -->|"submits selections"| node_query
node_workflow -->|"runs modes"| node_account_modes
node_account_modes -->|"requests account items"| node_query
node_workflow -->|"reads URL lists"| node_bulk_input
node_bulk_input -->|"submits URLs"| node_query
node_workflow -->|"starts verification"| node_verify
node_verify -->|"checks archive entries"| node_archive
node_verify -->|"scans files"| node_library
node_query -->|"fetches metadata"| node_spotify
node_query -->|"resolves content"| node_content
node_content -->|"parses responses"| node_metadata
node_query -->|"downloads requested audio"| node_stream
node_stream -->|"retrieves audio"| node_spotify
node_stream -.->|"fetches episode audio"| node_partner
node_stream -->|"converts audio"| node_ffmpeg
node_stream -->|"writes tags"| node_tagger
node_tagger -->|"updates audio files"| node_library
node_tagger -->|"uses content metadata"| node_metadata
node_query -.->|"downloads lyrics"| node_lyrics
node_lyrics -.->|"writes lyric files"| node_library
node_query -->|"records downloads"| node_archive
node_config -->|"authenticates session"| node_spotify
node_workflow -->|"reports and prompts"| node_printer
node_config -->|"uses path helpers"| node_utils

click node_cli "https://github.com/googolplexed0/zotify/blob/main/zotify/__main__.py"
click node_workflow "https://github.com/googolplexed0/zotify/blob/main/zotify/app.py"
click node_search "https://github.com/googolplexed0/zotify/blob/main/zotify/app.py"
click node_account_modes "https://github.com/googolplexed0/zotify/blob/main/zotify/app.py"
click node_bulk_input "https://github.com/googolplexed0/zotify/blob/main/zotify/app.py"
click node_verify "https://github.com/googolplexed0/zotify/blob/main/zotify/app.py"
click node_query "https://github.com/googolplexed0/zotify/blob/main/zotify/api.py"
click node_content "https://github.com/googolplexed0/zotify/blob/main/zotify/api.py"
click node_stream "https://github.com/googolplexed0/zotify/blob/main/zotify/api.py"
click node_config "https://github.com/googolplexed0/zotify/blob/main/zotify/config.py"
click node_metadata "https://github.com/googolplexed0/zotify/blob/main/zotify/metadata.py"
click node_tagger "https://github.com/googolplexed0/zotify/blob/main/zotify/metadata.py"
click node_archive "https://github.com/googolplexed0/zotify/blob/main/zotify/metadata.py"
click node_lyrics "https://github.com/googolplexed0/zotify/blob/main/zotify/api.py"
click node_printer "https://github.com/googolplexed0/zotify/blob/main/zotify/termoutput.py"
click node_utils "https://github.com/googolplexed0/zotify/blob/main/zotify/utils.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_cli,node_workflow,node_search,node_account_modes,node_bulk_input,node_verify,node_user toneBlue
class node_query,node_content,node_stream,node_metadata,node_library toneAmber
class node_tagger,node_archive,node_lyrics,node_partner toneMint
class node_config,node_printer,node_utils toneRose
class node_spotify,node_ffmpeg toneIndigo
```

## Components

### CLI and workflows

- [CLI arguments](https://github.com/googolplexed0/zotify/blob/main/zotify/__main__.py): `zotify/__main__.py`
- [Query workflows](https://github.com/googolplexed0/zotify/blob/main/zotify/app.py): `zotify/app.py`
- [Interactive search](https://github.com/googolplexed0/zotify/blob/main/zotify/app.py): `zotify/app.py`
- [Account modes](https://github.com/googolplexed0/zotify/blob/main/zotify/app.py): `zotify/app.py`
- [Bulk URL input](https://github.com/googolplexed0/zotify/blob/main/zotify/app.py): `zotify/app.py`
- [Library verification](https://github.com/googolplexed0/zotify/blob/main/zotify/app.py): `zotify/app.py`

### Catalog and retrieval

- [Query resolution](https://github.com/googolplexed0/zotify/blob/main/zotify/api.py): `zotify/api.py`
- [Catalog content](https://github.com/googolplexed0/zotify/blob/main/zotify/api.py): `zotify/api.py`
- [Audio retrieval](https://github.com/googolplexed0/zotify/blob/main/zotify/api.py): `zotify/api.py`
- [Metadata parsing](https://github.com/googolplexed0/zotify/blob/main/zotify/metadata.py): `zotify/metadata.py`

### Files and library

- [Audio tagging](https://github.com/googolplexed0/zotify/blob/main/zotify/metadata.py): `zotify/metadata.py`
- [Song archives](https://github.com/googolplexed0/zotify/blob/main/zotify/metadata.py): `zotify/metadata.py`
- [Lyrics output](https://github.com/googolplexed0/zotify/blob/main/zotify/api.py): `zotify/api.py`

### Runtime support

- [Settings and login](https://github.com/googolplexed0/zotify/blob/main/zotify/config.py): `zotify/config.py`
- [Terminal interface](https://github.com/googolplexed0/zotify/blob/main/zotify/termoutput.py): `zotify/termoutput.py`
- [Path and input utilities](https://github.com/googolplexed0/zotify/blob/main/zotify/utils.py): `zotify/utils.py`

### Other components

- **User**
- **Spotify services**
- **Podcast partner API**
- **Music files**
- **FFmpeg**

## Connections

- User → CLI arguments: supplies options
- CLI arguments → Settings and login: loads settings
- CLI arguments → Query workflows: dispatches
- Query workflows → Query resolution: executes requests
- Query workflows → Interactive search: runs search
- Interactive search → Spotify services: searches catalog
- Interactive search → Query resolution: submits selections
- Query workflows → Account modes: runs modes
- Account modes → Query resolution: requests account items
- Query workflows → Bulk URL input: reads URL lists
- Bulk URL input → Query resolution: submits URLs
- Query workflows → Library verification: starts verification
- Library verification → Song archives: checks archive entries
- Library verification → Music files: scans files
- Query resolution → Spotify services: fetches metadata
- Query resolution → Catalog content: resolves content
- Catalog content → Metadata parsing: parses responses
- Query resolution → Audio retrieval: downloads requested audio
- Audio retrieval → Spotify services: retrieves audio
- Audio retrieval → Podcast partner API: fetches episode audio
- Audio retrieval → FFmpeg: converts audio
- Audio retrieval → Audio tagging: writes tags
- Audio tagging → Music files: updates audio files
- Audio tagging → Metadata parsing: uses content metadata
- Query resolution → Lyrics output: downloads lyrics
- Lyrics output → Music files: writes lyric files
- Query resolution → Song archives: records downloads
- Settings and login → Spotify services: authenticates session
- Query workflows → Terminal interface: reports and prompts
- Settings and login → Path and input utilities: uses path helpers