# skhapijulhossen/gsearch architecture

> Architecture diagram of the GitHub repository skhapijulhossen/gsearch, 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/skhapijulhossen/gsearch
- Repository: https://github.com/skhapijulhossen/gsearch

## Overview

##### Project type and purpose
- This is a full-stack Retrieval-Augmented Generation (RAG) chatbot for HR teams.
- Front-end: Streamlit application (`app/streamlit_app.py`)
- Back-end: FastAPI service (`app/api/main.py`)
- Core pipeline: data loading, FAISS vector store, LLM chain (via Ollama), hybrid search.

##### File structure
- app/api/main.py → FastAPI entrypoint & HTTP endpoints
- app/streamlit_app.py → Streamlit UI
- app/core/
- config.py → application settings (e.g., thresholds, model names)
- schemas.py → Pydantic models for requests/responses
- prompts.py → prompt templates for the LLM
- app/services/
- data_service.py → load/filter employee JSON (data/employees.json)
- retriever_service.py → wrap FAISS index (employee_faiss_index/index.faiss), hybrid search logic
- llm_service.py → assemble LangChain QA chain, call Ollama LLM, handle context & formatting
- data/ → raw employee JSON
- employee_faiss_index/ → persisted FAISS index
- requirements.txt → Python dependencies

##### Extract key architecture insights from the README
- Four logical stages: Data Loading → Vector Store → LLM Chain → API
- Hybrid search: similarity + keyword matching
- Open-source stack: FastAPI, FAISS, LangChain, Ollama, Streamlit

a. Main components
- Streamlit UI (front-end)
- FastAPI server (API gateway)
- Service layer (DataService, RetrieverService, LLMService)
- Data Store (employees.json)
- Vector Store (FAISS index)
- External LLM (Ollama)
b. Relationships & data flow
1. User enters query in Streamlit → HTTP POST to FastAPI
2. FastAPI controller validates via schemas → passes to DataService (optional filters)
3. RetrieverService queries FAISS index → retrieves top-k embeddings + metadata
4. LLMService builds prompt (using prompts.py), invokes Ollama via LangChain QA chain
5. Ollama returns structured response → LLMService formats + attaches citations
6. FastAPI returns JSON → Streamlit renders response
c. Architectural patterns & principles
- Layered architecture: UI → API → Services → Storage/External
- Separation of concerns: data loading, retrieval, LLM orchestration
- RAG pipeline pattern (index, retrieve, generate)
d. Key technologies & frameworks
- FastAPI (web framework)
- Streamlit (UI)
- FAISS (vector similarity search)
- LangChain (RAG orchestration)
- Ollama (local LLM host)
- Pydantic (schemas & validation)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Front-end Layer
    subgraph "Front-end" 
        Streamlit_UI["Streamlit UI"]:::ui
    end

    %% API & Services Layer
    subgraph "API & Services"
        FastAPI_Controller["FastAPI Controller"]:::api
        subgraph "Service Layer"
            Config["Configuration"]:::api
            Schemas["Pydantic Schemas"]:::api
            Prompts["Prompt Templates"]:::api
            DataService["Data Service"]:::api
            RetrieverService["Retriever Service"]:::api
            LLMService["LLM Service"]:::api
        end
    end

    %% Storage Layer
    subgraph "Storage"
        Employee_JSON["Raw Employee Data (JSON)"]:::storage
        FAISS_Index["Persisted FAISS Vector Store"]:::storage
        Requirements["Python Dependencies"]:::storage
    end

    %% External Layer
    subgraph "External"
        Ollama["Ollama LLM"]:::external
    end

    %% Data Flow
    Streamlit_UI -->|"1. POST Query"| FastAPI_Controller
    FastAPI_Controller -->|"2. Validate Request"| Schemas
    FastAPI_Controller -->|"3. Load Config"| Config
    FastAPI_Controller -->|"4. Call DataService"| DataService
    DataService -->|"reads JSON"| Employee_JSON
    FastAPI_Controller -->|"5. Call RetrieverService"| RetrieverService
    RetrieverService -->|"loads FAISS"| FAISS_Index
    RetrieverService -->|"hybrid search"| RetrieverService
    FastAPI_Controller -->|"6. Call LLMService"| LLMService
    LLMService -->|"uses Prompts"| Prompts
    LLMService -->|"calls external LLM"| Ollama
    Ollama -->|"7. Returns Response"| LLMService
    LLMService -->|"formats answer"| FastAPI_Controller
    FastAPI_Controller -->|"8. Return JSON"| Streamlit_UI

    %% Click Events
    click Streamlit_UI "https://github.com/skhapijulhossen/gsearch/blob/main/app/streamlit_app.py"
    click FastAPI_Controller "https://github.com/skhapijulhossen/gsearch/blob/main/app/api/main.py"
    click Config "https://github.com/skhapijulhossen/gsearch/blob/main/app/core/config.py"
    click Schemas "https://github.com/skhapijulhossen/gsearch/blob/main/app/core/schemas.py"
    click Prompts "https://github.com/skhapijulhossen/gsearch/blob/main/app/core/prompts.py"
    click DataService "https://github.com/skhapijulhossen/gsearch/blob/main/app/services/data_service.py"
    click RetrieverService "https://github.com/skhapijulhossen/gsearch/blob/main/app/services/retriever_service.py"
    click LLMService "https://github.com/skhapijulhossen/gsearch/blob/main/app/services/llm_service.py"
    click Employee_JSON "https://github.com/skhapijulhossen/gsearch/blob/main/data/employees.json"
    click FAISS_Index "https://github.com/skhapijulhossen/gsearch/blob/main/employee_faiss_index/index.faiss"
    click Requirements "https://github.com/skhapijulhossen/gsearch/blob/main/requirements.txt"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000
    classDef api fill:#90EE90,stroke:#000
    classDef storage fill:#FFD700,stroke:#000
    classDef external fill:#DDA0DD,stroke:#000
```
