# fynnfluegge/doc-comments-ai architecture

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

- Interactive diagram: https://gitdiagram.com/fynnfluegge/doc-comments-ai
- Repository: https://github.com/fynnfluegge/doc-comments-ai

## Overview

##### Project type and purpose
- This is an open-source, CLI-based developer tool (Python package) that generates documentation comments for source files using LLMs and Tree-sitter.
- Key use case: “aicomment <path>” parses your code, sends method signatures and bodies to an LLM (OpenAI/Azure or local via llama.cpp/ollama), and injects generated doc blocks back into the file.

##### Main components
a. CLI entrypoint
- `__main__.py` / `app.py`
- Parses command-line options, resolves flags (–inline, –guided, –gpt4, –local_model, etc.)
b. Core application logic
- `app.py`: orchestrates file I/O, change detection (unstaged changes check), Treesitter parsing, LLM invocation, and patch application.
- `constants.py`, `utils.py`: helper functions and shared constants.
c. Treesitter integration
- `treesitter/treesitter.py` & per-language modules (`treesitter_c.py`, `treesitter_py.py`, …)
- `treesitter_registry.py`: plugin registry that picks the right parser based on file extension.
d. LLM interface
- `llm.py`: abstraction over multiple backends
- OpenAI (GPT-3.5/Turbo, GPT-4)
- Azure OpenAI
- Local llama.cpp (via `llama-cpp-python`)
- Local Ollama
e. File system & patching
- Reads source files, generates AST, extracts method definitions, writes back with inserted docstrings.
f. Tests & CI
- `tests/`: unit tests for parser logic and response parsing.
- GitHub workflows: build and publish pipelines.

##### Relationships and data flow
1) User issues CLI command →
2) CLI parser loads `app.py` →
3) `app.py` invokes Tree-sitter registry to parse file →
4) Extracted code segments passed to `llm.py` →
5) `llm.py` sends prompt to selected LLM backend →
6) LLM returns doc comments →
7) `app.py` applies comments to in-memory AST or text buffer →
8) Writes patched file back to disk.

External dependencies: OpenAI/Azure endpoints or local models (llama.cpp/ollama).

##### Architectural patterns & design principles
- Plugin/strategy pattern for Treesitter language support.
- Adapter pattern for multiple LLM backends behind a single interface.
- Single-responsibility modules: CLI, parsing, LLM communication, utilities.
- Pure-Python CLI application—no frontend or database.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI Entrypoint\n__main__.py"]:::internal
    end

    %% Core Orchestrator
    subgraph "Core App Orchestrator"
        App["Core App Orchestrator\napp.py"]:::internal
        Const["Shared Constants\nconstants.py"]:::internal
        Utils["Utility Functions\nutils.py"]:::internal
    end

    %% Treesitter Modules
    subgraph "Treesitter Registry & Parsers"
        Reg["Treesitter Registry\ntreesitter_registry.py"]:::internal
        subgraph "Language Parsers"
            TCore["Core API\ntreesitter.py"]:::internal
            TC["C\ntreesitter_c.py"]:::internal
            TCP["C++\ntreesitter_cpp.py"]:::internal
            TCS["C#\ntreesitter_cs.py"]:::internal
            TG["Go\ntreesitter_go.py"]:::internal
            THS["Haskell\ntreesitter_hs.py"]:::internal
            TJ["Java\ntreesitter_java.py"]:::internal
            TJS["JavaScript\ntreesitter_js.py"]:::internal
            TTS["TypeScript\ntreesitter_ts.py"]:::internal
            TKT["Kotlin\ntreesitter_kt.py"]:::internal
            TPY["Python\ntreesitter_py.py"]:::internal
            TRS["Rust\ntreesitter_rs.py"]:::internal
        end
    end

    %% LLM Interface and Backends
    subgraph "LLM Interface & Backends"
        LLM["LLM Interface\nllm.py"]:::internal
        OpenAI[(OpenAI API)]:::external
        Azure[(Azure OpenAI)]:::external
        Local1[(llama.cpp)]:::external
        Local2[(Ollama)]:::external
    end

    %% File System & Patching
    subgraph "File System & Patcher"
        FS["File System & Patch\n(file I/O)"]:::fs
    end

    %% Tests & CI
    subgraph "Tests & CI"
        TT["treesitter_query_test.py"]:::test
        RP["response_parser_test.py"]:::test
        Fixtures["fixtures/"]:::test
        Build[".github/workflows/build.yaml"]:::test
        Publish[".github/workflows/publish.yaml"]:::test
    end

    %% Data Flow
    CLI -->|"invokes"| App
    App -->|"uses"| Reg
    Reg -->|"dispatch"| TCore
    TCore -->|"parses AST"| TC
    TCore -->|"parses AST"| TCP
    TCore -->|"parses AST"| TCS
    TCore -->|"parses AST"| TG
    TCore -->|"parses AST"| THS
    TCore -->|"parses AST"| TJ
    TCore -->|"parses AST"| TJS
    TCore -->|"parses AST"| TTS
    TCore -->|"parses AST"| TKT
    TCore -->|"parses AST"| TPY
    TCore -->|"parses AST"| TRS
    App -->|"extracts segments"| LLM
    LLM -->|"prompt+code"| OpenAI
    LLM -->|"prompt+code"| Azure
    LLM -->|"prompt+code"| Local1
    LLM -->|"prompt+code"| Local2
    OpenAI -->|"doc comments"| App
    Azure -->|"doc comments"| App
    Local1 -->|"doc comments"| App
    Local2 -->|"doc comments"| App
    App -->|"applies patches"| FS

    %% Utility Dependencies
    App -.->|"refs"| Const
    App -.->|"uses"| Utils

    %% Tests & CI Flows
    TT -.-> App
    RP -.-> App
    Fixtures -.-> App
    Build -.-> Publish

    %% Click Events
    click CLI "https://github.com/fynnfluegge/doc-comments-ai/blob/main/doc_comments_ai/__main__.py"
    click App "https://github.com/fynnfluegge/doc-comments-ai/blob/main/doc_comments_ai/app.py"
    click Const "https://github.com/fynnfluegge/doc-comments-ai/blob/main/doc_comments_ai/constants.py"
    click Utils "https://github.com/fynnfluegge/doc-comments-ai/blob/main/doc_comments_ai/utils.py"
    click LLM "https://github.com/fynnfluegge/doc-comments-ai/blob/main/doc_comments_ai/llm.py"
    click TCore "https://github.com/fynnfluegge/doc-comments-ai/blob/main/doc_comments_ai/treesitter/treesitter.py"
    click TC "https://github.com/fynnfluegge/doc-comments-ai/blob/main/doc_comments_ai/treesitter/treesitter_c.py"
    click TCP "https://github.com/fynnfluegge/doc-comments-ai/blob/main/doc_comments_ai/treesitter/treesitter_cpp.py"
    click TCS "https://github.com/fynnfluegge/doc-comments-ai/blob/main/doc_comments_ai/treesitter/treesitter_cs.py"
    click TG "https://github.com/fynnfluegge/doc-comments-ai/blob/main/doc_comments_ai/treesitter/treesitter_go.py"
    click THS "https://github.com/fynnfluegge/doc-comments-ai/blob/main/doc_comments_ai/treesitter/treesitter_hs.py"
    click TJ "https://github.com/fynnfluegge/doc-comments-ai/blob/main/doc_comments_ai/treesitter/treesitter_java.py"
    click TJS "https://github.com/fynnfluegge/doc-comments-ai/blob/main/doc_comments_ai/treesitter/treesitter_js.py"
    click TTS "https://github.com/fynnfluegge/doc-comments-ai/blob/main/doc_comments_ai/treesitter/treesitter_ts.py"
    click TKT "https://github.com/fynnfluegge/doc-comments-ai/blob/main/doc_comments_ai/treesitter/treesitter_kt.py"
    click TPY "https://github.com/fynnfluegge/doc-comments-ai/blob/main/doc_comments_ai/treesitter/treesitter_py.py"
    click TRS "https://github.com/fynnfluegge/doc-comments-ai/blob/main/doc_comments_ai/treesitter/treesitter_rs.py"
    click Reg "https://github.com/fynnfluegge/doc-comments-ai/blob/main/doc_comments_ai/treesitter/treesitter_registry.py"
    click TT "https://github.com/fynnfluegge/doc-comments-ai/blob/main/tests/treesitter_query_test.py"
    click RP "https://github.com/fynnfluegge/doc-comments-ai/blob/main/tests/response_parser_test.py"
    click Fixtures "https://github.com/fynnfluegge/doc-comments-ai/tree/main/tests/fixtures/"
    click Build "https://github.com/fynnfluegge/doc-comments-ai/blob/main/.github/workflows/build.yaml"
    click Publish "https://github.com/fynnfluegge/doc-comments-ai/blob/main/.github/workflows/publish.yaml"

    %% Styles
    classDef internal fill:#add8e6,stroke:#000,stroke-width:1px
    classDef external fill:#90ee90,stroke:#000,stroke-width:1px
    classDef fs fill:#ffffe0,stroke:#000,stroke-width:1px
    classDef test fill:#f5f5f5,stroke:#000,stroke-width:1px
```
