# catrilao/manga-tracker architecture

> Architecture diagram of the GitHub repository catrilao/manga-tracker, 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/catrilao/manga-tracker
- Repository: https://github.com/catrilao/manga-tracker

## Overview

MangaDex Tracker runs a batch sync: its CLI entrypoint loads configuration and infrastructure, selects active manga, fetches and parses chapters, validates a sync plan, stores new chapters, and notifies Discord. The service also records per-manga audit outcomes. The README documents cold-start notification suppression and anomaly checks, both represented in the planning stage. Edges follow the sampled entrypoint, controller, and service calls; unsampled internals are not inferred.

Main entry points: [`src/core/services.py`](https://github.com/catrilao/manga-tracker/blob/main/src/core/services.py) (Manga sync service), [`src/main.py`](https://github.com/catrilao/manga-tracker/blob/main/src/main.py) (Application entrypoint), [`src/infrastructure/database/postgres.py`](https://github.com/catrilao/manga-tracker/blob/main/src/infrastructure/database/postgres.py) (Postgres repository), [`src/core/controllers.py`](https://github.com/catrilao/manga-tracker/blob/main/src/core/controllers.py) (Batch controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application flow"]
  node_entry["Application entrypoint<br/>[main.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_controller["Batch controller<br/>[controllers.py]"]
  node_sync["Manga sync service<br/>[services.py]"]
  node_domain["Domain models<br/>[models.py]"]
end

subgraph group_scrape["Scraping and planning"]
  node_factory["Scraper factory<br/>[factory.py]"]
  node_plugin["MangaDex scraper<br/>[scraper.py]"]
  node_parser["Chapter parser<br/>[parser.py]"]
  node_planner["Sync planner<br/>[use_cases.py]"]
end

subgraph group_persistence["Persistence"]
  node_connection["DB connection<br/>[connection.py]"]
  node_repository["Postgres repository<br/>[postgres.py]"]
  node_schema["Database schema"]
end

subgraph group_notify["Notifications"]
  node_notifier["Discord notifier<br/>[discord.py]"]
end

node_operator(("CLI operator"))
node_postgres[("PostgreSQL")]
node_mangadex{{"MangaDex API"}}
node_discord{{"Discord webhook"}}

node_operator -->|"runs"| node_entry
node_entry -->|"loads"| node_config
node_entry -->|"opens"| node_connection
node_entry -->|"creates"| node_repository
node_entry -->|"creates"| node_factory
node_entry -->|"creates"| node_parser
node_entry -->|"creates"| node_notifier
node_entry -->|"creates"| node_sync
node_entry -->|"creates"| node_controller
node_entry -->|"runs"| node_controller
node_controller -->|"gets active IDs"| node_repository
node_controller -->|"syncs manga"| node_sync
node_plugin -->|"registers scraper"| node_factory
node_factory -->|"creates scraper"| node_plugin
node_sync -->|"loads manga"| node_repository
node_sync -->|"selects scraper"| node_factory
node_sync -->|"fetches chapters"| node_plugin
node_plugin -->|"requests chapter data"| node_mangadex
node_sync -->|"parses chapters"| node_parser
node_parser -->|"creates chapter models"| node_domain
node_sync -->|"loads metadata"| node_repository
node_sync -->|"calculates plan"| node_planner
node_planner -->|"returns sync plan"| node_domain
node_sync -->|"stores planned chapters"| node_repository
node_sync -->|"sends chapter notifications"| node_notifier
node_notifier -->|"posts webhook"| node_discord
node_sync -->|"marks notified"| node_repository
node_sync -->|"saves audit"| node_repository
node_connection -->|"connects"| node_postgres
node_repository -->|"queries and updates"| node_postgres
node_schema -.->|"defines schema"| node_postgres

click node_entry "https://github.com/catrilao/manga-tracker/blob/main/src/main.py"
click node_config "https://github.com/catrilao/manga-tracker/blob/main/src/config.py"
click node_controller "https://github.com/catrilao/manga-tracker/blob/main/src/core/controllers.py"
click node_sync "https://github.com/catrilao/manga-tracker/blob/main/src/core/services.py"
click node_domain "https://github.com/catrilao/manga-tracker/blob/main/src/domain/models.py"
click node_factory "https://github.com/catrilao/manga-tracker/blob/main/src/infrastructure/scrapers/factory.py"
click node_plugin "https://github.com/catrilao/manga-tracker/blob/main/src/infrastructure/scrapers/plugins/mangadex/scraper.py"
click node_parser "https://github.com/catrilao/manga-tracker/blob/main/src/infrastructure/scrapers/parser.py"
click node_planner "https://github.com/catrilao/manga-tracker/blob/main/src/core/use_cases.py"
click node_connection "https://github.com/catrilao/manga-tracker/blob/main/src/infrastructure/database/connection.py"
click node_repository "https://github.com/catrilao/manga-tracker/blob/main/src/infrastructure/database/postgres.py"
click node_schema "https://github.com/catrilao/manga-tracker/tree/main/supabase/migrations"
click node_notifier "https://github.com/catrilao/manga-tracker/blob/main/src/infrastructure/notifications/discord.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_entry,node_config,node_controller,node_sync,node_domain toneBlue
class node_factory,node_plugin,node_parser,node_planner,node_postgres toneAmber
class node_connection,node_repository,node_schema,node_mangadex,node_discord toneMint
class node_notifier toneRose
class node_operator toneIndigo
```

## Components

### Application flow

- [Application entrypoint](https://github.com/catrilao/manga-tracker/blob/main/src/main.py): `src/main.py`
- [Configuration](https://github.com/catrilao/manga-tracker/blob/main/src/config.py): `src/config.py`
- [Batch controller](https://github.com/catrilao/manga-tracker/blob/main/src/core/controllers.py): `src/core/controllers.py`
- [Manga sync service](https://github.com/catrilao/manga-tracker/blob/main/src/core/services.py): `src/core/services.py`
- [Domain models](https://github.com/catrilao/manga-tracker/blob/main/src/domain/models.py): `src/domain/models.py`

### Scraping and planning

- [Scraper factory](https://github.com/catrilao/manga-tracker/blob/main/src/infrastructure/scrapers/factory.py): `src/infrastructure/scrapers/factory.py`
- [MangaDex scraper](https://github.com/catrilao/manga-tracker/blob/main/src/infrastructure/scrapers/plugins/mangadex/scraper.py): `src/infrastructure/scrapers/plugins/mangadex/scraper.py`
- [Chapter parser](https://github.com/catrilao/manga-tracker/blob/main/src/infrastructure/scrapers/parser.py): `src/infrastructure/scrapers/parser.py`
- [Sync planner](https://github.com/catrilao/manga-tracker/blob/main/src/core/use_cases.py): `src/core/use_cases.py`

### Persistence

- [DB connection](https://github.com/catrilao/manga-tracker/blob/main/src/infrastructure/database/connection.py): `src/infrastructure/database/connection.py`
- [Postgres repository](https://github.com/catrilao/manga-tracker/blob/main/src/infrastructure/database/postgres.py): `src/infrastructure/database/postgres.py`
- [Database schema](https://github.com/catrilao/manga-tracker/tree/main/supabase/migrations): `supabase/migrations`

### Notifications

- [Discord notifier](https://github.com/catrilao/manga-tracker/blob/main/src/infrastructure/notifications/discord.py): `src/infrastructure/notifications/discord.py`

### Other components

- **CLI operator**
- **PostgreSQL**
- **MangaDex API**
- **Discord webhook**

## Connections

- CLI operator → Application entrypoint: runs
- Application entrypoint → Configuration: loads
- Application entrypoint → DB connection: opens
- Application entrypoint → Postgres repository: creates
- Application entrypoint → Scraper factory: creates
- Application entrypoint → Chapter parser: creates
- Application entrypoint → Discord notifier: creates
- Application entrypoint → Manga sync service: creates
- Application entrypoint → Batch controller: creates
- Application entrypoint → Batch controller: runs
- Batch controller → Postgres repository: gets active IDs
- Batch controller → Manga sync service: syncs manga
- MangaDex scraper → Scraper factory: registers scraper
- Scraper factory → MangaDex scraper: creates scraper
- Manga sync service → Postgres repository: loads manga
- Manga sync service → Scraper factory: selects scraper
- Manga sync service → MangaDex scraper: fetches chapters
- MangaDex scraper → MangaDex API: requests chapter data
- Manga sync service → Chapter parser: parses chapters
- Chapter parser → Domain models: creates chapter models
- Manga sync service → Postgres repository: loads metadata
- Manga sync service → Sync planner: calculates plan
- Sync planner → Domain models: returns sync plan
- Manga sync service → Postgres repository: stores planned chapters
- Manga sync service → Discord notifier: sends chapter notifications
- Discord notifier → Discord webhook: posts webhook
- Manga sync service → Postgres repository: marks notified
- Manga sync service → Postgres repository: saves audit
- DB connection → PostgreSQL: connects
- Postgres repository → PostgreSQL: queries and updates
- Database schema → PostgreSQL: defines schema