# manu9986/llm-booking-analytics architecture

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

- Interactive diagram: https://gitdiagram.com/manu9986/llm-booking-analytics
- Repository: https://github.com/manu9986/llm-booking-analytics

## Overview

##### Project type and purpose
- This is a backend-focused, data-driven “full-stack” service (no separate UI) that offers (a) hotel booking analytics via FastAPI endpoints and (b) a Retrieval-Augmented Generation (RAG) chatbot powered by OpenAI and ChromaDB.

##### File structure
- Top-level scripts and config:
- `precompute.py` (in `scripts/`): loads raw CSV, cleans data, computes analytics, writes to `data/analytics.db` and `data/bookings.db`.
- `main.py` and `database.py` (in `app/`): launch FastAPI app, define endpoints, wire up SQLite and ChromaDB clients.
- `analytics.py` and `rag.py` (in `app/`): modules encapsulating analytics queries and RAG logic.
- Data stores under `data/`:
- `analytics.db` & `bookings.db` (SQLite analytic tables),
- `chromadb/` (vector DB directory),
- raw CSV files.
- Dependencies: FastAPI, ChromaDB, OpenAI, SQLite.

##### Extract architecture clues from the README
- Two main usage flows:
a. **Precompute pipeline**: raw CSV → cleaning → analytic tables & ChromaDB embeddings.
b. **API server**: HTTP REST endpoints → analytics queries & RAG QA calls → JSON responses.
- External service: OpenAI API for GPT-4.

##### Main components
a. **Data Ingestion & Precompute (Offline Batch)**
- Raw CSVs (`hotel_bookings.csv`)
- Precompute script (`scripts/precompute.py`)
- SQLite analytic DB (`analytics.db`, `bookings.db`)
- ChromaDB vector store (`data/chromadb/...`)
b. **API Server (Online / Real-time)**
- FastAPI Application (`app/main.py`)
- Analytics Module (`app/analytics.py`) → reads from `analytics.db`
- RAG Module (`app/rag.py`) → queries ChromaDB + calls OpenAI
c. **External Services**
- OpenAI GPT-4 API
d. **Clients**
- API consumer (e.g., web front-end or CLI)

##### Relationships & data flows
1. CSV files → `precompute.py` → writes to SQLite (`analytics.db`)
2. `main.py` initialization or separate script → processes embeddings → writes to ChromaDB
1. Client HTTP request → FastAPI router
2. If `/api/analytics/*` → `analytics.py` → SQLite query → JSON response
3. If `/ask` → `rag.py` → vector search in ChromaDB → top-k docs → OpenAI API call → answer → JSON response

##### Architectural patterns & design principles
- **Separation of Concerns**:
- Batch processing (data prep) vs. real-time serving (FastAPI).
- Analytics logic vs. RAG logic in separate modules.
- **RAG Pattern**: integrating vector DB + LLM for QA.
- **Precompute for performance**: denormalized analytics tables.

##### Essential elements to capture
- Clear boundary between offline and online.
- Component names matching code modules/files: `precompute.py`, `analytics.py`, `rag.py`, `database.py`.
- All data stores (`analytics.db`, `bookings.db`, `chromadb` directory).
- External dependency: OpenAI API.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Offline Batch
    subgraph "Offline Batch"
        direction TB
        CSV1["hotel_bookings.csv"]:::datastore
        CSV2["cleaned_bookings.csv"]:::datastore
        precompute["precompute.py"]:::offline
        analyticsDB["analytics.db"]:::datastore
        bookingsDB["bookings.db"]:::datastore
        chroma["ChromaDB Store"]:::datastore
        README["README.md"]:::offline
        Report["Report.md"]:::offline
        Req["requirements.txt"]:::offline
    end

    %% Online API
    subgraph "Online API"
        direction TB
        Client["API Client"]:::online
        Main["main.py\nFastAPI App"]:::online
        DBClient["database.py"]:::online
        AnalyticsMod["analytics.py"]:::online
        RAGMod["rag.py"]:::online
        OpenAI["OpenAI GPT-4 API"]:::external
    end

    %% Connections - Offline Flow
    CSV1 -->|"load & clean"| precompute
    precompute -->|"write analytics tables"| analyticsDB
    precompute -->|"write bookings tables"| bookingsDB
    precompute -->|"generate embeddings"| chroma

    %% Connections - Online Flow
    Client -->|"HTTP request"| Main
    Main -->|"initialize DB clients"| DBClient
    DBClient -->|"connect"| analyticsDB
    DBClient -->|"connect"| bookingsDB
    DBClient -->|"connect"| chroma
    Main -->|"route to analytics"| AnalyticsMod
    Main -->|"route to RAG"| RAGMod
    AnalyticsMod -->|"SQL query"| analyticsDB
    AnalyticsMod -->|"SQL query"| bookingsDB
    RAGMod -->|"vector search"| chroma
    RAGMod -->|"OpenAI API call"| OpenAI

    %% Click Events
    click precompute "https://github.com/manu9986/llm-booking-analytics/blob/main/scripts/precompute.py"
    click CSV1 "https://github.com/manu9986/llm-booking-analytics/blob/main/data/hotel_bookings.csv"
    click CSV2 "https://github.com/manu9986/llm-booking-analytics/blob/main/data/cleaned_bookings.csv"
    click analyticsDB "https://github.com/manu9986/llm-booking-analytics/blob/main/data/analytics.db"
    click bookingsDB "https://github.com/manu9986/llm-booking-analytics/blob/main/data/bookings.db"
    click chroma "https://github.com/manu9986/llm-booking-analytics/tree/main/data/chromadb/"
    click Main "https://github.com/manu9986/llm-booking-analytics/blob/main/app/main.py"
    click AnalyticsMod "https://github.com/manu9986/llm-booking-analytics/blob/main/app/analytics.py"
    click RAGMod "https://github.com/manu9986/llm-booking-analytics/blob/main/app/rag.py"
    click DBClient "https://github.com/manu9986/llm-booking-analytics/blob/main/app/database.py"
    click README "https://github.com/manu9986/llm-booking-analytics/blob/main/README.md"
    click Report "https://github.com/manu9986/llm-booking-analytics/blob/main/Report.md"
    click Req "https://github.com/manu9986/llm-booking-analytics/blob/main/requirements.txt"

    %% Styles
    classDef offline fill:#add8e6,stroke:#000,stroke-width:1px
    classDef online fill:#98fb98,stroke:#000,stroke-width:1px
    classDef datastore fill:#d3d3d3,stroke:#000,stroke-width:1px
    classDef external fill:#ffa500,stroke:#000,stroke-width:1px
```
