# chichichi959595/artist-tracker-for-obsidian architecture

> Architecture diagram of the GitHub repository chichichi959595/artist-tracker-for-obsidian, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chichichi959595/artist-tracker-for-obsidian
- Repository: https://github.com/chichichi959595/artist-tracker-for-obsidian

## Overview

1. **What this repo is**
   - A **Python CLI batch synchronizer** that pulls updates from two external sources—**Apple iTunes Search API** and **YouTube Data API**—then writes curated markdown files into an **Obsidian vault**.
   - It is not a web app or daemon; the architecture is a **run-to-completion job** executed by `src/main.py`.

2. **Top-level control flow**
   - `src/main.py` is the orchestration entry point.
   - It reads command-line flags like music-only / YouTube-only, loads configuration and environment, then runs the relevant sync pipelines.
   - The execution model is linear: **load config → fetch remote data → reconcile with local state → write markdown → update SQLite**.

3. **Configuration boundary**
   - `src/config_loader.py` reads the JSON config under `config/config.json` or a custom path.
   - `src/env_loader.py` reads `.env`, mainly for `YOUTUBE_API_KEY`.
   - Config defines the two tracked entity sets:
     - `music`: artist names and iTunes artist IDs
     - `youtube`: channel names and YouTube channel IDs
   - It also defines the Obsidian vault path, output folder, and behavior flags such as country list, minimum year, and Shorts/Live filtering.

4. **External service adapters**
   - `src/itunes.py` encapsulates calls to the **Apple iTunes Search API**.
   - `src/youtube.py` encapsulates calls to the **YouTube Data API**.
   - These modules form the outbound integration boundary; the rest of the app should treat them as data providers, not contain API-specific logic.

5. **Local persistence layer**
   - `src/database.py` manages a **SQLite** database used as the authoritative local record of already-seen music items.
   - The DB prevents duplicate inserts, stores pending/listened state, and supports restoration if Obsidian content is accidentally removed.
   - The repository includes `scripts/clear_music_db.py` as an operational reset tool for this persistence layer.

6. **Obsidian output layer**
   - `src/markdown_writer.py` is responsible for turning domain records into markdown for Obsidian.
   - `src/obsidian_sync.py` handles the file-level sync semantics against the vault path and output folder.
   - The output boundary is concrete:
     - `Music.md` is maintained as a table
     - `YouTube.md` is maintained as a checklist-style append-only log

7. **Music-specific domain rules**
   - `src/music_keys.py` appears to centralize music identity and normalization logic.
   - This is where the repo’s important deduplication rule lives: songs are compared after normalizing names so variants like singles, remasters, or featured suffixes do not create duplicates.
   - This module is a key architectural boundary because it separates **business identity** from raw API metadata.

8. **Music data flow**
   - For each configured artist, the app fetches recent tracks from iTunes, filtered by country and year/limit options.
   - New tracks are checked against SQLite before insertion.
   - The markdown table in `Music.md` is then reconciled with the database state:
     - rows marked complete in Obsidian are removed from the file and marked listened in SQLite
     - pending rows missing from Obsidian can be restored from SQLite if the artist is still configured

9. **YouTube data flow**
   - For each configured channel, the app fetches recent uploads from YouTube.
   - Optional filters remove **Shorts** and/or **Live** videos based on config.
   - The result is appended as unchecked checklist items in `YouTube.md`.
   - Unlike music, the YouTube flow is described as **append-oriented** and does not rely on the same restore/listened state machine.

10. **Storage layout and operational files**
   - The repository keeps `data/` and `logs/` directories in-tree with `.gitkeep` placeholders, indicating local runtime storage and logging are expected.
   - `config/config.example.json` and `.env.example` provide the bootstrap boundary for local installation.
   - This is a local-first tool: the important system-of-records are the SQLite DB and the Obsidian vault files.

11. **Runtime and dependency model**
   - The project explicitly uses **only Python standard library modules**.
   - That affects the architecture: no package manager, no third-party ORM, and no external sync framework.
   - The design is therefore modular but lightweight, with direct integration code in the `src/` adapters.

12. **Test boundaries**
   - The `tests/` directory covers the major subsystems separately:
     - database behavior
     - iTunes fetch logic
     - YouTube fetch logic
     - markdown writing
     - Obsidian sync
     - main orchestration
   - This mirrors the architecture: each adapter or workflow is isolated enough to test independently.

13. **What an architecture diagram should show**
   - A central CLI orchestrator feeding two pipelines:
     - **Music pipeline**: iTunes API → normalization/dedup → SQLite → markdown sync → Obsidian vault
     - **YouTube pipeline**: YouTube API → filtering → markdown append → Obsidian vault
   - Surrounding the pipelines are shared concerns:
     - config/env loading
     - logging
     - local file system / SQLite persistence
     - reset script for maintenance

Main entry points: [`src/main.py`](https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/src/main.py) (CLI main), [`src/database.py`](https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/src/database.py) (SQLite DB), [`src/markdown_writer.py`](https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/src/markdown_writer.py) (Markdown writer), [`src/obsidian_sync.py`](https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/src/obsidian_sync.py) (Vault sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_orchestration["Orchestration"]
  node_main["CLI main<br/>orchestrator<br/>[main.py]"]
  node_config_loader["Config loader<br/>[config_loader.py]"]
  node_env_loader["Env loader<br/>[env_loader.py]"]
end

subgraph group_grp_music["Music pipeline"]
  node_itunes["iTunes API<br/>adapter<br/>[itunes.py]"]
  node_music_keys["Music keys<br/>identity<br/>[music_keys.py]"]
end

subgraph group_grp_youtube["YouTube pipeline"]
  node_youtube["YouTube API<br/>adapter<br/>[youtube.py]"]
end

subgraph group_grp_storage["Storage"]
  node_database[("SQLite DB<br/>persistence<br/>[database.py]")]
  node_markdown_writer["Markdown writer<br/>renderer<br/>[markdown_writer.py]"]
  node_obsidian_sync["Vault sync<br/>file sync<br/>[obsidian_sync.py]"]
end

subgraph group_grp_ops["Operations"]
  node_clear_music_db["DB reset<br/>ops script<br/>[clear_music_db.py]"]
  node_config_example["Config example<br/>bootstrap file"]
  node_env_example["Env example<br/>bootstrap file<br/>[.env.example]"]
end

node_main -->|"loads"| node_config_loader
node_main -->|"loads"| node_env_loader
node_config_loader -.->|"guided by"| node_config_example
node_env_loader -.->|"guided by"| node_env_example
node_main -->|"music fetch"| node_itunes
node_main -->|"video fetch"| node_youtube
node_itunes -->|"raw tracks"| node_music_keys
node_music_keys -->|"dedup state"| node_database
node_main -->|"music persistence"| node_database
node_database -->|"records"| node_markdown_writer
node_main -->|"render"| node_markdown_writer
node_markdown_writer -->|"write files"| node_obsidian_sync
node_main -->|"sync vault"| node_obsidian_sync
node_youtube -->|"append output"| node_obsidian_sync
node_main -.->|"maintenance"| node_clear_music_db

click node_main "https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/src/main.py"
click node_config_loader "https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/src/config_loader.py"
click node_env_loader "https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/src/env_loader.py"
click node_itunes "https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/src/itunes.py"
click node_music_keys "https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/src/music_keys.py"
click node_database "https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/src/database.py"
click node_markdown_writer "https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/src/markdown_writer.py"
click node_obsidian_sync "https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/src/obsidian_sync.py"
click node_youtube "https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/src/youtube.py"
click node_clear_music_db "https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/scripts/clear_music_db.py"
click node_config_example "https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/config/config.example.json"
click node_env_example "https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/.env.example"

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_main,node_config_loader,node_env_loader toneBlue
class node_itunes,node_music_keys toneAmber
class node_youtube toneMint
class node_database,node_markdown_writer,node_obsidian_sync toneRose
class node_clear_music_db,node_config_example,node_env_example toneIndigo
```

## Components

### Orchestration

CLI entrypoint and shared runtime setup

- [CLI main](https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/src/main.py): orchestrator · Run-to-completion entrypoint that loads config and dispatches sync pipelines · `src/main.py`
- [Config loader](https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/src/config_loader.py): config · Loads JSON configuration for tracked artists, channels, and vault settings · `src/config_loader.py`
- [Env loader](https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/src/env_loader.py): env · Loads environment variables such as the YouTube API key · `src/env_loader.py`

### Music pipeline

Fetch, normalize, deduplicate, and sync music updates

- [iTunes API](https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/src/itunes.py): adapter · Apple iTunes Search API client for music fetches · `src/itunes.py`
- [Music keys](https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/src/music_keys.py): identity · Normalizes music identity for deduplication and variant matching · `src/music_keys.py`

### YouTube pipeline

Fetch, filter, and append channel uploads

- [YouTube API](https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/src/youtube.py): adapter · YouTube Data API client for recent uploads · `src/youtube.py`

### Storage

Local persistence and vault output

- [SQLite DB](https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/src/database.py): persistence · Local record of seen music items and listened state · `src/database.py`
- [Markdown writer](https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/src/markdown_writer.py): renderer · Turns domain records into Obsidian markdown content · `src/markdown_writer.py`
- [Vault sync](https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/src/obsidian_sync.py): file sync · Reconciles generated content with the Obsidian vault and output files · `src/obsidian_sync.py`

### Operations

Maintenance and bootstrap files

- [DB reset](https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/scripts/clear_music_db.py): ops script · Operational script for clearing the music SQLite database · `scripts/clear_music_db.py`
- [Config example](https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/config/config.example.json): bootstrap file · Example JSON config used to initialize local setup · `config/config.example.json`
- [Env example](https://github.com/chichichi959595/artist-tracker-for-obsidian/blob/main/.env.example): bootstrap file · Example environment file for local secrets and API keys · `.env.example`

## Connections

- CLI main → Config loader: loads · Reads repository and vault configuration before syncing
- CLI main → Env loader: loads · Loads runtime secrets and API credentials
- Config loader → Config example: guided by · Bootstrap configuration template
- Env loader → Env example: guided by · Bootstrap environment template
- CLI main → iTunes API: music fetch · Invokes iTunes retrieval when music sync is enabled
- CLI main → YouTube API: video fetch · Invokes YouTube retrieval when YouTube sync is enabled
- iTunes API → Music keys: raw tracks · Music results are normalized before deduplication
- Music keys → SQLite DB: dedup state · Normalized identity is checked against local records
- CLI main → SQLite DB: music persistence · Stores new items and updates listened state
- SQLite DB → Markdown writer: records · Provides authoritative music rows for markdown rendering
- CLI main → Markdown writer: render · Generates Obsidian markdown for music output
- Markdown writer → Vault sync: write files · Produces file content for vault reconciliation
- CLI main → Vault sync: sync vault · Applies file-level sync semantics to Obsidian outputs
- YouTube API → Vault sync: append output · Feeds checklist-style additions into the vault sync layer
- CLI main → DB reset: maintenance · Separate operational reset path for the SQLite database
