# facebookresearch/docagent architecture

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

- Interactive diagram: https://gitdiagram.com/facebookresearch/docagent
- Repository: https://github.com/facebookresearch/docagent

## Overview

##### Project type and purpose
- DocAgent is a Python-based, full-stack system for automated, context-aware docstring generation. It provides both a CLI and a web UI for driving a multi-agent pipeline that reads a codebase, orchestrates a set of specialized agents (Reader, Searcher, Writer, Verifier), invokes external LLMs, and writes high-quality docstrings back into the code. It also includes a separate evaluation subsystem with its own web UI to assess docstring quality.

##### File structure
- Top-level “generate_docstrings.py” and “run_web_ui.py” launch the generation pipeline (CLI vs. web).
- “config/example_config.yaml” → user config for LLM endpoints, model names, API keys.
- “src/agent” → core agent framework: Orchestrator + four agent types + LLM factory and rate limiter.
- “src/dependency_analyzer” → builds file dependency DAG to traverse code hierarchically.
- “src/data/parse” → helpers for downloading repos, building AST, normalizing data.
- “src/evaluator” + “src/visualizer” → static analyzers (completeness, helpfulness, truthfulness) and progress/status display code.
- “src/web” → Flask app for generation UI (static assets + JS + HTML templates).
- “src/web_eval” → separate Flask app for evaluation UI.

##### README for additional insights
- Methodology: hierarchical traversal (dependency_analyzer) + agentic system (agent orchestrator + four agents).

##### Main components and their interactions
a. Configuration loader
- Reads “config/agent_config.yaml” → provides LLM endpoints, model names, generation settings.
b. Entry points
- CLI: generate_docstrings.py
- Web UI: run_web_ui.py → Flask app (src/web/app.py)
- Evaluation Web UI: src/web_eval/app.py
c. Core pipeline
- Orchestrator (src/agent/orchestrator.py)
– Calls dependency_analyzer to sort files
– For each file/module:
· Reader (loads code, builds AST context)
· Searcher (external/internal context retrieval)
· Writer (formulates prompts, calls LLM via LLMFactory)
· Verifier (validates and refines docstrings)
d. LLM abstraction
- LLMFactory routes to openai_llm, claude_llm, gemini_llm, huggingface_llm
- Rate limiter module throttles calls
e. Persistence & output
- Docstrings are injected back into source files
- CLI logs or Web UI progress shown by visualizer modules
f. Evaluation subsystem
- Evaluator modules compute completeness, helpfulness, truthfulness
- Web-based UI shows metrics and allows manual review

##### Architectural patterns & design principles
- Layered architecture:
- Presentation layer: CLI & two web UIs (Flask + static frontend)
- Application layer: Orchestrator and agents
- Service layer: LLM adapters, AST tools, dependency analyzer
- Data layer: file I/O, configuration, evaluation outputs
- Modular, single-responsibility agents
- Dependency-driven (hierarchical) traversal to maximize context accuracy
- Clear separation of concerns between generation vs. evaluation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration
    Config["Configuration Loader\nconfig/example_config.yaml"]:::data

    %% Entry Points
    CLI["CLI\ngenerate_docstrings.py"]:::ui
    GenWebLauncher["Gen Web UI Launcher\nrun_web_ui.py"]:::ui
    GenWebApp["Generation Web UI\nFlask App\nsrc/web/app.py"]:::ui
    GHConfig["Web UI Config Handler\nsrc/web/config_handler.py"]:::ui
    GHProcess["Web UI Process Handler\nsrc/web/process_handler.py"]:::ui
    GHStatic["Static Assets\nsrc/web/static"]:::ui
    GHTemplate["Template\nsrc/web/templates/index.html"]:::ui

    EvalWebApp["Evaluation Web UI\nFlask App\nsrc/web_eval/app.py"]:::ui
    EvalHelpers["Eval Helpers\nsrc/web_eval/helpers.py"]:::ui
    EvalTpl1["Template\nsrc/web_eval/templates/index.html"]:::ui
    EvalTpl2["Template\nsrc/web_eval/templates/results.html"]:::ui

    %% Core Pipeline
    subgraph "Core Pipeline" 
        direction TB
        Orchestrator["Orchestrator\nsrc/agent/orchestrator.py"]:::core
        Reader["Reader Agent\nsrc/agent/reader.py"]:::core
        Searcher["Searcher Agent\nsrc/agent/searcher.py"]:::core
        Writer["Writer Agent\nsrc/agent/writer.py"]:::core
        Verifier["Verifier Agent\nsrc/agent/verifier.py"]:::core
        Workflow["Agent Workflow\nsrc/agent/workflow.py"]:::core
    end

    %% LLM Providers
    subgraph "LLM Services" 
        direction TB
        LLMFactory["LLM Factory\nsrc/agent/llm/factory.py"]:::external
        OpenAI["OpenAI Adapter\nsrc/agent/llm/openai_llm.py"]:::external
        Claude["Claude Adapter\nsrc/agent/llm/claude_llm.py"]:::external
        Gemini["Gemini Adapter\nsrc/agent/llm/gemini_llm.py"]:::external
        HF["HuggingFace Adapter\nsrc/agent/llm/huggingface_llm.py"]:::external
        BaseLLM["LLM Base\nsrc/agent/llm/base.py"]:::external
        RateLimiter["Rate Limiter\nsrc/agent/llm/rate_limiter.py"]:::external
    end

    %% Preprocessing & Data
    subgraph "Dependency Analyzer" 
        direction TB
        AST["AST Parser\nsrc/dependency_analyzer/ast_parser.py"]:::data
        Topo["Topo Sort\nsrc/dependency_analyzer/topo_sort.py"]:::data
    end

    subgraph "Data Parsing Helpers" 
        direction TB
        DataProc["Data Processor\nsrc/data/parse/data_process.py"]:::data
        Downloader["Downloader\nsrc/data/parse/downloader.py"]:::data
        RepoTree["Repo Tree\nsrc/data/parse/repo_tree.py"]:::data
    end

    %% Evaluation Subsystem
    subgraph "Evaluation" 
        direction TB
        EvaluatorBase["Evaluator Base\nsrc/evaluator/base.py"]:::eval
        Completeness["Completeness\nsrc/evaluator/completeness.py"]:::eval
        Helpfulness["Helpfulness\nsrc/evaluator/helpfulness_*.py"]:::eval
        Truthfulness["Truthfulness\nsrc/evaluator/truthfulness.py"]:::eval
    end

    subgraph "Visualizer" 
        direction TB
        Progress["Progress\nsrc/visualizer/progress.py"]:::core
        Status["Status\nsrc/visualizer/status.py"]:::core
        WebBridge["Web Bridge\nsrc/visualizer/web_bridge.py"]:::core
    end

    %% Connections
    Config --> Orchestrator
    Config --> GenWebApp
    Config --> EvalWebApp

    CLI --> Orchestrator
    GenWebLauncher --> GenWebApp
    GenWebApp --> GHConfig
    GenWebApp --> GHProcess
    GenWebApp --> GHStatic
    GenWebApp --> GHTemplate

    GenWebApp --> Orchestrator

    Orchestrator --> Renderer1[/"Dependency Order"/]:::data
    Renderer1 --> AST
    Renderer1 --> Topo
    AST --> Reader
    Topo --> Reader

    DataProc --> Reader
    Downloader --> Reader
    RepoTree --> Reader

    Orchestrator --> Workflow
    Workflow --> Reader
    Reader --> Searcher
    Searcher --> Writer
    Writer --> LLMFactory
    LLMFactory --> BaseLLM
    LLMFactory --> OpenAI
    LLMFactory --> Claude
    LLMFactory --> Gemini
    LLMFactory --> HF
    LLMFactory --> RateLimiter
    RateLimiter --> OpenAI
    RateLimiter --> Claude
    RateLimiter --> Gemini
    RateLimiter --> HF

    Writer --> Verifier
    Verifier --> FileSystem["Source Files\nInjected Docstrings"]:::data

    Orchestrator --> Progress
    Orchestrator --> Status
    Progress --> GenWebApp
    Status --> GenWebApp
    Progress --> CLI
    Status --> CLI

    EvalWebApp --> EvaluatorBase
    EvaluatorBase --> Completeness
    EvaluatorBase --> Helpfulness
    EvaluatorBase --> Truthfulness
    Completeness --> EvalWebApp
    Helpfulness --> EvalWebApp
    Truthfulness --> EvalWebApp

    EvalWebApp --> EvalHelpers
    EvalWebApp --> EvalTpl1
    EvalWebApp --> EvalTpl2

    %% Click Events
    click Config "https://github.com/facebookresearch/docagent/blob/main/config/example_config.yaml"
    click CLI "https://github.com/facebookresearch/docagent/blob/main/generate_docstrings.py"
    click GenWebLauncher "https://github.com/facebookresearch/docagent/blob/main/run_web_ui.py"
    click GenWebApp "https://github.com/facebookresearch/docagent/blob/main/src/web/app.py"
    click GHConfig "https://github.com/facebookresearch/docagent/blob/main/src/web/config_handler.py"
    click GHProcess "https://github.com/facebookresearch/docagent/blob/main/src/web/process_handler.py"
    click GHStatic "https://github.com/facebookresearch/docagent/tree/main/src/web/static"
    click GHTemplate "https://github.com/facebookresearch/docagent/blob/main/src/web/templates/index.html"
    click EvalWebApp "https://github.com/facebookresearch/docagent/blob/main/src/web_eval/app.py"
    click EvalHelpers "https://github.com/facebookresearch/docagent/blob/main/src/web_eval/helpers.py"
    click EvalTpl1 "https://github.com/facebookresearch/docagent/blob/main/src/web_eval/templates/index.html"
    click EvalTpl2 "https://github.com/facebookresearch/docagent/blob/main/src/web_eval/templates/results.html"
    click Orchestrator "https://github.com/facebookresearch/docagent/blob/main/src/agent/orchestrator.py"
    click Reader "https://github.com/facebookresearch/docagent/blob/main/src/agent/reader.py"
    click Searcher "https://github.com/facebookresearch/docagent/blob/main/src/agent/searcher.py"
    click Writer "https://github.com/facebookresearch/docagent/blob/main/src/agent/writer.py"
    click Verifier "https://github.com/facebookresearch/docagent/blob/main/src/agent/verifier.py"
    click Workflow "https://github.com/facebookresearch/docagent/blob/main/src/agent/workflow.py"
    click LLMFactory "https://github.com/facebookresearch/docagent/blob/main/src/agent/llm/factory.py"
    click OpenAI "https://github.com/facebookresearch/docagent/blob/main/src/agent/llm/openai_llm.py"
    click Claude "https://github.com/facebookresearch/docagent/blob/main/src/agent/llm/claude_llm.py"
    click Gemini "https://github.com/facebookresearch/docagent/blob/main/src/agent/llm/gemini_llm.py"
    click HF "https://github.com/facebookresearch/docagent/blob/main/src/agent/llm/huggingface_llm.py"
    click BaseLLM "https://github.com/facebookresearch/docagent/blob/main/src/agent/llm/base.py"
    click RateLimiter "https://github.com/facebookresearch/docagent/blob/main/src/agent/llm/rate_limiter.py"
    click AST "https://github.com/facebookresearch/docagent/blob/main/src/dependency_analyzer/ast_parser.py"
    click Topo "https://github.com/facebookresearch/docagent/blob/main/src/dependency_analyzer/topo_sort.py"
    click DataProc "https://github.com/facebookresearch/docagent/blob/main/src/data/parse/data_process.py"
    click Downloader "https://github.com/facebookresearch/docagent/blob/main/src/data/parse/downloader.py"
    click RepoTree "https://github.com/facebookresearch/docagent/blob/main/src/data/parse/repo_tree.py"
    click Completeness "https://github.com/facebookresearch/docagent/blob/main/src/evaluator/completeness.py"
    click Helpfulness "https://github.com/facebookresearch/docagent/blob/main/src/evaluator/helpfulness_*.py"
    click Truthfulness "https://github.com/facebookresearch/docagent/blob/main/src/evaluator/truthfulness.py"
    click EvaluatorBase "https://github.com/facebookresearch/docagent/blob/main/src/evaluator/base.py"
    click Progress "https://github.com/facebookresearch/docagent/blob/main/src/visualizer/progress.py"
    click Status "https://github.com/facebookresearch/docagent/blob/main/src/visualizer/status.py"
    click WebBridge "https://github.com/facebookresearch/docagent/blob/main/src/visualizer/web_bridge.py"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#333,stroke-width:1px;
    classDef core fill:#D2F8D2,stroke:#333,stroke-width:1px;
    classDef external fill:#FFD8B0,stroke:#333,stroke-width:1px;
    classDef data fill:#FFF4C1,stroke:#333,stroke-width:1px;
    classDef eval fill:#F0D0FF,stroke:#333,stroke-width:1px;
```
