How techsavvymind/github_changes_tracking works
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 Tracker · webhook_receiver.py Webhook receiver · track.yml track workflow · railway.json Railway config
Components 12
External systems
Outside event sources and automation that interact with the repository service.
- GitHub webhooks · Inbound change events that trigger tracking.
- GitHub Actions · Repository automation that can execute the tracking workflow.
.github/workflows/track.yml - Railway config · Deployment configuration for hosting the webhook service.
railway.json
Python service
Core webhook handling and change-tracking logic.
- Webhook receiver · Receives and parses incoming GitHub webhook requests.
webhook_receiver.py - Tracker · Core business logic that evaluates changes and records history.
tracker.py - Event parsing · Turns webhook payloads into internal change records.
- Change evaluation · Determines what changed and whether it should be tracked.
- Record write · Writes processed change data to the local database.
Persistence
Local state and tracked artifacts.
- changes.db · Local system of record for tracked change history.
changes.db - a.yaml · Sample YAML artifact or tracked input used by the repository.
a.yaml - b.yaml · Second YAML artifact or comparison input used by the repository.
b.yaml
CI workflow
GitHub Actions automation for running tracking tasks.
- track workflow · Workflow definition that runs the tracking process in CI.
.github/workflows/track.yml
Connections 11
- 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.