# adamtornhill/code-maat architecture

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

- Interactive diagram: https://gitdiagram.com/adamtornhill/code-maat
- Repository: https://github.com/adamtornhill/code-maat

## Overview

##### Project type and purpose
- Code Maat is an open-source command-line tool (Clojure) for mining and analyzing version-control logs (git, hg, svn, p4, tfs).
- No GUI/web front end—focus is on parsing input logs, computing metrics, and producing CSV output or piping to visualization tools.

##### High-level architecture from the file tree and README
- Top-level: Dockerfile, project.clj (build), README.md, Travis config, doc/ (guides & images).
- src/code_maat/: main code divided into:
- cmd_line.clj – command-line dispatcher
- parsers/ – one parser module per VCS plus XML/time parsers
- dataset/ – dataset builder holding in-memory data model
- app/ – grouping logic (team_mapper, time_based_grouper, generic grouper)
- analysis/ – independent analysis modules (authors, churn, coupling, code_age, etc.)
- output/ – CSV formatter and filter modules
- test/ and src/code_maat/test/ cover unit, end-to-end, data-driven tests.

##### Core dataflow and component interactions
- 1) CLI layer reads arguments (log file path, VCS type, analysis type, flags)
↓
- 2) Parser adapter (selects git/git2/hg/svn/p4/tfs parser) consumes raw log → produces sequence of commit records
↓
- 3) Dataset builder ingests commit records → builds in-memory representation of entities, authors, timestamps
↓
- 4) (Optional) App-level grouping transforms dataset based on layer definitions or temporal periods
↓
- 5) Analysis engine invokes chosen analysis module(s) on the dataset → yields metric records
↓
- 6) Output layer formats metric records (CSV, filters) → writes to STDOUT, file, or pipes to downstream tools

##### Key architectural patterns and design principles
- Strategy/plugin pattern: parsers and analyses are pluggable modules implementing a common interface
- Functional pipeline: pure data transformations from raw log → dataset → analysis → output
- Separation of concerns: clear layers for input, data model, business logic (analysis), presentation (output)
- Extensibility: adding a new VCS parser or metric analysis requires dropping in a new namespace under parsers/ or analysis/.

##### External dependencies and packaging
- Clojure runtime + Incanter (for data handling), Leiningen build tool
- Packaged as standalone Uberjar or Docker image (Dockerfile)
- Can also be used as a Clojure library via project.clj dependency

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External entities
    Logs["VCS Log Files"]:::external
    STDOUT["STDOUT/Files"]:::external
    Viz["Downstream Visualization Tools"]:::external

    %% CLI Dispatcher
    CLI["CLI Dispatcher\n(code_maat.cmd_line)"]:::orchestration
    click CLI "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/cmd_line.clj"

    %% Parser Modules
    subgraph "Parser Modules" 
        direction TB
        Git["code_maat.parsers.git"]:::adapter
        Git2["code_maat.parsers.git2"]:::adapter
        Mercurial["code_maat.parsers.mercurial"]:::adapter
        SVN["code_maat.parsers.svn"]:::adapter
        P4["code_maat.parsers.perforce"]:::adapter
        TFS["code_maat.parsers.tfs"]:::adapter
        XML["code_maat.parsers.xml"]:::adapter
        TimeParser["code_maat.parsers.time_parser"]:::adapter
        Hiccup["code_maat.parsers.hiccup_based_parser"]:::adapter
    end
    click Git "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/parsers/git.clj"
    click Git2 "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/parsers/git2.clj"
    click Mercurial "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/parsers/mercurial.clj"
    click SVN "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/parsers/svn.clj"
    click P4 "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/parsers/perforce.clj"
    click TFS "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/parsers/tfs.clj"
    click XML "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/parsers/xml.clj"
    click TimeParser "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/parsers/time_parser.clj"
    click Hiccup "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/parsers/hiccup_based_parser.clj"

    %% Dataset Builder
    Dataset["Dataset Builder\n(code_maat.dataset.dataset)"]:::core
    click Dataset "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/dataset/dataset.clj"

    %% App-Level Groupers
    subgraph "App-Level Groupers"
        direction TB
        AppOrch["Orchestrator\n(code_maat.app.app)"]:::orchestration
        GenericG["Generic Grouper\n(code_maat.app.grouper)"]:::orchestration
        TeamMap["Team Mapper\n(code_maat.app.team_mapper)"]:::orchestration
        TimeG["Time-Based Grouper\n(code_maat.app.time_based_grouper)"]:::orchestration
    end
    click AppOrch "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/app/app.clj"
    click GenericG "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/app/grouper.clj"
    click TeamMap "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/app/team_mapper.clj"
    click TimeG "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/app/time_based_grouper.clj"

    %% Analysis Modules
    subgraph "Analysis Modules"
        direction TB
        Authors["Authors\n(code_maat.analysis.authors)"]:::core
        Churn["Churn\n(code_maat.analysis.churn)"]:::core
        Age["Code Age\n(code_maat.analysis.code_age)"]:::core
        CommitMsg["Commit Messages\n(code_maat.analysis.commit_messages)"]:::core
        Comm["Communication\n(code_maat.analysis.communication)"]:::core
        Coupling["Coupling Algos\n(code_maat.analysis.coupling_algos)"]:::core
        Effort["Effort\n(code_maat.analysis.effort)"]:::core
        Entities["Entities\n(code_maat.analysis.entities)"]:::core
        LogCouple["Logical Coupling\n(code_maat.analysis.logical_coupling)"]:::core
        MathUtil["Math Utils\n(code_maat.analysis.math)"]:::core
        SumCouple["Sum of Coupling\n(code_maat.analysis.sum_of_coupling)"]:::core
        Summary["Summary\n(code_maat.analysis.summary)"]:::core
        Workarounds["Workarounds\n(code_maat.analysis.workarounds)"]:::core
    end
    click Authors "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/analysis/authors.clj"
    click Churn "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/analysis/churn.clj"
    click Age "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/analysis/code_age.clj"
    click CommitMsg "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/analysis/commit_messages.clj"
    click Comm "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/analysis/communication.clj"
    click Coupling "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/analysis/coupling_algos.clj"
    click Effort "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/analysis/effort.clj"
    click Entities "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/analysis/entities.clj"
    click LogCouple "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/analysis/logical_coupling.clj"
    click MathUtil "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/analysis/math.clj"
    click SumCouple "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/analysis/sum_of_coupling.clj"
    click Summary "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/analysis/summary.clj"
    click Workarounds "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/analysis/workarounds.clj"

    %% Output Formatters
    subgraph "Output Formatters"
        direction TB
        CSV["CSV Writer\n(code_maat.output.csv)"]:::adapter
        Filters["Filters\n(code_maat.output.filters)"]:::adapter
    end
    click CSV "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/output/csv.clj"
    click Filters "https://github.com/adamtornhill/code-maat/blob/master/src/code_maat/output/filters.clj"

    %% Packaging
    Jar["Uberjar\n(project.clj)"]:::external
    Docker["Docker Image\n(Dockerfile)"]:::external
    Doc["Documentation\n(README.md, doc/)"]:::external
    click Jar "https://github.com/adamtornhill/code-maat/blob/master/project.clj"
    click Docker "https://github.com/adamtornhill/code-maat/tree/master/Dockerfile"
    click Doc "https://github.com/adamtornhill/code-maat/blob/master/README.md"

    %% Data Flow
    Logs -->|"raw log"| CLI
    CLI -->|"select parser"| Git & Git2 & Mercurial & SVN & P4 & TFS & XML & TimeParser & Hiccup
    Git & Git2 & Mercurial & SVN & P4 & TFS & XML & TimeParser & Hiccup -->|"CommitRecord seq"| Dataset
    Dataset -->|"Dataset"| AppOrch
    AppOrch --> GenericG
    AppOrch --> TeamMap
    AppOrch --> TimeG
    GenericG & TeamMap & TimeG -->|"Transformed Dataset"| Authors
    Authors & Churn & Age & CommitMsg & Comm & Coupling & Effort & Entities & LogCouple & MathUtil & SumCouple & Summary & Workarounds -->|"MetricRecord seq"| CSV
    CSV -->|"CSV"| STDOUT
    Filters -->|"Filtered CSV"| Viz

    %% Packaging boundaries
    CLI --> Jar
    Jar --> Docker
    Jar --> Doc

    %% Styles
    classDef orchestration fill:#fde,stroke:#bb2,stroke-width:1px;
    classDef adapter fill:#def,stroke:#48b,stroke-width:1px;
    classDef core fill:#dfd,stroke:#2b8,stroke-width:1px;
    classDef external stroke:#999,stroke-dasharray:5 5,fill:#fff;
    class Logs,STDOUT,Viz,Jar,Docker,Doc external
    class CLI,AppOrch,GenericG,TeamMap,TimeG orchestration
    class Git,Git2,Mercurial,SVN,P4,TFS,XML,TimeParser,Hiccup,CSV,Filters adapter
    class Dataset,Authors,Churn,Age,CommitMsg,Comm,Coupling,Effort,Entities,LogCouple,MathUtil,SumCouple,Summary,Workarounds core
```
