# knbr13/gitcs architecture

> Architecture diagram of the GitHub repository knbr13/gitcs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/knbr13/gitcs
- Repository: https://github.com/knbr13/gitcs

## Overview

##### Project Type and Purpose
- Type: Command‐line tool for visualizing Git commit histories locally.
- Purpose: Scan a local Git repository, aggregate commit data by date/author, and render a heatmap graph to the terminal.

##### File Structure
- `main.go`          – Entry point: parses flags (`-path`, `-email`, `-since`, `-until`) and orchestrates components.
- `scan.go`          – Implements scanning of the Git repository (calls `git log`) and parses commit metadata.
- `stats.go`         – Aggregates parsed commit data into a date‐based matrix of commit counts.
- `print.go`         – Renders the heatmap graph to the terminal output.
- `utils.go`         – Shared helpers (e.g., date parsing, flag validation).
- Tests (`*_test.go`) alongside each module ensure component correctness.
- CI workflows (`.github/workflows/*.yaml`) automate testing and release.

##### README for Additional Insights
- External Dependency: Git command‐line tool.
- Data Flow: Local Git repo → scanner → stats aggregator → printer → terminal.

##### Main Architecture Components
a. **CLI Frontend (main.go)**
– Flag parsing (Go’s `flag` package)
– Input validation (paths, dates, email)
– Invokes Scanner, Stats, and Printer
b. **Scanner Module (scan.go)**
– Executes `git log` via Go’s `os/exec`
– Parses raw commit lines into a slice of commit records
c. **Statistics Module (stats.go)**
– Receives commit records
– Builds a matrix: dates ↔ commit counts
– Applies “since/until” filters
d. **Renderer Module (print.go)**
– Takes the date/count matrix
– Outputs a terminal-friendly heatmap
e. **Utility Module (utils.go)**
– Date parsing, validation, shared types
f. **External Systems**
– Local Git CLI (data source)
– File system (repo directory and `.git`)
g. **CI/CD Pipelines**
– GitHub Actions for testing and releases

##### Relationships and Interactions
- **main.go** → invokes → **scan.go** → returns commit records → passed to → **stats.go** → returns matrix → passed to → **print.go** → writes to → Terminal
- **scan.go** ↔ executes ↔ Git CLI
- All modules share **utils.go** for common functions
- Tests invoke each module in isolation
- CI pipelines trigger `go test` and `go install` on push/release

##### Key Architectural Patterns & Principles
- Modular design: single‐responsibility per Go file
- Pipeline data flow: raw data → processed data → rendered output
- Test‐driven: `_test.go` files per module
- CLI‐centric: minimal external dependencies beyond Git

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Components
    CLI["CLI Frontend\n(main.go)"]:::cli
    Scanner["Scanner Module\n(scan.go)"]:::module
    Stats["Statistics Module\n(stats.go)"]:::module
    Renderer["Renderer Module\n(print.go)"]:::module
    Utils["Utility Module\n(utils.go)"]:::module
    GitCLI(["Git CLI"]):::external
    FS(["File System\n(repo directory)"]):::external
    Terminal(["Terminal Output"]):::external

    %% Tests
    subgraph "Tests"
        MT["main_test.go"]:::test
        ST["scan_test.go"]:::test
        ST2["stats_test.go"]:::test
        PT["print_test.go"]:::test
        UT["utils_test.go"]:::test
    end

    %% CI/CD
    subgraph "CI/CD Pipelines"
        TW["Test Workflow\n(.github/workflows/test.yaml)"]:::ci
        RW["Release Workflow\n(.github/workflows/release.yaml)"]:::ci
    end

    %% Data Flow
    CLI -->|"invokes"| Scanner
    Scanner -->|"returns commit records"| Stats
    Stats -->|"returns date matrix"| Renderer
    Renderer -->|"renders heatmap"| Terminal

    %% External Dependencies
    Scanner -->|"executes git log"| GitCLI
    Scanner -->|"reads repo"| FS

    %% Shared Utils
    CLI --> Utils
    Scanner --> Utils
    Stats --> Utils
    Renderer --> Utils

    %% Tests Invocation
    CLI -.-> MT
    Scanner -.-> ST
    Stats -.-> ST2
    Renderer -.-> PT
    Utils -.-> UT

    %% CI flows
    TW --> CLI
    TW --> Scanner
    TW --> Stats
    TW --> Renderer
    TW --> Utils
    RW --> CLI

    %% Click Events
    click CLI "https://github.com/knbr13/gitcs/blob/main/main.go"
    click Scanner "https://github.com/knbr13/gitcs/blob/main/scan.go"
    click Stats "https://github.com/knbr13/gitcs/blob/main/stats.go"
    click Renderer "https://github.com/knbr13/gitcs/blob/main/print.go"
    click Utils "https://github.com/knbr13/gitcs/blob/main/utils.go"
    click MT "https://github.com/knbr13/gitcs/blob/main/main_test.go"
    click ST "https://github.com/knbr13/gitcs/blob/main/scan_test.go"
    click ST2 "https://github.com/knbr13/gitcs/blob/main/stats_test.go"
    click PT "https://github.com/knbr13/gitcs/blob/main/print_test.go"
    click UT "https://github.com/knbr13/gitcs/blob/main/utils_test.go"
    click TW "https://github.com/knbr13/gitcs/blob/main/.github/workflows/test.yaml"
    click RW "https://github.com/knbr13/gitcs/blob/main/.github/workflows/release.yaml"

    %% Styles
    classDef cli fill:#FFD700,stroke:#333,stroke-width:1px
    classDef module fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
    classDef test fill:#FFA07A,stroke:#333,stroke-width:1px
    classDef ci fill:#DDA0DD,stroke:#333,stroke-width:1px
```
