Commit Chronicle 📜

Commit Chronicle is een "SQL-first" analytics engine voor je GitHub historie. Het project is ontworpen als oefening in strikte architectuur principes: Python is "dom" (alleen data ophalen), en SQL is "slim" (alle logica, transformaties en analyses).

Gebouwd met: Python, Docker, PostgreSQL (JSONB), en Metabase.

🚀 Kenmerken

• Domme Ingestie laag: Een Python script haalt ruwe JSON events op van de GitHub API en dumpt ze 1-op-1 in PostgreSQL. Geen filtering, geen transformatie.
• SQL Transformatietaal: Alle logica gebeurt in de database.
  • Rawe data → Dimensie & Fact tabellen.
  • SQL Views voor complexe analyses (gaps & islands streaks, heatmaps).
• BI Dashboard: Metabase gekoppeld aan de database voor directe visualisatie.
• Privacy First: Draait lokaal, jouw data blijft van jou.

---

🛠 Installatie & Starten

Vereisten

• Docker & Docker Compose
• Een GitHub Personal Access Token (PAT)

1. Setup

Kopieer het voorbeeld environment bestand en vul je gegevens in:

cp .env.example .env
# Bewerk .env en vul je GITHUB_TOKEN en GITHUB_USERNAME in

Start de infrastructuur:

make up

2. Database Migraties

Maak de tabellen aan:

make migrate

3. Data Ophalen (Ingest)

Installeer de Python tools en haal data op:

# Eerst een virtual environment maken (optioneel, maar aanbevolen)
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Data ophalen (haal bijv. 5 pagina's op)
commit-chronicle ingest --max-pages 5

4. Transformatie & Analyse

Laat SQL zijn magie doen:

make transform

Bekijk direct resultaten in je terminal:

# Zie je streaks
commit-chronicle query commit_streaks_view

# Zie je refactor ratio
commit-chronicle query refactor_ratio_view

Of open Metabase op http://localhost:3000 voor grafieken.

---

🏗 Architectuur

Database Schema

1. raw_github_events: De "bron". Bevat onbewerkte JSON blobs van GitHub.
2. fact_commits: Genormaliseerde commits, afgeleid uit raw_github_events.
3. dim_repositories: Repository metadata.
4. dim_calendar: Gegenereerde kalender voor tijd-analyses.

Data Flow

graph LR
    GitHub[GitHub API] -->|Python Client| Raw[Postgres: raw_github_events]
    Raw -->|SQL Script| Facts[Postgres: fact_commits]
    Facts -->|SQL Views| Analytics[Analytics Views]
    Analytics -->|Query| CLI[CLI Output]
    Analytics -->|Connect| BI[Metabase Dashboard]

Loading

---

📝 SQL-First Regels

Dit project volgt strikte regels:

1. Python mag geen business logic bevatten (geen if event == 'PushEvent', geen sum()).
2. Alle datums en strings worden in SQL geparsed.
3. Views zijn de enige manier om data te consumeren (read-models).

---

🛡 Licentie

MIT.