# bogdan-chis/ai-research-assistant architecture

> Architecture diagram of the GitHub repository bogdan-chis/ai-research-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bogdan-chis/ai-research-assistant
- Repository: https://github.com/bogdan-chis/ai-research-assistant

## Overview

##### Project type and purpose
- This is a full-stack web application (“AI Research Assistant”) that allows end users to query scientific literature.
- The backend provides a Retrieval-Augmented Generation (RAG) pipeline with vector search, embeddings, and local LLM integration.
- The frontend is a React (or Streamlit) UI that sends queries to the backend and renders the results with source citations and guardrails.

##### File structure
- Top-level directories:
- backend: Python service with submodules for API, data ingestion, embeddings, LLM integration, vector store, and tests.
- frontend: JavaScript/TypeScript React app with public assets, reusable UI components, and HTTP/service wrappers.
- chroma: local database file (chroma.sqlite3) for vector storage.
- Key backend modules:
- api: main.py, routes, schemas – defines HTTP endpoints (likely FastAPI).
- data: dataset loading, document splitting, postprocessing.
- embeddings: wrapper for computing or fetching embeddings.
- llm_integration: client for local LLM (LM Studio), prompt engineering, RAG service.
- vectorstore: interface to ChromaDB vector store.
- Configuration files: .env.example, requirements.txt.

##### README for additional insights
- Workflow steps:
1. User query via web UI.
2. Vector search on embedded docs.
3. Context + query → local LLM.
4. Toxicity/hallucination checks.
5. Return answer + citations.
- External services: LM Studio (local LLM), Perspective API (toxicity / hallucination guardrails).

1. Frontend (React)
2. Backend API Server (FastAPI)
3. Ingestion & Preprocessing Pipeline (dataset_loader, document_splitter, postprocessing)
4. Embeddings Service (embeddings.py)
5. Vector Store (ChromaDB with chroma.sqlite3)
6. RAG Service (rag_service.py)
7. LLM Client (LLM Studio via llm_client.py)
8. Toxicity/Hallucination Guardrails (Perspective API)
9. External Services (LM Studio, Perspective API)
10. Data Store (raw documents, optional file storage)
b. Relationships & interactions:
- Frontend ↔ Backend API: HTTP requests (question submission, answer retrieval).
- Backend API → Ingestion Pipeline: triggered on new uploads or at startup.
- Backend API → Vector Store: query–embed–retrieve.
- Backend API → Embeddings Service: compute embeddings for query or new docs.
- Backend API → RAG Service → LLM Client → LLM Studio: send prompt + context.
- Backend API → Guardrails → Perspective API: analyze LLM output.
- Vector Store ← Embeddings Service ← Data Pipeline: embedding docs once.
- Database (chroma.sqlite3) stores embedding vectors and metadata.
c. Architectural patterns and design principles:
- Modular micro-service–style Python modules (api, data, embeddings, llm_integration, vectorstore).
- Clear separation of concerns: ingestion, storage, inference, and UI.
- Pipeline orchestration: RAG service composes retrieval + LLM + guardrails.
- Stateless API layer, with persistent vector store.
d. Key technologies, frameworks, libraries:
- Frontend: React (components/services)
- Backend: Python (FastAPI or Flask), Pydantic schemas
- Vector DB: ChromaDB
- LLM: Local instance via LM Studio (llm_client)
- Guardrails: Perspective API
- Data processing: custom Python modules

##### Details to capture
- Batch vs. real-time flows (document ingestion is batch, querying is real-time).
- Protocols (HTTP, gRPC if any, local file I/O).
- Config points (e.g., .env for API keys, LM Studio endpoint).
- Error/guardrail branch: LLM output → Perspective API → warning labels.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        UI["React UI"]:::frontend
        Services["HTTP/Service Wrappers"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Services"
        direction TB
        API["API Server (FastAPI)"]:::backend
        subgraph "Ingestion & Preprocessing Pipeline"
            direction TB
            DL["Dataset Loader"]:::backend
            DS["Document Splitter"]:::backend
            PP["Postprocessing"]:::backend
        end
        Embeddings["Embeddings Service"]:::backend
        VStoreInterface["Vector Store Interface"]:::backend
        RAG["RAG Service"]:::backend
        LLMClient["LLM Client"]:::backend
        Guardrails["Prompt Eng. & Guardrails"]:::backend
        Config["Configuration (.env)"]:::backend
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        RawDocs[(Raw Documents)]:::datastore
        ChromaDB[(ChromaDB\nchroma.sqlite3)]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LMStudio((LM Studio)):::external
        Perspective((Perspective API)):::external
    end

    %% Query Flow
    UI -->|"HTTP: Query"| API
    API -->|"Embed Query"| Embeddings
    Embeddings -->|"Query Embeddings"| VStoreInterface
    VStoreInterface -->|"Retrieve Context"| ChromaDB
    VStoreInterface -->|"Context"| RAG
    API -->|"Trigger Ingestion"| DL
    DL --> DS
    DS --> PP
    PP --> Embeddings
    Embeddings --> ChromaDB
    API --> RAG
    RAG --> LLMClient
    LLMClient --> LMStudio
    RAG --> Guardrails
    Guardrails --> Perspective
    Guardrails --> API
    API -->|"HTTP: Response"| UI

    %% Data Store Edges
    RawDocs --> DL
    ChromaDB --> VStoreInterface

    %% Click Events
    click UI "https://github.com/bogdan-chis/ai-research-assistant/tree/main/frontend/src/components"
    click Services "https://github.com/bogdan-chis/ai-research-assistant/tree/main/frontend/src/services"
    click API "https://github.com/bogdan-chis/ai-research-assistant/blob/main/backend/api/main.py"
    click DL "https://github.com/bogdan-chis/ai-research-assistant/blob/main/backend/data/dataset_loader.py"
    click DS "https://github.com/bogdan-chis/ai-research-assistant/blob/main/backend/data/document_splitter.py"
    click PP "https://github.com/bogdan-chis/ai-research-assistant/blob/main/backend/data/postprocessing.py"
    click Embeddings "https://github.com/bogdan-chis/ai-research-assistant/blob/main/backend/embeddings/embeddings.py"
    click VStoreInterface "https://github.com/bogdan-chis/ai-research-assistant/blob/main/backend/vectorstore/vector_store.py"
    click ChromaDB "https://github.com/bogdan-chis/ai-research-assistant/blob/main/chroma/chroma.sqlite3"
    click RAG "https://github.com/bogdan-chis/ai-research-assistant/blob/main/backend/llm_integration/rag_service.py"
    click LLMClient "https://github.com/bogdan-chis/ai-research-assistant/blob/main/backend/llm_integration/llm_client.py"
    click Guardrails "https://github.com/bogdan-chis/ai-research-assistant/blob/main/backend/llm_integration/prompt_engineering.py"
    click Config "https://github.com/bogdan-chis/ai-research-assistant/blob/main/backend/.env.example"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#333,stroke-width:1px
    classDef backend fill:#CFF7AE,stroke:#333,stroke-width:1px
    classDef datastore fill:#FFDDAA,stroke:#333,stroke-width:1px
    classDef external fill:#DDDDDD,stroke:#333,stroke-width:1px
```
