# highkay/codereview-agent architecture

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

- Interactive diagram: https://gitdiagram.com/highkay/codereview-agent
- Repository: https://github.com/highkay/codereview-agent

## Overview

##### Main Components
- API Server (FastAPI): This is the central hub of the system, handling both webhooks and configuration UI endpoints.
- Webhook Handler: Represented by the “webhooks.py” router, this component receives Pull Request events from Gitea.
- Configuration UI: Found under “config_ui.py” and served via templates (e.g., “config.html”) and static assets – this allows users to set up system parameters like Gitea URL, API tokens, and LLM settings.
- Core Business Logic:
- Code Review Agent (agent.py): The heart of the application, which orchestrates receiving SCM data, delegating the review analysis, and generating comments.
- SCM Module (scm.py): Abstracts interactions with the source control manager (Gitea), fetching code changes and other metadata.
- LLM Service (llm_service.py): A dedicated service that communicates with third-party LLM providers (e.g., OpenAI’s GPT-4-turbo) to perform the heavy lifting of evaluating code on multiple dimensions (security, performance, readability, best practices).

##### Relationships and Data Flow
- The Webhook Handler parses the event and passes the code changes to the Code Review Agent (agent.py) within the core.
- The Code Review Agent uses the SCM Module to fetch or validate commit details, and then delegates the actual analysis to the LLM Service.
- For configuration changes, the Configuration UI component allows users to set parameters, which are then reflected in the configuration data models and YAML config file.

##### Architectural Patterns and Design Principles
- Modular Design: Separation into routers (for HTTP endpoints), core (business logic), services (external API interactions), and models (data structures).
- Separation of Concerns: Each module handles its own responsibility – webhook event handling, LLM service communication, SCM interactions, and UI display.
- Extensibility: The design makes it straightforward to add additional services or extend current functionality by maintaining clear boundaries between modules.

##### Technologies and Frameworks
- FastAPI: For the web server and API routing.
- HTMX and TailwindCSS: Used in the configuration UI (as mentioned in the README).
- LiteLLM (or a similar LLM provider SDK): Employed in the LLM service for performing code review analysis.
- Docker: A Dockerfile is present indicating containerization for consistent deployments.
- GitHub Actions: CI/CD workflow configured in .github/workflows/docker-build.yml.

## Diagram (Mermaid)

```mermaid
flowchart TD
    GITEA["Gitea (Pull Request)"]:::blue
    API["API Server (FastAPI)"]:::blue
    WH["Webhook Handler (webhooks.py)"]:::blue
    CUI["Configuration UI (config_ui.py, config.html)"]:::blue
    CRA["Code Review Agent (agent.py)"]:::green
    SCM["SCM Module (scm.py)"]:::green
    LLM["LLM Service (llm_service.py)"]:::green
    EXT["External LLM Provider"]:::orange
    CFG["Configuration Data Models (config.py)"]:::grey

    GITEA -->|"POST_webhook"| API
    API -->|"routes_to"| WH
    API -->|"routes_to"| CUI
    WH -->|"passes_event_to"| CRA
    CRA -->|"fetches_via"| SCM
    CRA -->|"delegates_review_to"| LLM
    LLM -->|"calls"| EXT
    CUI -->|"updates"| CFG

    click API "https://github.com/highkay/codereview-agent/blob/main/app/main.py"
    click WH "https://github.com/highkay/codereview-agent/blob/main/app/routers/webhooks.py"
    click CUI "https://github.com/highkay/codereview-agent/blob/main/app/routers/config_ui.py"
    click CUI "https://github.com/highkay/codereview-agent/blob/main/app/templates/config.html"
    click CRA "https://github.com/highkay/codereview-agent/blob/main/app/core/agent.py"
    click SCM "https://github.com/highkay/codereview-agent/blob/main/app/core/scm.py"
    click LLM "https://github.com/highkay/codereview-agent/blob/main/app/services/llm_service.py"
    click CFG "https://github.com/highkay/codereview-agent/blob/main/app/models/config.py"

    classDef blue fill:#AED6F1,stroke:#2471A3,color:#000;
    classDef green fill:#A9DFBF,stroke:#145A32,color:#000;
    classDef orange fill:#F9E79F,stroke:#D4AC0D,color:#000;
    classDef grey fill:#D5D8DC,stroke:#566573,color:#000;
```
