# seif-douida/patch architecture

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

- Interactive diagram: https://gitdiagram.com/seif-douida/patch
- Repository: https://github.com/seif-douida/patch

## Overview

PatchPulse is an analyst-agent foundation for explaining Steam review-sentiment changes and estimating patch effects; the README says the project is still in Phase 0. Its implemented workflow is a nightly run that fetches and classifies Steam data, stores it, invokes dbt, exports dashboard JSON, and publishes it. The graph retains the documented analytics stages and source-indexed modules; unsampled dbt model internals and some runner calls are represented cautiously rather than inferred in detail.

Main entry points: [`src/patchpulse/pipeline/runner.py`](https://github.com/seif-douida/patch/blob/main/src/patchpulse/pipeline/runner.py) (Nightly orchestration), [`src/patchpulse/ingest/http.py`](https://github.com/seif-douida/patch/blob/main/src/patchpulse/ingest/http.py) (Steam HTTP client), [`src/patchpulse/db/engine.py`](https://github.com/seif-douida/patch/blob/main/src/patchpulse/db/engine.py) (SQL database), [`src/patchpulse/pipeline/cli.py`](https://github.com/seif-douida/patch/blob/main/src/patchpulse/pipeline/cli.py) (Pipeline commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Steam ingestion"]
  node_games_config["Tracked games<br/>[games.yaml]"]
  node_game_loader["Game configuration<br/>[games.py]"]
  node_steam_http["Steam HTTP client<br/>[http.py]"]
  node_review_fetch["Review paging<br/>[reviews.py]"]
  node_news_fetch["News fetching<br/>[news.py]"]
  node_price_fetch["Price fetching<br/>[prices.py]"]
  node_patch_classify["Patch classification<br/>[patches.py]"]
  node_coverage["Review coverage<br/>[coverage.py]"]
  node_record_models["Typed records and privacy<br/>[models.py]"]
end

subgraph group_pipeline["Nightly pipeline"]
  node_pipeline_cli["Pipeline commands<br/>[cli.py]"]
  node_nightly_runner["Nightly orchestration<br/>[runner.py]"]
  node_dbt_runner["dbt execution<br/>[dbt.py]"]
end

subgraph group_storage["Persistence"]
  node_database[("SQL database<br/>[engine.py]")]
  node_schema_tables["Raw and ops tables<br/>[tables.py]"]
  node_ingest_load["Ingest persistence<br/>[load.py]"]
end

subgraph group_analytics["Analytics and export"]
  node_dbt_models["Staging, core, marts"]
  node_site_export["Dashboard JSON export<br/>[site.py]"]
  node_publisher["Export publisher<br/>[cli.py]"]
end

subgraph group_operations["Configuration and operations"]
  node_settings["Pipeline settings<br/>[config.py]"]
  node_cost_guard["Cost guard<br/>[cost_guard.py]"]
end

node_analyst(("Studio analyst"))
node_steam["Steam"]
node_dashboard_data["Published dashboard data"]

node_analyst -.->|"inspects"| node_dashboard_data
node_games_config -->|"loaded by"| node_game_loader
node_pipeline_cli -->|"starts nightly"| node_nightly_runner
node_pipeline_cli -->|"connects through"| node_database
node_pipeline_cli -->|"loads settings"| node_settings
node_nightly_runner -->|"loads games"| node_game_loader
node_nightly_runner -->|"uses client"| node_steam_http
node_nightly_runner -->|"fetches reviews"| node_review_fetch
node_nightly_runner -->|"fetches news"| node_news_fetch
node_nightly_runner -->|"fetches prices"| node_price_fetch
node_nightly_runner -->|"plans coverage"| node_coverage
node_nightly_runner -->|"classifies news"| node_patch_classify
node_nightly_runner -->|"stores fetched data"| node_ingest_load
node_review_fetch -->|"requests pages"| node_steam_http
node_review_fetch -->|"creates records"| node_record_models
node_news_fetch -->|"requests news"| node_steam_http
node_news_fetch -->|"creates records"| node_record_models
node_price_fetch -->|"requests prices"| node_steam_http
node_price_fetch -->|"creates records"| node_record_models
node_steam_http -->|"sends requests"| node_steam
node_ingest_load -->|"writes tables"| node_schema_tables
node_ingest_load -.->|"writes to"| node_database
node_nightly_runner -->|"runs dbt"| node_dbt_runner
node_dbt_runner -.->|"builds models"| node_dbt_models
node_site_export -->|"reads marts"| node_database
node_nightly_runner -->|"builds export"| node_site_export
node_nightly_runner -->|"publishes files"| node_publisher
node_publisher -.->|"writes JSON"| node_dashboard_data
node_database -->|"configured by"| node_settings
node_cost_guard -.->|"guards spend"| node_database

click node_games_config "https://github.com/seif-douida/patch/blob/main/config/games.yaml"
click node_game_loader "https://github.com/seif-douida/patch/blob/main/src/patchpulse/ingest/games.py"
click node_steam_http "https://github.com/seif-douida/patch/blob/main/src/patchpulse/ingest/http.py"
click node_review_fetch "https://github.com/seif-douida/patch/blob/main/src/patchpulse/ingest/reviews.py"
click node_news_fetch "https://github.com/seif-douida/patch/blob/main/src/patchpulse/ingest/news.py"
click node_price_fetch "https://github.com/seif-douida/patch/blob/main/src/patchpulse/ingest/prices.py"
click node_patch_classify "https://github.com/seif-douida/patch/blob/main/src/patchpulse/ingest/patches.py"
click node_coverage "https://github.com/seif-douida/patch/blob/main/src/patchpulse/ingest/coverage.py"
click node_record_models "https://github.com/seif-douida/patch/blob/main/src/patchpulse/ingest/models.py"
click node_pipeline_cli "https://github.com/seif-douida/patch/blob/main/src/patchpulse/pipeline/cli.py"
click node_nightly_runner "https://github.com/seif-douida/patch/blob/main/src/patchpulse/pipeline/runner.py"
click node_dbt_runner "https://github.com/seif-douida/patch/blob/main/src/patchpulse/pipeline/dbt.py"
click node_database "https://github.com/seif-douida/patch/blob/main/src/patchpulse/db/engine.py"
click node_schema_tables "https://github.com/seif-douida/patch/blob/main/src/patchpulse/db/tables.py"
click node_ingest_load "https://github.com/seif-douida/patch/blob/main/src/patchpulse/ingest/load.py"
click node_dbt_models "https://github.com/seif-douida/patch/tree/main/dbt/models"
click node_site_export "https://github.com/seif-douida/patch/blob/main/src/patchpulse/export/site.py"
click node_publisher "https://github.com/seif-douida/patch/blob/main/src/patchpulse/pipeline/cli.py"
click node_settings "https://github.com/seif-douida/patch/blob/main/src/patchpulse/config.py"
click node_cost_guard "https://github.com/seif-douida/patch/blob/main/src/patchpulse/monitoring/cost_guard.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_games_config,node_game_loader,node_steam_http,node_review_fetch,node_news_fetch,node_price_fetch,node_patch_classify,node_coverage,node_record_models toneBlue
class node_pipeline_cli,node_nightly_runner,node_dbt_runner toneAmber
class node_database,node_schema_tables,node_ingest_load toneMint
class node_dbt_models,node_site_export,node_publisher toneRose
class node_settings,node_cost_guard,node_analyst,node_steam,node_dashboard_data toneIndigo
```

## Components

### Steam ingestion

- [Tracked games](https://github.com/seif-douida/patch/blob/main/config/games.yaml): `config/games.yaml`
- [Game configuration](https://github.com/seif-douida/patch/blob/main/src/patchpulse/ingest/games.py): `src/patchpulse/ingest/games.py`
- [Steam HTTP client](https://github.com/seif-douida/patch/blob/main/src/patchpulse/ingest/http.py): `src/patchpulse/ingest/http.py`
- [Review paging](https://github.com/seif-douida/patch/blob/main/src/patchpulse/ingest/reviews.py): `src/patchpulse/ingest/reviews.py`
- [News fetching](https://github.com/seif-douida/patch/blob/main/src/patchpulse/ingest/news.py): `src/patchpulse/ingest/news.py`
- [Price fetching](https://github.com/seif-douida/patch/blob/main/src/patchpulse/ingest/prices.py): `src/patchpulse/ingest/prices.py`
- [Patch classification](https://github.com/seif-douida/patch/blob/main/src/patchpulse/ingest/patches.py): `src/patchpulse/ingest/patches.py`
- [Review coverage](https://github.com/seif-douida/patch/blob/main/src/patchpulse/ingest/coverage.py): `src/patchpulse/ingest/coverage.py`
- [Typed records and privacy](https://github.com/seif-douida/patch/blob/main/src/patchpulse/ingest/models.py): `src/patchpulse/ingest/models.py`

### Nightly pipeline

- [Pipeline commands](https://github.com/seif-douida/patch/blob/main/src/patchpulse/pipeline/cli.py): `src/patchpulse/pipeline/cli.py`
- [Nightly orchestration](https://github.com/seif-douida/patch/blob/main/src/patchpulse/pipeline/runner.py): `src/patchpulse/pipeline/runner.py`
- [dbt execution](https://github.com/seif-douida/patch/blob/main/src/patchpulse/pipeline/dbt.py): `src/patchpulse/pipeline/dbt.py`

### Persistence

- [SQL database](https://github.com/seif-douida/patch/blob/main/src/patchpulse/db/engine.py): `src/patchpulse/db/engine.py`
- [Raw and ops tables](https://github.com/seif-douida/patch/blob/main/src/patchpulse/db/tables.py): `src/patchpulse/db/tables.py`
- [Ingest persistence](https://github.com/seif-douida/patch/blob/main/src/patchpulse/ingest/load.py): `src/patchpulse/ingest/load.py`

### Analytics and export

- [Staging, core, marts](https://github.com/seif-douida/patch/tree/main/dbt/models): `dbt/models`
- [Dashboard JSON export](https://github.com/seif-douida/patch/blob/main/src/patchpulse/export/site.py): `src/patchpulse/export/site.py`
- [Export publisher](https://github.com/seif-douida/patch/blob/main/src/patchpulse/pipeline/cli.py): `src/patchpulse/pipeline/cli.py`

### Configuration and operations

- [Pipeline settings](https://github.com/seif-douida/patch/blob/main/src/patchpulse/config.py): `src/patchpulse/config.py`
- [Cost guard](https://github.com/seif-douida/patch/blob/main/src/patchpulse/monitoring/cost_guard.py): `src/patchpulse/monitoring/cost_guard.py`

### Other components

- **Studio analyst**
- **Steam**
- **Published dashboard data**

## Connections

- Studio analyst → Published dashboard data: inspects
- Tracked games → Game configuration: loaded by (evidence: `src/patchpulse/ingest/games.py`)
- Pipeline commands → Nightly orchestration: starts nightly (evidence: `src/patchpulse/pipeline/cli.py`)
- Pipeline commands → SQL database: connects through (evidence: `src/patchpulse/pipeline/cli.py`)
- Pipeline commands → Pipeline settings: loads settings (evidence: `src/patchpulse/pipeline/cli.py`)
- Nightly orchestration → Game configuration: loads games (evidence: `src/patchpulse/pipeline/runner.py`)
- Nightly orchestration → Steam HTTP client: uses client (evidence: `src/patchpulse/pipeline/runner.py`)
- Nightly orchestration → Review paging: fetches reviews (evidence: `src/patchpulse/pipeline/runner.py`)
- Nightly orchestration → News fetching: fetches news (evidence: `src/patchpulse/pipeline/runner.py`)
- Nightly orchestration → Price fetching: fetches prices (evidence: `src/patchpulse/pipeline/runner.py`)
- Nightly orchestration → Review coverage: plans coverage (evidence: `src/patchpulse/pipeline/runner.py`)
- Nightly orchestration → Patch classification: classifies news (evidence: `src/patchpulse/pipeline/runner.py`)
- Nightly orchestration → Ingest persistence: stores fetched data (evidence: `src/patchpulse/pipeline/runner.py`)
- Review paging → Steam HTTP client: requests pages (evidence: `src/patchpulse/ingest/reviews.py`)
- Review paging → Typed records and privacy: creates records (evidence: `src/patchpulse/ingest/reviews.py`)
- News fetching → Steam HTTP client: requests news (evidence: `src/patchpulse/ingest/news.py`)
- News fetching → Typed records and privacy: creates records (evidence: `src/patchpulse/ingest/news.py`)
- Price fetching → Steam HTTP client: requests prices (evidence: `src/patchpulse/ingest/prices.py`)
- Price fetching → Typed records and privacy: creates records (evidence: `src/patchpulse/ingest/prices.py`)
- Steam HTTP client → Steam: sends requests (evidence: `src/patchpulse/ingest/http.py`)
- Ingest persistence → Raw and ops tables: writes tables (evidence: `src/patchpulse/ingest/load.py`)
- Ingest persistence → SQL database: writes to
- Nightly orchestration → dbt execution: runs dbt (evidence: `src/patchpulse/pipeline/runner.py`)
- dbt execution → Staging, core, marts: builds models
- Dashboard JSON export → SQL database: reads marts (evidence: `src/patchpulse/export/site.py`)
- Nightly orchestration → Dashboard JSON export: builds export (evidence: `src/patchpulse/pipeline/runner.py`)
- Nightly orchestration → Export publisher: publishes files (evidence: `src/patchpulse/pipeline/runner.py`)
- Export publisher → Published dashboard data: writes JSON
- SQL database → Pipeline settings: configured by (evidence: `src/patchpulse/db/engine.py`)
- Cost guard → SQL database: guards spend
