# contrastoai/cartai architecture

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

- Interactive diagram: https://gitdiagram.com/contrastoai/cartai
- Repository: https://github.com/contrastoai/cartai

## Overview

##### Project type and purpose
- CartAI is a Python-based command-line tool whose primary purpose is to generate end-to-end documentation (e.g. README files, PR diffs) through code parsing and large-language-model (LLM) integration.

##### File structure
- Top-level directories:
- cartai/ (the main package)
– cli/ (CLI entrypoint & commands)
– core/ (domain logic: code parsing)
– llm_agents/ (LLM wrappers, templating, utilities)
- examples/ (Jupyter notebooks demonstrating usage)
- tests/ (unit tests)
- Configuration & tooling: Makefile, pyproject.toml, pre-commit, .python-version
- No separate “frontend” or “backend”—it’s a single CLI application with layered modules.

##### Key insights from the README
- The workflow: user invokes a Makefile/CLI command → CartAI parses code → CartAI builds prompts via Jinja templates → CartAI calls an external LLM API → CartAI outputs documentation files.

##### Main components
a. CLI Layer
- Entrypoint (main.py)
- Commands: readme, pr_diff
b. Core Layer
- code_parser.py (ingests user code, AST extraction, metrics)
c. LLM Agents Layer
- documenter.py (orchestrates prompt construction & LLM calls)
- utils.py (shared helpers)
- templates/ (readme.jinja, pr_diff.jinja)
d. External Services
- LLM API (e.g. OpenAI)
e. File System
- Input: user’s codebase (src files)
- Output: generated docs (README_new.md, PR summaries)
f. Supporting Infrastructure
- Tests (unit tests under tests/)
- CI workflows (.github/workflows)
- Pre-commit & linting

##### Relationships & data flow
1) User runs `make run_readme` or `cartai readme` → invokes CLI Layer
2) CLI Layer calls Core Layer to parse source code
3) Core Layer returns parsed data structures to LLM Agents Layer
4) LLM Agents Layer fills Jinja templates with parsed data → generates prompt
5) LLM Agents Layer sends prompt to External LLM API, receives response
6) CLI Layer writes response to file system (e.g. README_new.md)
7) Tests validate Core & LLM Agents modules in isolation

##### Architectural patterns & design principles
- Layered architecture (Presentation/CLI → Domain/Core → Integration/LLM Agents → Infrastructure/API)
- Adapter pattern (wrapping the external LLM API behind documenter.py)
- Command pattern (each CLI command is a discrete unit in cartai/cli/commands)
- Template-driven design (Jinja templates define prompt structure and output format)

##### Technologies & frameworks
- Python 3.x
- Click (or built-in argparse) for CLI (main.py)
- Jinja2 for templating
- pytest for testing
- pre-commit, uv for quality & dependency management

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        Entrypoint["main.py"]:::internal
        ReadmeCmd["readme.py"]:::internal
        PRDiffCmd["pr_diff.py"]:::internal
    end

    %% Core Layer
    subgraph "Core Layer"
        CodeParser["code_parser.py"]:::internal
    end

    %% LLM Agents Layer
    subgraph "LLM Agents Layer"
        Documenter["documenter.py"]:::internal
        Utils["utils.py"]:::internal
        subgraph "Templates"
            ReadmeTpl["readme.jinja"]:::internal
            PRDiffTpl["pr_diff.jinja"]:::internal
        end
    end

    %% External Service
    LLMAPI["LLM API"]:::external-service

    %% File System
    subgraph "File System"
        UserCode["User Codebase"]:::fs
        GeneratedDocs["Generated Docs"]:::fs
    end

    %% Examples
    subgraph "Examples"
        Notebook00["00_prompt_templ_parser.ipynb"]:::fs
        Notebook01["01_code_parser.ipynb"]:::fs
        Notebook02["02_pr_diff.ipynb"]:::fs
    end

    %% Supporting Infrastructure
    subgraph "Supporting Infrastructure"
        Conftest["conftest.py"]:::infra
        TestDoc["test_documenter.py"]:::infra
        CIWorkflows["GitHub Workflows"]:::infra
        PreCommit[".pre-commit-config.yaml"]:::infra
        MakefileNode["Makefile"]:::infra
        PyProject["pyproject.toml"]:::infra
    end

    %% Relationships
    MakefileNode -->|"run_readme / run_pr_diff"| Entrypoint
    Entrypoint -->|"dispatch command"| ReadmeCmd
    Entrypoint -->|"dispatch command"| PRDiffCmd
    ReadmeCmd -->|"parse source"| CodeParser
    PRDiffCmd -->|"parse source"| CodeParser
    CodeParser -->|"parsed AST"| Documenter
    Documenter -->|"load templates"| ReadmeTpl
    Documenter -->|"load templates"| PRDiffTpl
    Documenter -->|"prompt"| LLMAPI
    LLMAPI -->|"response"| Documenter
    Documenter -->|"generate docs"| GeneratedDocs
    ReadmeCmd -->|"write file"| GeneratedDocs
    PRDiffCmd -->|"write file"| GeneratedDocs
    CodeParser -->|"validate"| Conftest
    Documenter -->|"validate"| TestDoc

    Notebook00 --> UserCode
    Notebook01 --> CodeParser
    Notebook02 --> PRDiffCmd

    CIWorkflows -->|uses| Conftest
    CIWorkflows -->|uses| TestDoc
    CIWorkflows -->|enforces| PreCommit

    %% Click Events
    click Entrypoint "https://github.com/contrastoai/cartai/blob/main/cartai/cli/main.py"
    click ReadmeCmd "https://github.com/contrastoai/cartai/blob/main/cartai/cli/commands/readme.py"
    click PRDiffCmd "https://github.com/contrastoai/cartai/blob/main/cartai/cli/commands/pr_diff.py"
    click CodeParser "https://github.com/contrastoai/cartai/blob/main/cartai/core/code_parser.py"
    click Documenter "https://github.com/contrastoai/cartai/blob/main/cartai/llm_agents/documenter.py"
    click Utils "https://github.com/contrastoai/cartai/blob/main/cartai/llm_agents/utils.py"
    click ReadmeTpl "https://github.com/contrastoai/cartai/blob/main/cartai/llm_agents/templates/readme.jinja"
    click PRDiffTpl "https://github.com/contrastoai/cartai/blob/main/cartai/llm_agents/templates/pr_diff.jinja"
    click Notebook00 "https://github.com/contrastoai/cartai/blob/main/examples/00_prompt_templ_parser.ipynb"
    click Notebook01 "https://github.com/contrastoai/cartai/blob/main/examples/01_code_parser.ipynb"
    click Notebook02 "https://github.com/contrastoai/cartai/blob/main/examples/02_pr_diff.ipynb"
    click Conftest "https://github.com/contrastoai/cartai/blob/main/tests/unit/conftest.py"
    click TestDoc "https://github.com/contrastoai/cartai/blob/main/tests/unit/llm_agents/test_documenter.py"
    click CIWorkflows "https://github.com/contrastoai/cartai/blob/main/.github/workflows/pre-commit.yaml"
    click PreCommit "https://github.com/contrastoai/cartai/blob/main/.pre-commit-config.yaml"
    click MakefileNode "https://github.com/contrastoai/cartai/tree/main/Makefile"
    click PyProject "https://github.com/contrastoai/cartai/blob/main/pyproject.toml"

    %% Styles
    classDef internal fill:#AED6F1,stroke:#1B4F72,color:#1B2631
    classDef external-service fill:#A9DFBF,stroke:#145A32,color:#0B5345
    classDef fs fill:#D5D8DC,stroke:#566573,color:#212F3D
    classDef infra fill:#F5B041,stroke:#B9770E,color:#7E5109
```
