# thinkany-ai/rag-search architecture

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

- Interactive diagram: https://gitdiagram.com/thinkany-ai/rag-search
- Repository: https://github.com/thinkany-ai/rag-search

## Overview

##### Project type and purpose
- This is a Python-based backend API service (monolithic FastAPI app) for Retrieval‑Augmented‑Generation (RAG) search.
- It exposes a REST endpoint (“/rag-search”) that:
– Takes a user query
– Runs a search via external search providers (e.g., Serper/Google, “search2ai”)
– Embeds/query documents in a vector database (Zilliz/Milvus)
– Optionally reranks results (FlashRank, LlamaIndex)
– Optionally summarizes/enhances with LLMs (OpenAI, Gemini, LingYi)
– Returns structured JSON responses

##### File structure
Top‑level folders and what they imply:
- components/ – cross‑cutting utilities (environment loader, logger)
- handlers/ – FastAPI route handlers implementing each API endpoint’s orchestration logic
- services/ – core business logic broken into subdomains:
– document/ (query & store vectors)
– llm/ (calls to different LLM providers)
– search/ (external search providers)
– rerank/ (result reranking logic)
– vdb/ (vector database client)
– web.py (wrapping service calls for HTTP)
- utils/ – small helpers (hashing, response formatting, sequence ops)
- main.py – application bootstrap (FastAPI app, router registration, dependency injection via service_context_factory)
- .env & requirements.txt – configuration and dependencies

##### Key insights from README
- Starts a FastAPI server on port 8069
- Relies on environment variables to wire in API keys, model names, Zilliz credentials, etc.
- Single HTTP POST endpoint (/rag-search) with request parameters controlling search provider, reranking, filtering, detail inclusion, etc.

##### Main components & their interactions
A. Client Layer:
– External Client (Postman/HTTP client)
B. API Layer (FastAPI)
– main.py: App + Router
– handlers/ (rag_search handler, ping, reranking)
– components/env.py & log.py (config + centralized logging)
C. Service Layer (Orchestration)
– Service Context Factory: builds and injects instances of all services
– services/search (calls out to Serper/Google, Search2AI)
– services/vdb (Zilliz vector store)
– services/document (stores/queries embeddings)
– services/rerank (FlashRank, LlamaIndex)
– services/llm (OpenAI, Gemini, LingYi clients)
– services/web (translating HTTP inputs into service calls)
D. Data & External Systems
– Zilliz/Milvus vector DB
– External Search APIs (Serper, Search2AI)
– LLM providers (OpenAI, Gemini, LingYi)
E. Utilities
– utils/* modules for common routines

##### Architectural patterns & design principles
- Layered architecture: clear separation between HTTP handling (handlers), business logic (services), and third‑party integrations (external APIs, DB).
- Dependency injection via a single ServiceContextFactory to make unit testing and swapping implementations easy.
- Modular design: each service subdomain is in its own package.
- Environment‑driven configuration: all sensitive keys and endpoints come from .env

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["External Client\n(Postman/HTTP)"]:::client

    %% API Layer
    subgraph "API Layer"
        direction TB
        Main["main.py\n(FastAPI App & Router)"]:::api
        Env["env.py\n(Environment Loader)"]:::util
        Log["log.py\n(Centralized Logger)"]:::util
        Rag["rag_search.py\n(Handler)"]:::api
        RerankH["reranking.py\n(Handler)"]:::api
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        SCF["service_context_factory.py\n(DI Factory)"]:::service
        Web["web.py\n(HTTP→Service Adapter)"]:::service
        subgraph "Search Services"
            direction TB
            Serper["serper.py"]:::service
            Search2AI["search2ai.py"]:::service
        end
        subgraph "Vector DB Service"
            direction TB
            VDB["zilliz.py"]:::service
        end
        subgraph "Document Services"
            direction TB
            DocQuery["query.py"]:::service
            DocStore["store.py"]:::service
        end
        subgraph "Rerank Services"
            direction TB
            FlashRank["flashrank.py"]:::service
            LlamaIndex["llamaindex.py"]:::service
            RerankCore["rerank.py"]:::service
        end
        subgraph "LLM Services"
            direction TB
            OpenAI["openai.py"]:::service
            Gemini["gemini.py"]:::service
            LingYi["lingyi.py"]:::service
        end
    end

    %% Data & External Layer
    subgraph "Data & External Systems"
        direction TB
        SerperAPI["Serper API"]:::external
        Search2API["Search2AI API"]:::external
        MilvusDB["Zilliz/Milvus\nVector DB"]:::external
        OpenAIAPI["OpenAI API"]:::external
        GeminiAPI["Gemini API"]:::external
        LingYiAPI["LingYi API"]:::external
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        Hash["hash.py"]:::util
        Resp["resp.py"]:::util
        Seq["seq.py"]:::util
    end

    %% Connections
    Client -->|"HTTP POST JSON"| Rag
    Client -->|"HTTP POST JSON"| RerankH
    Rag -->|"calls"| SCF
    RerankH -->|"calls"| SCF
    SCF --> Web
    Web --> Serper
    Web --> Search2AI
    SCF --> DocQuery
    SCF --> DocStore
    SCF --> VDB
    SCF --> RerankCore
    SCF --> FlashRank
    SCF --> LlamaIndex
    SCF --> OpenAI
    SCF --> Gemini
    SCF --> LingYi

    Serper -->|"HTTP Requests"| SerperAPI
    Search2AI -->|"HTTP Requests"| Search2API
    VDB -->|"Vector Query"| MilvusDB
    DocQuery --> VDB
    DocStore --> VDB
    FlashRank -->|"rerank scores"| RerankCore
    LlamaIndex -->|"rerank scores"| RerankCore
    RerankCore -->|"filtered results"| Web
    OpenAI -->|"LLM calls"| OpenAIAPI
    Gemini -->|"LLM calls"| GeminiAPI
    LingYi -->|"LLM calls"| LingYiAPI
    Web -->|"response JSON"| Rag
    Web -->|"response JSON"| RerankH
    Rag -->|"HTTP Response JSON"| Client
    RerankH -->|"HTTP Response JSON"| Client

    %% Click Events
    click Main "https://github.com/thinkany-ai/rag-search/blob/main/main.py"
    click Env "https://github.com/thinkany-ai/rag-search/blob/main/components/env.py"
    click Log "https://github.com/thinkany-ai/rag-search/blob/main/components/log.py"
    click Rag "https://github.com/thinkany-ai/rag-search/blob/main/handlers/rag_search.py"
    click RerankH "https://github.com/thinkany-ai/rag-search/blob/main/handlers/reranking.py"
    click SCF "https://github.com/thinkany-ai/rag-search/blob/main/services/llm/service_context_factory.py"
    click Serper "https://github.com/thinkany-ai/rag-search/blob/main/services/search/serper.py"
    click Search2AI "https://github.com/thinkany-ai/rag-search/blob/main/services/search/search2ai.py"
    click VDB "https://github.com/thinkany-ai/rag-search/blob/main/services/vdb/zilliz.py"
    click DocQuery "https://github.com/thinkany-ai/rag-search/blob/main/services/document/query.py"
    click DocStore "https://github.com/thinkany-ai/rag-search/blob/main/services/document/store.py"
    click FlashRank "https://github.com/thinkany-ai/rag-search/blob/main/services/rerank/flashrank.py"
    click LlamaIndex "https://github.com/thinkany-ai/rag-search/blob/main/services/rerank/llamaindex.py"
    click RerankCore "https://github.com/thinkany-ai/rag-search/blob/main/services/rerank/rerank.py"
    click OpenAI "https://github.com/thinkany-ai/rag-search/blob/main/services/llm/openai.py"
    click Gemini "https://github.com/thinkany-ai/rag-search/blob/main/services/llm/gemini.py"
    click LingYi "https://github.com/thinkany-ai/rag-search/blob/main/services/llm/lingyi.py"
    click Web "https://github.com/thinkany-ai/rag-search/blob/main/services/web.py"
    click Hash "https://github.com/thinkany-ai/rag-search/blob/main/utils/hash.py"
    click Resp "https://github.com/thinkany-ai/rag-search/blob/main/utils/resp.py"
    click Seq "https://github.com/thinkany-ai/rag-search/blob/main/utils/seq.py"

    %% Styles
    classDef client fill:#8fd3f4,stroke:#333,stroke-width:1px;
    classDef api fill:#b3cde3,stroke:#333,stroke-width:1px;
    classDef service fill:#ccebc5,stroke:#333,stroke-width:1px;
    classDef external fill:#fdae61,stroke:#333,stroke-width:1px;
    classDef util fill:#d9d9d9,stroke:#333,stroke-width:1px;
```
