# koaning/gitcharts architecture

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

- Interactive diagram: https://gitdiagram.com/koaning/gitcharts
- Repository: https://github.com/koaning/gitcharts

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========
    %% Diagram 1: System Context (C4 L1)
    %% =========
    subgraph "System Context (C4 Level 1)"
        direction TB

        User["User (Developer / Analyst)"]:::external

        subgraph "gitcharts (this repo)"
            direction TB
            Tooling["Tooling + Scripts"]:::compute
            StaticSite["Static Web Site + Data Artifacts"]:::static
        end

        GitHost["Remote Git Host (GitHub / Git server)"]:::external
        LocalGit["Git (local operations)"]:::external
        MarimoEnv["marimo / molab (interactive runner)"]:::external
        Pages["Static Hosting (GitHub Pages or similar)"]:::external
        Browser["User Browser"]:::external

        User -->|"runs CLI"| Tooling
        User -->|"runs notebook/app"| MarimoEnv
        MarimoEnv -->|"executes scripts"| Tooling

        Tooling -->|"fetches repo history"| GitHost
        Tooling -->|"clone/log/diff"| LocalGit

        Tooling -->|"generates JSON artifacts"| StaticSite
        StaticSite -->|"publishes static assets"| Pages

        Pages -->|"serves HTML/JS/CSS + JSON"| Browser
        Browser -->|"GET /charts/*.json"| Pages
        User -->|"views charts"| Browser
    end

    %% =========
    %% Diagram 2: Containers / Pipeline + Runtime (C4 L2)
    %% =========
    subgraph "Pipeline + Runtime (C4 Level 2)"
        direction TB

        %% --- Lane A: Generate time ---
        subgraph "Generate Time (offline/batch)"
            direction TB

            Make["Makefile Automation"]:::tooling

            subgraph "Runner"
                direction TB
                Cli["CLI Runner\n(uv run git_archaeology.py --repo ... --samples ...)"]:::compute
                Notebook["Interactive Runner\n(marimo notebook/app)"]:::compute
            end

            Engine["Git Archaeology Engine"]:::compute
            RepoListGen["Repo List Generator"]:::compute

            subgraph "Charts Artifacts Store (static JSON 'database')"
                direction TB
                ChartsDir[("charts/ (folder)")]:::data
                ReposJson["repos.json"]:::data
                CleanJson["per-repo '*-clean.json'"]:::data
                VersionedJson["per-repo '*-versioned.json'"]:::data
            end

            RemoteRepos["Target Git Repositories\n(HTTPS URLs)"]:::external
            GitOps["Git Operations\n(clone/log/diff/show)"]:::external

            Make -->|"invokes"| Cli
            Notebook -->|"passes params"| Engine
            Cli -->|"passes params"| Engine

            Engine -->|"clone/read history"| GitOps
            GitOps -->|"network fetch"| RemoteRepos

            Engine -->|"writes datasets"| CleanJson
            Engine -->|"writes datasets"| VersionedJson

            RepoListGen -->|"writes catalog"| ReposJson

            ChartsDir --- ReposJson
            ChartsDir --- CleanJson
            ChartsDir --- VersionedJson
        end

        %% --- Lane B: View time ---
        subgraph "View Time (static)"
            direction TB

            subgraph "Static Web App"
                direction TB
                Html["index.html"]:::static
                AppJs["Frontend Logic (JS)\n(loads JSON + renders charts)"]:::static
                Css["Styles (CSS)"]:::static
                Render["Chart Rendering (in browser)"]:::static
            end

            Published["Published Static Site\n(GitHub Pages)"]:::external

            Html -->|"loads"| AppJs
            Html -->|"loads"| Css
            AppJs -->|"renders"| Render

            AppJs -->|"fetch repos catalog"| ReposJson
            AppJs -->|"fetch selected clean dataset"| CleanJson
            AppJs -->|"fetch selected versioned dataset"| VersionedJson

            Html -->|"served from"| Published
            AppJs -->|"served from"| Published
            Css -->|"served from"| Published
            ReposJson -->|"served from"| Published
            CleanJson -->|"served from"| Published
            VersionedJson -->|"served from"| Published
        end

        %% Deployment link between lanes
        ChartsDir -->|"publish artifacts"| Published
        Html -->|"publish page"| Published
        AppJs -->|"publish JS"| Published
        Css -->|"publish CSS"| Published
    end

    %% =========
    %% Tooling / Meta (docs)
    %% =========
    subgraph "Contributor Tooling (docs/templates; not runtime)"
        direction TB
        AgentsMarimoBatch[".agents skills: marimo-batch"]:::meta
        AgentsMarimoNotebook[".agents skills: marimo-notebook"]:::meta
        ClaudeSkills[".claude skills mirrors"]:::meta
    end

    AgentsMarimoBatch -.->|"guides usage"| Notebook
    AgentsMarimoNotebook -.->|"guides usage"| Notebook
    ClaudeSkills -.->|"contributor workflow"| Make

    %% =========
    %% Click Events (from component_mapping)
    %% =========
    click Engine "https://github.com/koaning/gitcharts/blob/main/git_archaeology.py"
    click RepoListGen "https://github.com/koaning/gitcharts/blob/main/generate_repos_list.py"
    click ChartsDir "https://github.com/koaning/gitcharts/tree/main/charts/"
    click ReposJson "https://github.com/koaning/gitcharts/blob/main/charts/repos.json"
    click CleanJson "https://github.com/koaning/gitcharts/blob/main/charts/*-clean.json"
    click VersionedJson "https://github.com/koaning/gitcharts/blob/main/charts/*-versioned.json"
    click Html "https://github.com/koaning/gitcharts/blob/main/index.html"
    click AppJs "https://github.com/koaning/gitcharts/blob/main/js/app.js"
    click Css "https://github.com/koaning/gitcharts/blob/main/css/styles.css"
    click Make "https://github.com/koaning/gitcharts/tree/main/Makefile"
    click AgentsMarimoBatch "https://github.com/koaning/gitcharts/tree/main/.agents/skills/marimo-batch/"
    click AgentsMarimoNotebook "https://github.com/koaning/gitcharts/tree/main/.agents/skills/marimo-notebook/"
    click ClaudeSkills "https://github.com/koaning/gitcharts/tree/main/.claude/skills/"

    %% =========
    %% Styles
    %% =========
    classDef compute fill:#1f77b4,stroke:#0b3d91,color:#ffffff,stroke-width:1px
    classDef static fill:#2ca02c,stroke:#1b5e20,color:#ffffff,stroke-width:1px
    classDef data fill:#f2c94c,stroke:#b07d00,color:#1f1f1f,stroke-width:1px
    classDef external fill:#bdbdbd,stroke:#616161,color:#111111,stroke-width:1px
    classDef tooling fill:#8e44ad,stroke:#4a235a,color:#ffffff,stroke-width:1px
    classDef meta fill:#ff7f0e,stroke:#a14f00,color:#ffffff,stroke-width:1px
```
