# sacamb/rt-aaidc-project1 architecture

> Architecture diagram of the GitHub repository sacamb/rt-aaidc-project1, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sacamb/rt-aaidc-project1
- Repository: https://github.com/sacamb/rt-aaidc-project1

## Overview

##### Project type and purpose
- This is a backend AI service implementing a Retrieval-Augmented Generation (RAG) pipeline for an internal corporate knowledge corpus.
- It ingests a set of text documents, builds vector embeddings, stores them in ChromaDB, exposes a query API (via FastAPI), and uses LLMs (OpenAI/Groq/Google AI) to generate contextual answers.

##### File structure
- Top-level:
- data/ → raw corporate text files
- chroma_db/ → persistent vector store
- src/app.py → main application + API + RAG pipeline
- src/vectordb.py → ingestion, chunking, embedding, search wrapper
- .env.example, requirements.txt, LICENSE, README files
- No separate “frontend”—it’s a monolithic backend service with distinct ingestion vs. query modules.
- Uses FastAPI for HTTP endpoints; python-dotenv for config; LangChain orchestrates LLM calls.

a. Data Sources & Configuration
– data/ (Document Repository)
– .env (API keys)
b. Document Ingestion Module (vectordb.py)
– Chunker (text splitter)
– Embedding Generator (sentence-transformers)
– ChromaDB Client (vector storage)
c. Vector Database (ChromaDB)
– On-disk persistence in chroma_db/
d. Query API & RAG Pipeline (app.py)
– API Layer (FastAPI endpoints)
– Query Handler (embedding query, similarity search)
– Prompt Template & Chain (LangChain orchestration)
– LLM Providers (OpenAI, Groq, Google AI)
e. External Services
– LLM API endpoints (OpenAI/Groq/Google AI)

##### Relationships & interactions
- Ingestion flow: data/ → vectordb.chunker → embedding model → ChromaDB
- Query flow: Client HTTP GET/POST → FastAPI → Query Handler
→ vectordb.search() → ChromaDB → top-k chunks
→ LangChain prompt assembly → LLM API call → response → FastAPI → Client
- Config loader (.env) provides API keys to both ingestion & query steps.

##### Architectural patterns & principles
- Separation of concerns: ingestion vs. query modules
- Wrapper abstraction: vectordb.py hides direct ChromaDB calls
- Pipeline orchestration: LangChain chains prompt creation and LLM calls
- Stateless query service; stateful vector store (ChromaDB) on disk
- Pluggable LLM providers via dependency injection (via env variables)

- Layer 1: Configuration
- .env loader → provides OPENAI_API_KEY / GROQ_API_KEY / GOOGLE_API_KEY
- Layer 2: Data & Storage
- data/ (raw docs) → vectordb ingestion → ChromaDB
- Layer 3: Ingestion Module
- Text chunking → Embedding model → ChromaDB client
- Layer 4: Query Module
- FastAPI endpoint
- Query embedding → similarity search
- Context assembly (multi-hop)
- Prompt templating
- LLM API invocation
- Layer 5: Response
- Post-processing → JSON result with metadata → client

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Configuration Layer
    subgraph "Configuration"
        env[".env Loader"]:::config
        example[".env.example"]:::config
        reqs["requirements.txt"]:::config
    end

    %% Data & Storage Layer
    subgraph "Data & Storage"
        data["data/ (Document Repository)"]:::storageSource
        chroma["ChromaDB\n(Vector Store)"]:::storage
    end

    %% Ingestion Pipeline
    subgraph "Ingestion Pipeline"
        ingest["vectordb.py\n(Chunker, Embedding Generator,\nChromaDB Client)"]:::internal
    end

    %% Query/RAG Pipeline
    subgraph "Query/RAG Pipeline"
        client["HTTP Client"]:::external
        api["app.py\n(FastAPI, Query Handler,\nPrompt Template & Chain)"]:::internal
    end

    %% External Services
    subgraph "External LLM APIs"
        openai["OpenAI API"]:::external
        groq["Groq AI API"]:::external
        google["Google AI API"]:::external
    end

    %% Ingestion Flow (Blue)
    data -->|"load documents"| ingest
    example -->|"provide API keys"| ingest
    env -->|"load configuration"| ingest
    ingest -->|"store embeddings"| chroma

    %% Query Flow (Green)
    client -->|"HTTP request"| api
    example -->|"provide API keys"| api
    env -->|"load configuration"| api
    api -->|"similarity search"| chroma
    api -->|"invoke LLM"| openai
    api -->|"invoke LLM"| groq
    api -->|"invoke LLM"| google
    chroma -->|"return top-k chunks"| api
    api -->|"JSON response"| client

    %% Click Events
    click data "https://github.com/sacamb/rt-aaidc-project1/tree/main/data/"
    click example "https://github.com/sacamb/rt-aaidc-project1/blob/main/.env.example"
    click ingest "https://github.com/sacamb/rt-aaidc-project1/blob/main/src/vectordb.py"
    click api "https://github.com/sacamb/rt-aaidc-project1/blob/main/src/app.py"
    click reqs "https://github.com/sacamb/rt-aaidc-project1/blob/main/requirements.txt"

    %% Styles
    classDef internal fill:#add8e6,stroke:#333,stroke-width:1px
    classDef storage fill:#ffa500,stroke:#333,stroke-width:1px
    classDef storageSource fill:#ffdead,stroke:#333,stroke-width:1px
    classDef external fill:#90ee90,stroke:#333,stroke-width:1px
    classDef config fill:#d3d3d3,stroke:#333,stroke-width:1px
```
