# chefmarvin/roux architecture

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

- Interactive diagram: https://gitdiagram.com/chefmarvin/roux
- Repository: https://github.com/chefmarvin/roux

## Overview

Roux turns Git history or a supplied log into structured modification records, applies optional path/team/time transforms, runs a selected analysis, and emits CSV or JSON. The CLI and public API initiate the same application workflow. The README documents a broad analysis suite; the graph groups those analyses by purpose rather than listing every individual analysis. Edges reflect the sampled application flow and SOURCE INDEX references; unsampled implementation details are not inferred.

Main entry points: [`src/analysis/index.ts`](https://github.com/chefmarvin/roux/blob/main/src/analysis/index.ts) (Analysis selection), [`src/app.ts`](https://github.com/chefmarvin/roux/blob/main/src/app.ts) (Analysis workflow), [`src/utils/dataset.ts`](https://github.com/chefmarvin/roux/blob/main/src/utils/dataset.ts) (Dataset helpers), [`src/git.ts`](https://github.com/chefmarvin/roux/blob/main/src/git.ts) (Git log generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["CLI<br/>[cli.ts]"]
  node_app["Analysis workflow<br/>[app.ts]"]
end

subgraph group_history["History input"]
  node_git_history[("Git history")]
  node_git_generator["Git log generator<br/>[git.ts]"]
  node_log_cache[("Log cache<br/>[cache.ts]")]
  node_parser_registry["Parser registry<br/>[index.ts]"]
  node_git_parser["Git parser<br/>[git.ts]"]
  node_git2_parser["Git2 parser<br/>[git2.ts]"]
  node_rename_parser["Rename path parser<br/>[rename.ts]"]
  node_modifications["Modification records<br/>[types.ts]"]
end

subgraph group_transforms["Data transforms"]
  node_rename_tracking["Rename tracking<br/>[rename-tracker.ts]"]
  node_grouping["Architectural grouping<br/>[grouper.ts]"]
  node_temporal_grouping["Temporal grouping"]
  node_team_mapping["Team mapping<br/>[team-mapper.ts]"]
end

subgraph group_analysis["Analysis"]
  node_analysis_registry["Analysis selection<br/>[index.ts]"]
  node_hotspot_analysis["Hotspot and churn<br/>[churn.ts]"]
  node_coupling_analysis["Coupling<br/>[coupling.ts]"]
  node_age_analysis["Age<br/>[age.ts]"]
  node_collaboration_analysis["Collaboration<br/>[communication.ts]"]
  node_fragmentation_analysis["Knowledge fragmentation<br/>[fragmentation.ts]"]
  node_ownership_analysis["Ownership and effort"]
  node_other_analyses["Other analyses"]
  node_dataset_helpers["Dataset helpers<br/>[dataset.ts]"]
end

subgraph group_output["Output"]
  node_csv_output["CSV formatter<br/>[csv.ts]"]
  node_json_output["JSON formatter<br/>[json.ts]"]
end

node_cli_user(("CLI user"))
node_library_user(("API caller"))

node_cli_user -->|"invokes"| node_cli
node_cli -->|"calls"| node_app
node_library_user -->|"calls"| node_app
node_app -->|"generates log"| node_git_generator
node_git_generator -->|"queries"| node_git_history
node_git_generator -->|"checks cache"| node_log_cache
node_log_cache -->|"queries commits"| node_git_history
node_app -->|"selects parser"| node_parser_registry
node_parser_registry -->|"registers"| node_git_parser
node_parser_registry -->|"registers"| node_git2_parser
node_git_parser -->|"parses renames"| node_rename_parser
node_git2_parser -->|"parses renames"| node_rename_parser
node_git_parser -.->|"creates records"| node_modifications
node_git2_parser -->|"creates records"| node_modifications
node_app -->|"tracks renames"| node_rename_tracking
node_app -->|"applies groups"| node_grouping
node_app -->|"applies periods"| node_temporal_grouping
node_app -->|"maps teams"| node_team_mapping
node_app -->|"selects analysis"| node_analysis_registry
node_analysis_registry -->|"registers"| node_hotspot_analysis
node_analysis_registry -->|"registers"| node_coupling_analysis
node_analysis_registry -->|"registers"| node_age_analysis
node_analysis_registry -->|"registers"| node_collaboration_analysis
node_analysis_registry -->|"registers"| node_fragmentation_analysis
node_analysis_registry -->|"registers"| node_ownership_analysis
node_analysis_registry -->|"registers"| node_other_analyses
node_hotspot_analysis -->|"uses"| node_dataset_helpers
node_coupling_analysis -->|"uses"| node_dataset_helpers
node_age_analysis -->|"uses"| node_dataset_helpers
node_collaboration_analysis -->|"uses"| node_dataset_helpers
node_fragmentation_analysis -->|"uses"| node_dataset_helpers
node_analysis_registry -->|"formats results"| node_csv_output
node_analysis_registry -->|"formats results"| node_json_output

click node_cli "https://github.com/chefmarvin/roux/blob/main/src/cli.ts"
click node_app "https://github.com/chefmarvin/roux/blob/main/src/app.ts"
click node_git_generator "https://github.com/chefmarvin/roux/blob/main/src/git.ts"
click node_log_cache "https://github.com/chefmarvin/roux/blob/main/src/cache.ts"
click node_parser_registry "https://github.com/chefmarvin/roux/blob/main/src/parsers/index.ts"
click node_git_parser "https://github.com/chefmarvin/roux/blob/main/src/parsers/git.ts"
click node_git2_parser "https://github.com/chefmarvin/roux/blob/main/src/parsers/git2.ts"
click node_rename_parser "https://github.com/chefmarvin/roux/blob/main/src/parsers/rename.ts"
click node_modifications "https://github.com/chefmarvin/roux/blob/main/src/parsers/types.ts"
click node_rename_tracking "https://github.com/chefmarvin/roux/blob/main/src/transforms/rename-tracker.ts"
click node_grouping "https://github.com/chefmarvin/roux/blob/main/src/transforms/grouper.ts"
click node_temporal_grouping "https://github.com/chefmarvin/roux/blob/main/src/transforms/temporal-grouper.ts"
click node_team_mapping "https://github.com/chefmarvin/roux/blob/main/src/transforms/team-mapper.ts"
click node_analysis_registry "https://github.com/chefmarvin/roux/blob/main/src/analysis/index.ts"
click node_hotspot_analysis "https://github.com/chefmarvin/roux/blob/main/src/analysis/churn.ts"
click node_coupling_analysis "https://github.com/chefmarvin/roux/blob/main/src/analysis/coupling.ts"
click node_age_analysis "https://github.com/chefmarvin/roux/blob/main/src/analysis/age.ts"
click node_collaboration_analysis "https://github.com/chefmarvin/roux/blob/main/src/analysis/communication.ts"
click node_fragmentation_analysis "https://github.com/chefmarvin/roux/blob/main/src/analysis/fragmentation.ts"
click node_ownership_analysis "https://github.com/chefmarvin/roux/tree/main/src/analysis"
click node_other_analyses "https://github.com/chefmarvin/roux/tree/main/src/analysis"
click node_dataset_helpers "https://github.com/chefmarvin/roux/blob/main/src/utils/dataset.ts"
click node_csv_output "https://github.com/chefmarvin/roux/blob/main/src/output/csv.ts"
click node_json_output "https://github.com/chefmarvin/roux/blob/main/src/output/json.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_app,node_cli_user toneBlue
class node_git_history,node_git_generator,node_log_cache,node_parser_registry,node_git_parser,node_git2_parser,node_rename_parser,node_modifications toneAmber
class node_rename_tracking,node_grouping,node_temporal_grouping,node_team_mapping,node_library_user toneMint
class node_analysis_registry,node_hotspot_analysis,node_coupling_analysis,node_age_analysis,node_collaboration_analysis,node_fragmentation_analysis,node_ownership_analysis,node_other_analyses,node_dataset_helpers toneRose
class node_csv_output,node_json_output toneIndigo
```

## Components

### Entry points

- [CLI](https://github.com/chefmarvin/roux/blob/main/src/cli.ts): `src/cli.ts`
- [Analysis workflow](https://github.com/chefmarvin/roux/blob/main/src/app.ts): `src/app.ts`

### History input

- **Git history**
- [Git log generator](https://github.com/chefmarvin/roux/blob/main/src/git.ts): `src/git.ts`
- [Log cache](https://github.com/chefmarvin/roux/blob/main/src/cache.ts): `src/cache.ts`
- [Parser registry](https://github.com/chefmarvin/roux/blob/main/src/parsers/index.ts): `src/parsers/index.ts`
- [Git parser](https://github.com/chefmarvin/roux/blob/main/src/parsers/git.ts): `src/parsers/git.ts`
- [Git2 parser](https://github.com/chefmarvin/roux/blob/main/src/parsers/git2.ts): `src/parsers/git2.ts`
- [Rename path parser](https://github.com/chefmarvin/roux/blob/main/src/parsers/rename.ts): `src/parsers/rename.ts`
- [Modification records](https://github.com/chefmarvin/roux/blob/main/src/parsers/types.ts): `src/parsers/types.ts`

### Data transforms

- [Rename tracking](https://github.com/chefmarvin/roux/blob/main/src/transforms/rename-tracker.ts): `src/transforms/rename-tracker.ts`
- [Architectural grouping](https://github.com/chefmarvin/roux/blob/main/src/transforms/grouper.ts): `src/transforms/grouper.ts`
- [Temporal grouping](https://github.com/chefmarvin/roux/blob/main/src/transforms/temporal-grouper.ts): `src/transforms/temporal-grouper.ts`
- [Team mapping](https://github.com/chefmarvin/roux/blob/main/src/transforms/team-mapper.ts): `src/transforms/team-mapper.ts`

### Analysis

- [Analysis selection](https://github.com/chefmarvin/roux/blob/main/src/analysis/index.ts): `src/analysis/index.ts`
- [Hotspot and churn](https://github.com/chefmarvin/roux/blob/main/src/analysis/churn.ts): `src/analysis/churn.ts`
- [Coupling](https://github.com/chefmarvin/roux/blob/main/src/analysis/coupling.ts): `src/analysis/coupling.ts`
- [Age](https://github.com/chefmarvin/roux/blob/main/src/analysis/age.ts): `src/analysis/age.ts`
- [Collaboration](https://github.com/chefmarvin/roux/blob/main/src/analysis/communication.ts): `src/analysis/communication.ts`
- [Knowledge fragmentation](https://github.com/chefmarvin/roux/blob/main/src/analysis/fragmentation.ts): `src/analysis/fragmentation.ts`
- [Ownership and effort](https://github.com/chefmarvin/roux/tree/main/src/analysis): `src/analysis`
- [Other analyses](https://github.com/chefmarvin/roux/tree/main/src/analysis): `src/analysis`
- [Dataset helpers](https://github.com/chefmarvin/roux/blob/main/src/utils/dataset.ts): `src/utils/dataset.ts`

### Output

- [CSV formatter](https://github.com/chefmarvin/roux/blob/main/src/output/csv.ts): `src/output/csv.ts`
- [JSON formatter](https://github.com/chefmarvin/roux/blob/main/src/output/json.ts): `src/output/json.ts`

### Other components

- **CLI user**
- **API caller**

## Connections

- CLI user → CLI: invokes (evidence: `src/cli.ts`)
- CLI → Analysis workflow: calls (evidence: `src/cli.ts`)
- API caller → Analysis workflow: calls
- Analysis workflow → Git log generator: generates log (evidence: `src/app.ts`)
- Git log generator → Git history: queries (evidence: `src/git.ts`)
- Git log generator → Log cache: checks cache (evidence: `src/git.ts`)
- Log cache → Git history: queries commits (evidence: `src/cache.ts`)
- Analysis workflow → Parser registry: selects parser (evidence: `src/app.ts`)
- Parser registry → Git parser: registers (evidence: `src/parsers/index.ts`)
- Parser registry → Git2 parser: registers (evidence: `src/parsers/index.ts`)
- Git parser → Rename path parser: parses renames (evidence: `src/parsers/git.ts`)
- Git2 parser → Rename path parser: parses renames (evidence: `src/parsers/git2.ts`)
- Git parser → Modification records: creates records (evidence: `src/parsers/git.ts`)
- Git2 parser → Modification records: creates records (evidence: `src/parsers/git2.ts`)
- Analysis workflow → Rename tracking: tracks renames (evidence: `src/app.ts`)
- Analysis workflow → Architectural grouping: applies groups (evidence: `src/app.ts`)
- Analysis workflow → Temporal grouping: applies periods (evidence: `src/app.ts`)
- Analysis workflow → Team mapping: maps teams (evidence: `src/app.ts`)
- Analysis workflow → Analysis selection: selects analysis (evidence: `src/app.ts`)
- Analysis selection → Hotspot and churn: registers (evidence: `src/analysis/index.ts`)
- Analysis selection → Coupling: registers (evidence: `src/analysis/index.ts`)
- Analysis selection → Age: registers (evidence: `src/analysis/index.ts`)
- Analysis selection → Collaboration: registers (evidence: `src/analysis/index.ts`)
- Analysis selection → Knowledge fragmentation: registers (evidence: `src/analysis/index.ts`)
- Analysis selection → Ownership and effort: registers (evidence: `src/analysis/index.ts`)
- Analysis selection → Other analyses: registers (evidence: `src/analysis/index.ts`)
- Hotspot and churn → Dataset helpers: uses (evidence: `src/analysis/churn.ts`)
- Coupling → Dataset helpers: uses (evidence: `src/analysis/coupling.ts`)
- Age → Dataset helpers: uses (evidence: `src/analysis/age.ts`)
- Collaboration → Dataset helpers: uses (evidence: `src/analysis/communication.ts`)
- Knowledge fragmentation → Dataset helpers: uses (evidence: `src/analysis/fragmentation.ts`)
- Analysis selection → CSV formatter: formats results (evidence: `src/app.ts`)
- Analysis selection → JSON formatter: formats results (evidence: `src/app.ts`)
