# iptv-org/database architecture

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

- Interactive diagram: https://gitdiagram.com/iptv-org/database
- Repository: https://github.com/iptv-org/database

## Overview

This repository is a user-editable IPTV reference database, with CSV files as its source of truth. Contributors propose channel, feed, logo, city, and blocklist changes through GitHub issues; issue validation checks requests against loaded database data, and the update command processes approved issues and saves changes. A separate validation/export path supports database quality checks and API data generation. The README documents API availability, but the API service itself is maintained elsewhere. Some command implementations were not sampled, so their internal wiring is represented only where supported by the tree, README, or excerpts.

Main entry points: [`scripts/core/db.ts`](https://github.com/iptv-org/database/blob/master/scripts/core/db.ts) (Database access), [`scripts/commands/db/update.ts`](https://github.com/iptv-org/database/blob/master/scripts/commands/db/update.ts) (Issue processing), [`scripts/models`](https://github.com/iptv-org/database/tree/master/scripts/models) (Domain records), [`scripts/commands/issue/validate.ts`](https://github.com/iptv-org/database/blob/master/scripts/commands/issue/validate.ts) (Request validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Contribution intake"]
  node_issue_forms["Issue forms<br/>[ISSUE_TEMPLATE]"]
  node_issue_validate["Request validation<br/>[validate.ts]"]
end

subgraph group_runtime["Database runtime"]
  node_data_set["Request fields<br/>[dataSet.ts]"]
  node_core_db["Database access<br/>[db.ts]"]
  node_models["Domain records"]
  node_validator["Validation rules<br/>[validator.ts]"]
  node_csv_data[("CSV source data")]
end

subgraph group_curation["Data curation"]
  node_issue_update["Issue processing<br/>[update.ts]"]
  node_db_validate["Database validation<br/>[validate.ts]"]
  node_logo_check["Logo checking<br/>[check_logos.ts]"]
end

subgraph group_distribution["Data distribution"]
  node_db_export["API data export<br/>[export.ts]"]
  node_api_files["API data files"]
end

node_contributors(("Contributors"))
node_github(("GitHub issues"))
node_api_consumers(("API consumers"))
node_image_hosts(("Logo image hosts"))

node_contributors -->|"submit changes"| node_issue_forms
node_issue_forms -->|"opens issue"| node_github
node_github -->|"validates request"| node_issue_validate
node_issue_validate -->|"parses fields"| node_data_set
node_issue_validate -->|"loads data"| node_core_db
node_issue_update -->|"loads issues"| node_github
node_issue_update -->|"loads and saves"| node_core_db
node_issue_update -->|"reads fields"| node_data_set
node_issue_update -->|"updates records"| node_models
node_core_db -->|"reads and writes"| node_csv_data
node_core_db -->|"parses records"| node_models
node_models -->|"validates records"| node_validator
node_db_validate -->|"loads data"| node_core_db
node_db_validate -->|"validates records"| node_models
node_db_export -->|"loads data"| node_core_db
node_db_export -->|"exports data"| node_api_files
node_api_consumers -.->|"accesses data"| node_api_files
node_logo_check -->|"reads logos"| node_csv_data
node_logo_check -->|"checks images"| node_image_hosts

click node_issue_forms "https://github.com/iptv-org/database/tree/master/.github/ISSUE_TEMPLATE"
click node_issue_validate "https://github.com/iptv-org/database/blob/master/scripts/commands/issue/validate.ts"
click node_issue_update "https://github.com/iptv-org/database/blob/master/scripts/commands/db/update.ts"
click node_data_set "https://github.com/iptv-org/database/blob/master/scripts/core/dataSet.ts"
click node_core_db "https://github.com/iptv-org/database/blob/master/scripts/core/db.ts"
click node_models "https://github.com/iptv-org/database/tree/master/scripts/models"
click node_validator "https://github.com/iptv-org/database/blob/master/scripts/core/validator.ts"
click node_csv_data "https://github.com/iptv-org/database/tree/master/data"
click node_db_validate "https://github.com/iptv-org/database/blob/master/scripts/commands/db/validate.ts"
click node_db_export "https://github.com/iptv-org/database/blob/master/scripts/commands/db/export.ts"
click node_logo_check "https://github.com/iptv-org/database/blob/master/scripts/commands/db/check_logos.ts"

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_issue_forms,node_issue_validate toneBlue
class node_data_set,node_core_db,node_models,node_validator,node_csv_data toneAmber
class node_issue_update,node_db_validate,node_logo_check,node_api_consumers toneMint
class node_db_export,node_api_files toneRose
class node_contributors,node_github,node_image_hosts toneIndigo
```

## Components

### Contribution intake

- [Issue forms](https://github.com/iptv-org/database/tree/master/.github/ISSUE_TEMPLATE): `.github/ISSUE_TEMPLATE`
- [Request validation](https://github.com/iptv-org/database/blob/master/scripts/commands/issue/validate.ts): `scripts/commands/issue/validate.ts`

### Database runtime

- [Request fields](https://github.com/iptv-org/database/blob/master/scripts/core/dataSet.ts): `scripts/core/dataSet.ts`
- [Database access](https://github.com/iptv-org/database/blob/master/scripts/core/db.ts): `scripts/core/db.ts`
- [Domain records](https://github.com/iptv-org/database/tree/master/scripts/models): `scripts/models`
- [Validation rules](https://github.com/iptv-org/database/blob/master/scripts/core/validator.ts): `scripts/core/validator.ts`
- [CSV source data](https://github.com/iptv-org/database/tree/master/data): `data`

### Data curation

- [Issue processing](https://github.com/iptv-org/database/blob/master/scripts/commands/db/update.ts): `scripts/commands/db/update.ts`
- [Database validation](https://github.com/iptv-org/database/blob/master/scripts/commands/db/validate.ts): `scripts/commands/db/validate.ts`
- [Logo checking](https://github.com/iptv-org/database/blob/master/scripts/commands/db/check_logos.ts): `scripts/commands/db/check_logos.ts`

### Data distribution

- [API data export](https://github.com/iptv-org/database/blob/master/scripts/commands/db/export.ts): `scripts/commands/db/export.ts`
- **API data files**

### Other components

- **Contributors**
- **GitHub issues**
- **API consumers**
- **Logo image hosts**

## Connections

- Contributors → Issue forms: submit changes
- Issue forms → GitHub issues: opens issue
- GitHub issues → Request validation: validates request
- Request validation → Request fields: parses fields
- Request validation → Database access: loads data
- Issue processing → GitHub issues: loads issues
- Issue processing → Database access: loads and saves
- Issue processing → Request fields: reads fields
- Issue processing → Domain records: updates records
- Database access → CSV source data: reads and writes
- Database access → Domain records: parses records
- Domain records → Validation rules: validates records
- Database validation → Database access: loads data
- Database validation → Domain records: validates records
- API data export → Database access: loads data
- API data export → API data files: exports data
- API consumers → API data files: accesses data
- Logo checking → CSV source data: reads logos
- Logo checking → Logo image hosts: checks images