How koaning/gitcharts works
Project type & purpose (what you’re diagramming)
This repo is a data-collection + analysis + visualization project that generates “git archaeology” metrics from a target Git repository and renders them as interactive charts via a static web page (and optionally via a marimo notebook/app).
Key signals:
• git_archaeology.py: the core analyzer and also a CLI entrypoint (uv run git_archaeology.py --repo ...).
• charts/*.json: precomputed datasets (both “clean” and “versioned”) that the frontend likely loads.
• index.html, js/app.js, css/styles.css: a static client (likely GitHub Pages).
• README: explicitly mentions “GitHub pages link” and “marimo notebook”.
Repo into architectural components (from the file tree)
Treat the project as 4 major subsystems:
Analysis / Data Generation (Python)
• git_archaeology.py
• Responsibilities (inferred from name/usage): clone/open repo, sample commits, compute rewrite/churn-like metrics, output chart-ready structures.
• Operates as:
• CLI tool (batch mode)
• marimo notebook/app (interactive mode)
• generate_repos_list.py
• Generates/updates charts/repos.json used by the UI (a selector/list).
Data Artifacts (JSON outputs)
• **charts/*.json**
• Examples: *-clean.json and *-versioned.json
• These are the “database” of this repo, but stored as static JSON files committed/published.
Visualization Frontend (Static Site)
• index.html
• js/app.js
• css/styles.css
• Likely behavior: fetch JSON from /charts/*.json, render charts, allow repo selection via repos.json.
Tooling / Meta
• Makefile: automation for generating charts, building site artifacts, etc.
• .agents/, .claude/: internal “skills” documentation/templates; not runtime, but relevant for contributor workflow.
• Target Git repositories (typically GitHub HTTPS URLs).
• Git (local git operations) and/or GitHub network access.
• marimo / molab as an execution environment for the notebook/app.
• GitHub Pages (or any static hosting) for deployment.
CLI/Notebook Runner
• uv run git_archaeology.py ... (CLI)
• marimo notebook execution (interactive)
Git Archaeology Engine (inside git_archaeology.py)
• Inputs: --repo URL, --samples
• Calls: git operations (clone/log/show), parses diffs/commits
• Outputs: chart datasets
Repo List Generator (generate_repos_list.py)
• Output: charts/repos.json
Artifacts Folder (charts/)
• Stores: *-clean.json, *-versioned.json, repos.json
• Runner → Engine: parameters (repo URL, samples)
• Engine ↔ Git: clone/read history/diffs
• Engine → charts/*.json: write datasets
• Repo List Generator → charts/repos.json: write repo catalog
Lane B: View time (static)
Components:
Static Web App
• index.html
• js/app.js
• css/styles.css
Charts JSON
• charts/*.json
• Browser loads index.html → loads js/app.js + css/styles.css
• js/app.js → fetch charts/repos.json and selected repo’s *-clean.json / *-versioned.json
• charts/ + index.html + js/ + css/ → “published to GitHub Pages”
Static-data-driven UI
The “backend” is not a service; it’s a data generation step producing JSON. The UI is purely client-side.
Dual-mode execution (batch + interactive)
git_archaeology.py is both:
• a CLI batch tool (repeatable generation)
• a marimo notebook/app (interactive exploration)
Versioned vs clean datasets
The *-clean.json vs *-versioned.json split suggests two representations:
• “clean” (normalized/aggregated)
• “versioned” (more raw/time-indexed)
What to label explicitly (technologies & interfaces)
• CLI interface: uv run git_archaeology.py --repo ... --samples ...
• Git interface: “clone”, “log”, “diff” (local git plumbing)
• Data format: JSON files in charts/
• Frontend: static HTML/JS/CSS (and “fetch JSON over HTTP”)
• Hosting: GitHub Pages (static)
• commit sampler
• diff analyzer
• metrics calculator
• JSON serializer
• marimo UI bindings (if present)