# g0ldyy/comet architecture

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

- Interactive diagram: https://gitdiagram.com/g0ldyy/comet
- Repository: https://github.com/g0ldyy/comet

## Overview

Comet is a Stremio torrent-discovery addon, with Kodi and Torznab interfaces and an optional decentralized metadata network. Its main user flow is a client request handled by the API, which exposes stream and search capabilities; the repository evidence shows supporting metadata, scraper, persistence, and streaming components, but not the full request-to-result calls between them. Separate branches cover scheduled scraping, CometNet, debrid integrations, and operational features. Edges are limited to README statements and relationships visible in the supplied source index or excerpts; unsampled endpoint internals are not inferred.

Main entry points: [`comet/api/app.py`](https://github.com/g0ldyy/comet/blob/main/comet/api/app.py) (HTTP application), [`comet/background_scraper/worker.py`](https://github.com/g0ldyy/comet/blob/main/comet/background_scraper/worker.py) (Background scraper), [`comet/metadata/manager.py`](https://github.com/g0ldyy/comet/blob/main/comet/metadata/manager.py) (Metadata resolution), [`comet/services/media_search.py`](https://github.com/g0ldyy/comet/blob/main/comet/services/media_search.py) (Media search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Client interfaces"]
  node_api_app["HTTP application<br/>[app.py]"]
  node_api_routes["API endpoints"]
  node_kodi_addon["Kodi addon<br/>[plugin.video.comet]"]
  node_torznab["Torznab interface<br/>[torznab.py]"]
end

subgraph group_discovery["Discovery and delivery"]
  node_search["Media search<br/>[media_search.py]"]
  node_scraper_manager["Scraper manager<br/>[manager.py]"]
  node_scraper_adapters["Scraper adapters"]
  node_metadata["Metadata resolution<br/>[manager.py]"]
  node_torrent_manager["Torrent management<br/>[torrent_manager.py]"]
  node_debrid["Debrid services"]
  node_streaming["Stream delivery<br/>[manager.py]"]
  node_background["Background scraper<br/>[worker.py]"]
end

subgraph group_state["State and operations"]
  node_database[("Database<br/>[database.py]")]
  node_metrics["Prometheus metrics<br/>[metrics.py]"]
end

subgraph group_network["Federation"]
  node_cometnet["CometNet manager<br/>[manager.py]"]
  node_cometnet_protocol["P2P protocol<br/>[protocol.py]"]
end

node_stremio(("Stremio client"))
node_kodi_user(("Kodi user"))
node_torznab_client(("Indexer clients"))

node_stremio -->|"requests addon"| node_api_app
node_kodi_user -->|"uses addon"| node_kodi_addon
node_torznab_client -->|"queries index"| node_torznab
node_api_app -->|"registers routes"| node_api_routes
node_api_app -->|"starts worker"| node_background
node_api_app -->|"records requests"| node_metrics
node_torznab -->|"uses search"| node_search
node_search -.->|"invokes scrapers"| node_scraper_manager
node_scraper_manager -->|"dispatches scraping"| node_scraper_adapters
node_scraper_manager -->|"uses anime data"| node_metadata
node_metadata -->|"reads and caches"| node_database
node_metadata -.->|"resolves metadata"| node_search
node_torrent_manager -->|"persists torrents"| node_database
node_torrent_manager -->|"uses protocol"| node_cometnet_protocol
node_streaming -.->|"uses torrent data"| node_torrent_manager
node_streaming -.->|"proxies debrid streams"| node_debrid
node_background -->|"updates scrape state"| node_database
node_background -->|"requests metadata"| node_metadata
node_background -->|"orchestrates scraping"| node_search
node_cometnet -->|"coordinates protocol"| node_cometnet_protocol

click node_api_app "https://github.com/g0ldyy/comet/blob/main/comet/api/app.py"
click node_api_routes "https://github.com/g0ldyy/comet/tree/main/comet/api/endpoints"
click node_kodi_addon "https://github.com/g0ldyy/comet/tree/main/kodi/plugin.video.comet"
click node_torznab "https://github.com/g0ldyy/comet/blob/main/comet/api/endpoints/torznab.py"
click node_search "https://github.com/g0ldyy/comet/blob/main/comet/services/media_search.py"
click node_scraper_manager "https://github.com/g0ldyy/comet/blob/main/comet/scrapers/manager.py"
click node_scraper_adapters "https://github.com/g0ldyy/comet/tree/main/comet/scrapers"
click node_metadata "https://github.com/g0ldyy/comet/blob/main/comet/metadata/manager.py"
click node_torrent_manager "https://github.com/g0ldyy/comet/blob/main/comet/services/torrent_manager.py"
click node_debrid "https://github.com/g0ldyy/comet/tree/main/comet/debrid"
click node_streaming "https://github.com/g0ldyy/comet/blob/main/comet/services/streaming/manager.py"
click node_background "https://github.com/g0ldyy/comet/blob/main/comet/background_scraper/worker.py"
click node_database "https://github.com/g0ldyy/comet/blob/main/comet/core/database.py"
click node_metrics "https://github.com/g0ldyy/comet/blob/main/comet/observability/metrics.py"
click node_cometnet "https://github.com/g0ldyy/comet/blob/main/comet/cometnet/manager.py"
click node_cometnet_protocol "https://github.com/g0ldyy/comet/blob/main/comet/cometnet/protocol.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_api_app,node_api_routes,node_kodi_addon,node_torznab,node_stremio,node_kodi_user,node_torznab_client toneBlue
class node_search,node_scraper_manager,node_scraper_adapters,node_metadata,node_torrent_manager,node_debrid,node_streaming,node_background toneAmber
class node_database,node_metrics toneMint
class node_cometnet,node_cometnet_protocol toneRose
```

## Components

### Client interfaces

- [HTTP application](https://github.com/g0ldyy/comet/blob/main/comet/api/app.py): `comet/api/app.py`
- [API endpoints](https://github.com/g0ldyy/comet/tree/main/comet/api/endpoints): `comet/api/endpoints`
- [Kodi addon](https://github.com/g0ldyy/comet/tree/main/kodi/plugin.video.comet): `kodi/plugin.video.comet`
- [Torznab interface](https://github.com/g0ldyy/comet/blob/main/comet/api/endpoints/torznab.py): `comet/api/endpoints/torznab.py`

### Discovery and delivery

- [Media search](https://github.com/g0ldyy/comet/blob/main/comet/services/media_search.py): `comet/services/media_search.py`
- [Scraper manager](https://github.com/g0ldyy/comet/blob/main/comet/scrapers/manager.py): `comet/scrapers/manager.py`
- [Scraper adapters](https://github.com/g0ldyy/comet/tree/main/comet/scrapers): `comet/scrapers`
- [Metadata resolution](https://github.com/g0ldyy/comet/blob/main/comet/metadata/manager.py): `comet/metadata/manager.py`
- [Torrent management](https://github.com/g0ldyy/comet/blob/main/comet/services/torrent_manager.py): `comet/services/torrent_manager.py`
- [Debrid services](https://github.com/g0ldyy/comet/tree/main/comet/debrid): `comet/debrid`
- [Stream delivery](https://github.com/g0ldyy/comet/blob/main/comet/services/streaming/manager.py): `comet/services/streaming/manager.py`
- [Background scraper](https://github.com/g0ldyy/comet/blob/main/comet/background_scraper/worker.py): `comet/background_scraper/worker.py`

### State and operations

- [Database](https://github.com/g0ldyy/comet/blob/main/comet/core/database.py): `comet/core/database.py`
- [Prometheus metrics](https://github.com/g0ldyy/comet/blob/main/comet/observability/metrics.py): `comet/observability/metrics.py`

### Federation

- [CometNet manager](https://github.com/g0ldyy/comet/blob/main/comet/cometnet/manager.py): `comet/cometnet/manager.py`
- [P2P protocol](https://github.com/g0ldyy/comet/blob/main/comet/cometnet/protocol.py): `comet/cometnet/protocol.py`

### Other components

- **Stremio client**
- **Kodi user**
- **Indexer clients**

## Connections

- Stremio client → HTTP application: requests addon (evidence: `README.md`)
- Kodi user → Kodi addon: uses addon (evidence: `README.md`)
- Indexer clients → Torznab interface: queries index (evidence: `README.md`)
- HTTP application → API endpoints: registers routes (evidence: `comet/api/app.py`)
- HTTP application → Background scraper: starts worker (evidence: `comet/api/app.py`)
- HTTP application → Prometheus metrics: records requests (evidence: `comet/api/app.py`)
- Torznab interface → Media search: uses search (evidence: `comet/api/endpoints/torznab.py`)
- Media search → Scraper manager: invokes scrapers
- Scraper manager → Scraper adapters: dispatches scraping (evidence: `comet/scrapers/manager.py`)
- Scraper manager → Metadata resolution: uses anime data (evidence: `comet/scrapers/manager.py`)
- Metadata resolution → Database: reads and caches (evidence: `comet/metadata/manager.py`)
- Metadata resolution → Media search: resolves metadata
- Torrent management → Database: persists torrents (evidence: `comet/services/torrent_manager.py`)
- Torrent management → P2P protocol: uses protocol (evidence: `comet/services/torrent_manager.py`)
- Stream delivery → Torrent management: uses torrent data
- Stream delivery → Debrid services: proxies debrid streams (evidence: `README.md`)
- Background scraper → Database: updates scrape state (evidence: `comet/background_scraper/worker.py`)
- Background scraper → Metadata resolution: requests metadata (evidence: `comet/background_scraper/worker.py`)
- Background scraper → Media search: orchestrates scraping (evidence: `comet/background_scraper/worker.py`)
- CometNet manager → P2P protocol: coordinates protocol (evidence: `comet/cometnet/manager.py`)
