# sunmh207/ai-codereview-gitlab architecture

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

- Interactive diagram: https://gitdiagram.com/sunmh207/ai-codereview-gitlab
- Repository: https://github.com/sunmh207/ai-codereview-gitlab

## Overview

##### Project type and purpose
- This is a backend‐centric, event‑driven code‑review tool with a lightweight web dashboard. It exposes an HTTP API for webhook callbacks (api.py), processes review tasks in a worker (biz/queue/worker.py), and hosts a Streamlit UI (ui.py) for monitoring and reporting. It integrates with GitLab/GitHub, multiple LLM providers, and enterprise IM services.

##### File structure
- Top‑level:
- api.py – HTTP entry point for webhooks and manual CLI commands.
- ui.py – Streamlit dashboard.
- biz/ – business logic subdivided into:
– cmd/ – CLI commands (review, complex metrics, directory scan, etc.)
– github/ & gitlab/ – webhook handlers.
– event/ – central EventManager for dispatching review events.
– llm/ – factory and client adapters for multiple LLM providers.
– queue/ – worker that consumes tasks.
– service/ – core review orchestration (review_service.py).
– utils/ – helpers (code parsing, config, IM notifications, logging, queue abstraction).
- conf/ – .env templates, prompt templates, supervisord configs.
- docker-compose.yml & Dockerfile – containerization.

##### README insights
- The flow: GitLab/GitHub → webhook → API → enqueue review task → worker → LLM call → post back to MR/Commit → push notifications → dashboard/logging.
- Supports multiple providers (DeepSeek, OpenAI, etc.) and multiple IM channels (DingTalk, Feishu, WeCom).

##### Diagramming the architecture
a. Main components:
- External Systems: GitLab/GitHub, LLM Providers, IM Platforms (DingTalk, Feishu, WeCom)
- API Service (api.py + biz/github + biz/gitlab + biz/event)
- Task Queue (biz/utils/queue + supervisord.worker)
- Worker Service (biz/queue/worker + biz/service/review_service + biz/llm)
- Configuration Store (conf/.env, prompt_templates.yml)
- Data Store (log files under log/, optional local file storage)
- Dashboard UI (ui.py + biz/utils/reporter)
- CLI Tool (python -m biz.cmd.review)

b. Relationships & data flow:
1. GitLab/GitHub sends webhook → API Service
2. API parses event → EventManager → enqueues a Review Task into the Task Queue
3. Worker Service pulls task → CodeParser & CodeReviewer → ReviewService → chooses LLM Client via Factory → sends code to LLM Provider → receives review results
4. Worker posts results via webhook API back to GitLab/GitHub MR or Commit Note
5. Worker pushes notifications to IM services via Notifier utils
6. Dashboard polls or subscribes to log data / uses Reporter utils to display metrics

c. Architectural patterns & principles:
- Event‑driven / Pub‑Sub between API and Worker
- Adapter pattern for LLM client interfaces
- Separation of concerns: Webhook handling, business logic, third‑party integrations, presentation
- Supervisord to orchestrate independent processes (API, Worker)
- Containerization for consistent deployment

d. Key technologies & frameworks:
- Python 3.10+, Flask or similar HTTP framework in api.py
- Streamlit for UI
- Docker & docker-compose
- Supervisord for process management
- YAML for prompt templates & configs
- HTTP/Webhook integrations with GitLab/GitHub
- REST calls to LLM providers and IM webhooks

##### Essential elements
- Clear component labels (e.g., “GitLab Webhook Handler”, “ReviewService”)
- Deployment context (Docker containers, ports)
- Process manager (supervisord) overseeing API & Worker
- Config layer feeding all components

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "External Systems"
        Gitlab["GitLab/GitHub"]:::external
        LLM["LLM Providers"]:::external
        IM["IM Services (DingTalk, Feishu, WeCom)"]:::external
    end

    subgraph "Configuration Store" 
        Env[".env.dist"]:::config
        Templates["prompt_templates.yml"]:::config
        SupervisordApp["supervisord.app.conf"]:::config
        SupervisordWorker["supervisord.worker.conf"]:::config
    end

    subgraph "Containerization"
        DockerCompose["docker-compose.yml"]:::config
        Dockerfile["Dockerfile"]:::config
    end

    subgraph "API Process (port 5001)"
        API["API Service (api.py)"]:::service
        GHHandler["GitHub Webhook Handler"]:::service
        GLHandler["GitLab Webhook Handler"]:::service
        EventMgr["Event Manager"]:::service
    end

    subgraph "Worker Process"
        Worker["Task Queue Worker"]:::service
        QueueUtil["Queue Abstraction"]:::service
        CodeParser["Code Parser"]:::service
        CodeReviewer["Code Reviewer"]:::service
        ReviewService["ReviewService"]:::service
        LLMFactory["LLM Factory"]:::service
        subgraph "LLM Clients"
            BaseClient["Base Client"]:::service
            Deepseek["DeepSeek Adapter"]:::service
            Ollama["Ollama Adapter"]:::service
            OpenAI["OpenAI Adapter"]:::service
            Qwen["Qwen Adapter"]:::service
            ZhipuAI["Zhipu AI Adapter"]:::service
        end
    end

    subgraph "Dashboard Process (port 5002)"
        UI["Dashboard UI (ui.py)"]:::service
        Reporter["Reporter Utils"]:::service
    end

    subgraph "CLI Tool"
        CLI["CLI (biz/cmd/review.py)"]:::service
    end

    Gitlab -->|"POST /review/webhook"| API
    API -->|"route event"| GHHandler
    API -->|"route event"| GLHandler
    GHHandler --> EventMgr
    GLHandler --> EventMgr
    API --> EventMgr
    EventMgr -->|"enqueue Task"| QueueUtil
    QueueUtil --> Worker
    Worker --> CodeParser
    Worker --> CodeReviewer
    CodeReviewer --> ReviewService
    ReviewService --> LLMFactory
    LLMFactory --> BaseClient
    LLMFactory --> Deepseek
    LLMFactory --> Ollama
    LLMFactory --> OpenAI
    LLMFactory --> Qwen
    LLMFactory --> ZhipuAI
    BaseClient -->|REST| LLM
    Deepseek -->|REST| LLM
    Ollama -->|REST| LLM
    OpenAI -->|REST| LLM
    Qwen -->|REST| LLM
    ZhipuAI -->|REST| LLM
    ReviewService -->|POST review results| Gitlab
    ReviewService -->|send notifications| IM
    Worker -->|log/metrics| Reporter
    Reporter --> UI
    CLI -->|invoke ReviewService| ReviewService
    CLI --> Reporter

    Env --> API
    Templates --> API
    SupervisordApp --> API
    SupervisordApp --> UI
    Env --> Worker
    Templates --> Worker
    SupervisordWorker --> Worker
    DockerCompose --> API
    DockerCompose --> Worker
    DockerCompose --> UI
    Dockerfile --> API
    Dockerfile --> Worker
    Dockerfile --> UI

    classDef external fill:#a2fca0,stroke:#333,stroke-width:1px
    classDef service fill:#9ec1cf,stroke:#333,stroke-width:1px
    classDef config fill:#fddfae,stroke:#333,stroke-width:1px

    click API "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/api.py"
    click GHHandler "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/biz/github/webhook_handler.py"
    click GLHandler "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/biz/gitlab/webhook_handler.py"
    click EventMgr "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/biz/event/event_manager.py"
    click CLI "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/biz/cmd/review.py"
    click Worker "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/biz/queue/worker.py"
    click ReviewService "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/biz/service/review_service.py"
    click LLMFactory "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/biz/llm/factory.py"
    click BaseClient "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/biz/llm/client/base.py"
    click Deepseek "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/biz/llm/client/deepseek.py"
    click Ollama "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/biz/llm/client/ollama_client.py"
    click OpenAI "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/biz/llm/client/openai.py"
    click Qwen "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/biz/llm/client/qwen.py"
    click ZhipuAI "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/biz/llm/client/zhipuai.py"
    click CodeParser "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/biz/utils/code_parser.py"
    click CodeReviewer "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/biz/utils/code_reviewer.py"
    click QueueUtil "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/biz/utils/queue.py"
    click Reporter "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/biz/utils/reporter.py"
    click UI "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/ui.py"
    click Env "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/conf/.env.dist"
    click Templates "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/conf/prompt_templates.yml"
    click SupervisordApp "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/conf/supervisord.app.conf"
    click SupervisordWorker "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/conf/supervisord.worker.conf"
    click DockerCompose "https://github.com/sunmh207/ai-codereview-gitlab/blob/main/docker-compose.yml"
    click Dockerfile "https://github.com/sunmh207/ai-codereview-gitlab/tree/main/Dockerfile"
```
