# hapijul-trigent/esearch architecture

> Architecture diagram of the GitHub repository hapijul-trigent/esearch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hapijul-trigent/esearch
- Repository: https://github.com/hapijul-trigent/esearch

## Overview

##### Project type and purpose
- This is a microservice‐style search API built with FastAPI.
- Purpose: Provide intelligent, natural‐language–driven search over employee records using LangChain + Ollama (Gemma 3:1b) + FAISS for vector retrieval.

##### File structure
- Top-level:
- app/ – main application package
- data/ – static JSON data fallback
- requirements.txt, README.md
- app/ submodules:
- main.py – FastAPI app & endpoints
- data_loader.py – loads employees.json → in-memory list
- retriever.py – builds FAISS vector store from loaded data
- llm_chain.py – configures LangChain chain with Ollama model
- schema.py – Pydantic request/response models
- retriever.py & llm_chain.py handle two distinct flows (filter search vs. chat LLM)
- data/employees.json – primary data source

##### README for architectural cues
- Endpoints: /employees/search, /chat, /health
- External dependency: Ollama service running Gemma 3:1b
- In-process vector store (FAISS)
- Core flow: HTTP Request → FastAPI → Retriever/LLM chain → Ollama → Response

##### Main components and relationships
a. Client (Browser/CLI/Postman)
b. FastAPI Server (uvicorn/app.main)
- Endpoints layer (routes/controllers)
- Business logic layer:
- DataLoader (loads JSON)
- Retriever (FAISS index & similarity search)
- LLMChain (LangChain wrapper calling Ollama)
c. Data store
- Static JSON (app/data/employees.json)
- FAISS in-memory vector store (built at startup)
d. External service
- Ollama API (Gemma 3:1b model)

Interactions:
1. Client sends HTTP GET /employees/search → FastAPI → DataLoader → Retriever → return filtered + vector search results
2. Client sends HTTP POST /chat → FastAPI → LLMChain → Ollama API → return LLM response

##### Architectural patterns & design principles
- Layered architecture: Controllers → Services (loader, retriever, chain) → External services
- Single‐process microservice: no separate DB server; uses file + memory store
- Dependency injection via function parameters in FastAPI routes
- Separation of concerns: data loading vs. vector retrieval vs. LLM orchestration

##### Specific elements
- Labels: module names, endpoint names, data formats
- Notes:
- FAISS is in-memory, built at startup
- Ollama must be running separately
- DataLoader reads from app/data/employees.json

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Client["Client\n(browser/CLI/Postman)"]:::client

    %% FastAPI Server
    subgraph "FastAPI Server"
        direction TB
        Controllers["Endpoints\n(GET /employees/search, POST /chat, GET /health)"]:::internal
        Schemas["Schemas\n(app/schema.py)"]:::internal
        DataLoader["DataLoader\n(app/data_loader.py)"]:::internal
        RetrieverMod["Retriever\n(app/retriever.py)"]:::internal
        LLMChainMod["LLMChain\n(app/llm_chain.py)"]:::internal
    end

    %% Data Stores
    DataJSON1(("Primary Data Store\n(app/data/employees.json)")):::json
    DataJSON2(("Static JSON Fallback\n(data/employees.json)")):::json
    FAISS(("FAISS Vector Store\n(in-memory)")):::faiss

    %% External Services
    Ollama["Ollama Service\n(Gemma 3:1b)"]:::external

    %% Docs & Config
    README["README.md"]:::doc
    REQS["requirements.txt"]:::doc

    %% Connections
    Client -->|"HTTP GET/POST"| Controllers
    Controllers -->|"uses schemas"| Schemas
    Controllers -->|"load JSON"| DataLoader
    DataLoader --> DataJSON1
    DataLoader --> DataJSON2
    DataLoader -->|"build index at startup"| RetrieverMod
    Controllers -->|"vector query"| RetrieverMod
    RetrieverMod --> FAISS
    Controllers -->|"LLM request"| LLMChainMod
    LLMChainMod -->|"API call"| Ollama
    Ollama -->|"response"| LLMChainMod
    LLMChainMod -->|"LLM response"| Controllers
    Controllers -->|"HTTP response"| Client

    %% Click Events
    click Controllers "https://github.com/hapijul-trigent/esearch/blob/main/app/main.py"
    click DataLoader "https://github.com/hapijul-trigent/esearch/blob/main/app/data_loader.py"
    click RetrieverMod "https://github.com/hapijul-trigent/esearch/blob/main/app/retriever.py"
    click LLMChainMod "https://github.com/hapijul-trigent/esearch/blob/main/app/llm_chain.py"
    click Schemas "https://github.com/hapijul-trigent/esearch/blob/main/app/schema.py"
    click DataJSON1 "https://github.com/hapijul-trigent/esearch/blob/main/app/data/employees.json"
    click DataJSON2 "https://github.com/hapijul-trigent/esearch/blob/main/data/employees.json"
    click REQS "https://github.com/hapijul-trigent/esearch/blob/main/requirements.txt"
    click README "https://github.com/hapijul-trigent/esearch/blob/main/README.md"

    %% Styles
    classDef internal fill:#BBDEFB,stroke:#000;
    classDef json fill:#C8E6C9,stroke:#000;
    classDef faiss fill:#FFE0B2,stroke:#000;
    classDef external fill:#E1BEE7,stroke:#000;
    classDef doc fill:#CFD8DC,stroke:#000;
    classDef client fill:#FFECB3,stroke:#000;
```
