# techsavvymind/github_changes_tracking architecture

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

- Interactive diagram: https://gitdiagram.com/techsavvymind/github_changes_tracking
- Repository: https://github.com/techsavvymind/github_changes_tracking

## Overview

1. This repository is a small Python-based change-tracking system for GitHub content. The architecture is centered on ingesting change events, processing them, and persisting a change history.

2. The two main runtime entrypoints are `tracker.py` and `webhook_receiver.py`. `webhook_receiver.py` is the network-facing component, while `tracker.py` is the core processing logic that records or evaluates changes.

3. The primary inbound data flow is from GitHub into `webhook_receiver.py`. That implies GitHub webhook events are the external trigger for the system, rather than a user-facing UI or manual batch job.

4. `tracker.py` likely acts as the internal worker/service layer: it receives parsed event data from the webhook receiver, determines what changed, and writes the result to storage. This is the main business-logic boundary in the repo.

5. `changes.db` shows that change history is persisted locally in a database, most likely SQLite. That makes the architecture stateful, with the database serving as the system of record for tracked changes.

6. `a.yaml` and `b.yaml` appear to be tracked sample inputs or comparison artifacts. Their presence suggests the system may be monitoring YAML files or using YAML as the payload/configuration format for tracked entities.

7. `.github/workflows/track.yml` indicates there is a GitHub Actions workflow in the repo. That usually means part of the tracking process can be run automatically in CI, either on a schedule or on repository events.

8. `railway.json` points to deployment on Railway. So the service is likely intended to run as a small hosted web process, with the webhook receiver exposed to the internet and the tracker logic running in the same deployment.

9. `requirements.txt` defines a Python application stack. There are no signs of a frontend, queue, or multi-service backend; the architecture is intentionally lightweight: GitHub event source → Python webhook handler → tracker logic → SQLite persistence.

10. The main architecture boundary to capture in a diagram is the separation between external GitHub services and the internal Python service. GitHub is both the event producer and, via Actions, a possible automation runner; the repo itself is the local processing and storage layer.

Main entry points: [`tracker.py`](https://github.com/techsavvymind/github_changes_tracking/blob/main/tracker.py) (Tracker), [`webhook_receiver.py`](https://github.com/techsavvymind/github_changes_tracking/blob/main/webhook_receiver.py) (Webhook receiver), [`.github/workflows/track.yml`](https://github.com/techsavvymind/github_changes_tracking/blob/main/.github/workflows/track.yml) (track workflow), [`railway.json`](https://github.com/techsavvymind/github_changes_tracking/blob/main/railway.json) (Railway config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External systems"]
  node_github_webhooks(("GitHub webhooks<br/>event source"))
  node_github_actions(("GitHub Actions<br/>automation runner<br/>[track.yml]"))
  node_deployment["Railway config<br/>deploy config<br/>[railway.json]"]
end

subgraph group_service["Python service"]
  node_webhook_receiver["Webhook receiver<br/>network entrypoint"]
  node_tracker["Tracker<br/>change processor<br/>[tracker.py]"]
  node_event_parse["Event parsing<br/>request decode"]
  node_change_eval["Change evaluation<br/>diff logic"]
  node_record_write["Record write<br/>persistence adapter"]
end

subgraph group_storage["Persistence"]
  node_changes_db[("changes.db<br/>sqlite store<br/>[changes.db]")]
  node_sample_a["a.yaml<br/>tracked sample<br/>[a.yaml]"]
  node_sample_b["b.yaml<br/>tracked sample<br/>[b.yaml]"]
end

subgraph group_ci["CI workflow"]
  node_track_workflow["track workflow<br/>github actions job<br/>[track.yml]"]
end

node_github_webhooks -->|"deliver event"| node_webhook_receiver
node_webhook_receiver -->|"decode payload"| node_event_parse
node_event_parse -->|"forward change"| node_tracker
node_tracker -->|"analyze"| node_change_eval
node_change_eval -->|"prepare record"| node_record_write
node_record_write -->|"store history"| node_changes_db
node_github_actions -->|"run workflow"| node_track_workflow
node_track_workflow -->|"invoke logic"| node_tracker
node_deployment -->|"host service"| node_webhook_receiver
node_sample_a -.->|"example input"| node_tracker
node_sample_b -.->|"example input"| node_tracker

click node_github_actions "https://github.com/techsavvymind/github_changes_tracking/blob/main/.github/workflows/track.yml"
click node_webhook_receiver "https://github.com/techsavvymind/github_changes_tracking/blob/main/webhook_receiver.py"
click node_tracker "https://github.com/techsavvymind/github_changes_tracking/blob/main/tracker.py"
click node_changes_db "https://github.com/techsavvymind/github_changes_tracking/blob/main/changes.db"
click node_sample_a "https://github.com/techsavvymind/github_changes_tracking/blob/main/a.yaml"
click node_sample_b "https://github.com/techsavvymind/github_changes_tracking/blob/main/b.yaml"
click node_track_workflow "https://github.com/techsavvymind/github_changes_tracking/blob/main/.github/workflows/track.yml"
click node_deployment "https://github.com/techsavvymind/github_changes_tracking/blob/main/railway.json"

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_github_webhooks,node_github_actions,node_deployment toneBlue
class node_webhook_receiver,node_tracker,node_event_parse,node_change_eval,node_record_write toneAmber
class node_changes_db,node_sample_a,node_sample_b toneMint
class node_track_workflow toneRose
```

## Components

### External systems

Outside event sources and automation that interact with the repository service.

- **GitHub webhooks**: event source · Inbound change events that trigger tracking.
- [GitHub Actions](https://github.com/techsavvymind/github_changes_tracking/blob/main/.github/workflows/track.yml): automation runner · Repository automation that can execute the tracking workflow. · `.github/workflows/track.yml`
- [Railway config](https://github.com/techsavvymind/github_changes_tracking/blob/main/railway.json): deploy config · Deployment configuration for hosting the webhook service. · `railway.json`

### Python service

Core webhook handling and change-tracking logic.

- [Webhook receiver](https://github.com/techsavvymind/github_changes_tracking/blob/main/webhook_receiver.py): network entrypoint · Receives and parses incoming GitHub webhook requests. · `webhook_receiver.py`
- [Tracker](https://github.com/techsavvymind/github_changes_tracking/blob/main/tracker.py): change processor · Core business logic that evaluates changes and records history. · `tracker.py`
- **Event parsing**: request decode · Turns webhook payloads into internal change records.
- **Change evaluation**: diff logic · Determines what changed and whether it should be tracked.
- **Record write**: persistence adapter · Writes processed change data to the local database.

### Persistence

Local state and tracked artifacts.

- [changes.db](https://github.com/techsavvymind/github_changes_tracking/blob/main/changes.db): sqlite store · Local system of record for tracked change history. · `changes.db`
- [a.yaml](https://github.com/techsavvymind/github_changes_tracking/blob/main/a.yaml): tracked sample · Sample YAML artifact or tracked input used by the repository. · `a.yaml`
- [b.yaml](https://github.com/techsavvymind/github_changes_tracking/blob/main/b.yaml): tracked sample · Second YAML artifact or comparison input used by the repository. · `b.yaml`

### CI workflow

GitHub Actions automation for running tracking tasks.

- [track workflow](https://github.com/techsavvymind/github_changes_tracking/blob/main/.github/workflows/track.yml): github actions job · Workflow definition that runs the tracking process in CI. · `.github/workflows/track.yml`

## Connections

- GitHub webhooks → Webhook receiver: deliver event · GitHub sends webhook requests to the network-facing entrypoint.
- Webhook receiver → Event parsing: decode payload · Receiver converts HTTP/webhook payloads into internal event data.
- Event parsing → Tracker: forward change · Parsed events are handed to the core tracker logic.
- Tracker → Change evaluation: analyze · Tracker determines what changed and how to classify it.
- Change evaluation → Record write: prepare record · Evaluated changes are prepared for persistence.
- Record write → changes.db: store history · Processed change history is written to the local database.
- GitHub Actions → track workflow: run workflow · GitHub Actions executes the repository tracking workflow.
- track workflow → Tracker: invoke logic · The workflow can call into the same tracking code path.
- Railway config → Webhook receiver: host service · Railway config supports deploying the webhook receiver as a hosted process.
- a.yaml → Tracker: example input · Sample YAML artifact can be consumed by the tracking logic.
- b.yaml → Tracker: example input · Second sample YAML artifact can be consumed by the tracking logic.
