# mlange-42/git-graph architecture

> Architecture diagram of the GitHub repository mlange-42/git-graph, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mlange-42/git-graph
- Repository: https://github.com/mlange-42/git-graph

## Overview

##### Project type and purpose
- This is an open-source, command-line Rust tool (a Cargo crate) called “git-graph.”
- Its purpose is to read a Git repository’s history, build an internal graph representation of commits and branches (following user-selectable branching models), and render that graph in the terminal (or to SVG).

##### File structure
- Top-level:
- Cargo.toml / Cargo.lock: Rust package metadata and dependency lockfile
- src/: Rust source code
- docs/: user manual and model specification
- .github/workflows/: CI for tests, releases
- Justfile: build/automation shortcuts
- src/ layout:
- main.rs: CLI entrypoint
- lib.rs: public crate interface
- config.rs + settings.rs: loading CLI flags, config files, default settings
- graph.rs: core graph-building logic (parsing Git history, modeling commits/branches)
- print/: rendering logic
- External dependencies in Cargo.toml (e.g., clap for argument parsing, serde/toml for config, git2 or shelling out to git).

##### README for additional insights
- Describes features: structured graphs, branching models, ASCII or Unicode output, custom formatting.
- Mentions custom branching models loaded from user’s AppData/.config folder (TOML files).

##### Components and their relationships
a. Main components:
1. CLI Parser (main.rs + lib.rs using clap or structopt)
2. Configuration Loader (config.rs + settings.rs)
3. Git Adapter (calls out to `git log` or uses git2)
4. Graph Builder (graph.rs)
5. Renderer/Printer (print/ module)
6. Output Sink (terminal stdout or SVG file)
7. User Model Store (TOML files in ~/.config/git-graph/models)
b. Data flow:
[User invokes git-graph]
↓ CLI Parser parses flags & subcommands
↓ Configuration Loader merges defaults + CLI + user model file
↓ Git Adapter reads repository history → hands commit list to
↓ Graph Builder constructs internal node/edge model
↓ Output Sink writes to stdout or to an .svg file
c. Architectural patterns/design principles:
- Separation of concerns: parsing, config, graph logic, presentation are in separate modules
- Plugin/extension point: custom branching models loaded at runtime
- Single responsibility: each print module handles exactly one style
d. Key technologies:
- Rust programming language
- Cargo for build & dependency management
- clap (or structopt) for CLI
- serde + toml for config/model deserialization
- git2 or shelling-out for Git data
- svg crate or manual XML templating in svg.rs

##### Elements
- “CLI Parser”
- “Config Loader”
- “Git Adapter”
- “Graph Builder”
- “Printer Modules”
- “Output Sink”
- “Model Store (TOML files)”
- External services:
- Git binary / Git library
- Terminal / File system
- Data flow from user → CLI Parser → … → Output Sink
- How Config Loader reads from Model Store
- Git Adapter ↔ Git binary
- External dependencies (green clouds)
- Labels:

##### Detailed capture of architectural elements
- Plugin directory as a separate file store.
- That Cargo.toml/Cargo.lock drive versioning but aren’t part of runtime.

[User CLI Invocation]
↓
+------------------+
|  CLI Parser      |
+------------------+
↓
+------------------+      ←── reads TOML ── [Model Store: ~/.config/git-graph/models]
| Config Loader    |
+------------------+
↓
+------------------+      ↔── calls ── [Git binary or git2 library]
|   Git Adapter    |
+------------------+
↓
+------------------+
| Graph Builder    |
+------------------+
↓
+-----------------------------+
| Printer Modules             |
|  ┌──────┐ ┌──────┐ ┌──────┐ |
|  |ASCII | |Unicode| | SVG  | |
|  └──────┘ └──────┘ └──────┘ |
+-----------------------------+
↓
[Terminal stdout] or [output.svg]

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User["User CLI Invocation"]:::external

    %% Core components
    CLI["CLI Parser"]:::core
    Config["Config Loader"]:::core
    GitAdapter["Git Adapter"]:::core
    GraphBuilder["Graph Builder"]:::core

    subgraph "Printer Modules"
        direction TB
        Printer["Printer Entry (mod.rs)"]:::core
        ASCII["ASCII Printer"]:::core
        Unicode["Unicode Printer"]:::core
        SVGPrinter["SVG Printer"]:::core
    end

    Output["Output Sink"]:::core

    %% External and data stores
    ModelStore["Model Store\n(~/.config/git-graph/models)"]:::datastore
    GitBin["Git Binary / git2 Library"]:::external
    Terminal["Terminal stdout"]:::external
    SVGFile["output.svg file"]:::external

    %% Data flow
    User --> CLI
    CLI --> Config
    Config -->|reads TOML models| ModelStore
    Config --> GitAdapter
    GitAdapter <-->|calls| GitBin
    GitAdapter -->|commit list| GraphBuilder
    GraphBuilder -->|graph model| Printer
    Printer --> ASCII
    Printer --> Unicode
    Printer --> SVGPrinter
    Printer --> Output
    Output --> Terminal
    Output --> SVGFile

    %% Click events
    click CLI "https://github.com/mlange-42/git-graph/blob/master/src/main.rs"
    click CLI "https://github.com/mlange-42/git-graph/blob/master/src/lib.rs"
    click Config "https://github.com/mlange-42/git-graph/blob/master/src/config.rs"
    click Config "https://github.com/mlange-42/git-graph/blob/master/src/settings.rs"
    click GitAdapter "https://github.com/mlange-42/git-graph/blob/master/src/graph.rs"
    click GraphBuilder "https://github.com/mlange-42/git-graph/blob/master/src/graph.rs"
    click Printer "https://github.com/mlange-42/git-graph/blob/master/src/print/mod.rs"
    click ASCII "https://github.com/mlange-42/git-graph/blob/master/src/print/format.rs"
    click Unicode "https://github.com/mlange-42/git-graph/blob/master/src/print/unicode.rs"
    click SVGPrinter "https://github.com/mlange-42/git-graph/blob/master/src/print/svg.rs"
    click Output "https://github.com/mlange-42/git-graph/blob/master/src/print/svg.rs"
    click Output "https://github.com/mlange-42/git-graph/blob/master/src/print/format.rs"

    %% Styles
    classDef core fill:#D6EAF8,stroke:#1B4F72,color:#154360;
    classDef external fill:#D5F5E3,stroke:#145A32,color:#0B5345;
    classDef datastore fill:#FCF3CF,stroke:#B9770E,color:#7D6608;
```
