# rekib0023/racode-reviewer architecture

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

- Interactive diagram: https://gitdiagram.com/rekib0023/racode-reviewer
- Repository: https://github.com/rekib0023/racode-reviewer

## Overview

##### Project type and purpose
- This is a backend-only, microservice-style application (“RACode Reviewer”) that provides AI-powered, retrieval-augmented code reviews.
- It consumes GitHub webhook events, performs incremental code indexing and embedding, stores embeddings in a vector database (LanceDB), invokes an LLM for review generation, and posts review comments back to GitHub.

##### File structure
- Top-level files
- Dockerfile, pyproject.toml, requirements.txt, .env.example, README.md, TECHNICAL_DOCS.md
- app/main.py – FastAPI app entrypoint
- app/api
- routes/github.py – webhook endpoint
- routes/health.py – healthcheck
- dependencies.py – DI for settings, clients
- app/core
- config.py – Singleton settings loader
- exceptions.py – custom exception hierarchy
- logging_config.py – structured logging
- app/services
- github_service.py – wraps GitHub API calls
- llm_service.py – wraps calls to LLM (RAG retriever)
- app/indexing
- indexer.py, incremental_indexer.py – orchestration of file diff detection and re-indexing
- code_parser.py, embedding_generator.py – parsing source, factory for embedding models
- app/storage
- repo_manager.py – clones or opens local repo
- vector_store.py – LanceDB interactions (Repository pattern)
- app/llm
- rag_retriever.py – retrieves context vectors + prompt
- prompts.py – prompt templates
- app/utils – general parsers, diff utils

##### README insights
- Core components: GitHub API ↔ FastAPI App ↔ LLM Service; GitHub Service ↔ Incremental Indexer; Embedding Gen ↔ Vector Database

##### Detailed capture of essential elements
- Do not conflate embedding generation with vector store; show them as separate modules
- Configuration injection at the API layer (“core.config”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    GitHub["GitHub Webhooks & API"]:::external

    subgraph "API Layer"
        Main["FastAPI App Entry\napp/main.py"]:::api
        GitHubWebhook["Webhook Endpoint\napp/api/routes/github.py"]:::api
        Health["Healthcheck Endpoint\napp/api/routes/health.py"]:::api
        Dependencies["DI & Webhook Validation\napp/api/dependencies.py"]:::api
    end

    subgraph "Cross-Cutting"
        Config["Singleton Config\napp/core/config.py"]:::crossCutting
        Exceptions["Custom Exceptions\napp/core/exceptions.py"]:::crossCutting
        Logging["Logging Config\napp/core/logging_config.py"]:::crossCutting
    end

    subgraph "Service Layer"
        GitHubService["GitHub Service\napp/services/github_service.py"]:::dataProcessing
        LLMService["LLM Service\napp/services/llm_service.py"]:::ai
        QueryEngine["Query Engine\napp/query_engine.py"]:::dataProcessing
    end

    subgraph "Indexing & Embedding"
        IncrementalIndexer["Incremental Indexer\napp/indexing/incremental_indexer.py"]:::dataProcessing
        FullIndexer["Indexer Orchestration\napp/indexing/indexer.py"]:::dataProcessing
        CodeParser["Code Parser\napp/indexing/code_parser.py"]:::dataProcessing
        EmbeddingGen["Embedding Generator\napp/indexing/embedding_generator.py"]:::dataProcessing
    end

    subgraph "Storage"
        RepoManager["Repo Manager\napp/storage/repo_manager.py"]:::storage
        VectorStore["Vector Store\napp/storage/vector_store.py"]:::storage
    end

    subgraph "LLM & RAG"
        RAGRetriever["RAG Retriever\napp/llm/rag_retriever.py"]:::ai
        Prompts["Prompt Templates\napp/llm/prompts.py"]:::ai
    end

    GitHub -->|Webhook Event| Main
    Main --> GitHubWebhook
    Main --> Health
    GitHubWebhook -->|Validate HMAC| Dependencies
    GitHubWebhook -->|Trigger Indexing| IncrementalIndexer
    GitHubWebhook -->|Trigger Indexing| FullIndexer
    Dependencies --> Config
    Dependencies --> Logging
    Dependencies --> Exceptions

    IncrementalIndexer -->|Clone & diff| RepoManager
    FullIndexer -->|Clone & diff| RepoManager
    IncrementalIndexer --> CodeParser
    FullIndexer --> CodeParser
    CodeParser --> EmbeddingGen
    EmbeddingGen -->|Store embeddings| VectorStore

    GitHubWebhook --> QueryEngine
    QueryEngine --> RAGRetriever
    RAGRetriever --> VectorStore
    RAGRetriever --> Prompts
    RAGRetriever -->|Compose prompt| LLMService
    LLMService -->|LLM response| GitHubService
    GitHubService -->|Post Comment| GitHub

    classDef api fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef dataProcessing fill:#D0FFD8,stroke:#333,stroke-width:1px
    classDef storage fill:#FFE4B5,stroke:#333,stroke-width:1px
    classDef ai fill:#E6E6FA,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef crossCutting fill:#F0F0F0,stroke:#333,stroke-width:1px

    click Main "https://github.com/rekib0023/racode-reviewer/blob/main/app/main.py"
    click GitHubWebhook "https://github.com/rekib0023/racode-reviewer/blob/main/app/api/routes/github.py"
    click Health "https://github.com/rekib0023/racode-reviewer/blob/main/app/api/routes/health.py"
    click Dependencies "https://github.com/rekib0023/racode-reviewer/blob/main/app/api/dependencies.py"
    click Config "https://github.com/rekib0023/racode-reviewer/blob/main/app/core/config.py"
    click Exceptions "https://github.com/rekib0023/racode-reviewer/blob/main/app/core/exceptions.py"
    click Logging "https://github.com/rekib0023/racode-reviewer/blob/main/app/core/logging_config.py"
    click GitHubService "https://github.com/rekib0023/racode-reviewer/blob/main/app/services/github_service.py"
    click LLMService "https://github.com/rekib0023/racode-reviewer/blob/main/app/services/llm_service.py"
    click IncrementalIndexer "https://github.com/rekib0023/racode-reviewer/blob/main/app/indexing/incremental_indexer.py"
    click FullIndexer "https://github.com/rekib0023/racode-reviewer/blob/main/app/indexing/indexer.py"
    click CodeParser "https://github.com/rekib0023/racode-reviewer/blob/main/app/indexing/code_parser.py"
    click EmbeddingGen "https://github.com/rekib0023/racode-reviewer/blob/main/app/indexing/embedding_generator.py"
    click RepoManager "https://github.com/rekib0023/racode-reviewer/blob/main/app/storage/repo_manager.py"
    click VectorStore "https://github.com/rekib0023/racode-reviewer/blob/main/app/storage/vector_store.py"
    click RAGRetriever "https://github.com/rekib0023/racode-reviewer/blob/main/app/llm/rag_retriever.py"
    click Prompts "https://github.com/rekib0023/racode-reviewer/blob/main/app/llm/prompts.py"
    click QueryEngine "https://github.com/rekib0023/racode-reviewer/blob/main/app/query_engine.py"
```
