# lillianassefa/contract-ai-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/lillianassefa/contract-ai-chatbot
- Repository: https://github.com/lillianassefa/contract-ai-chatbot

## Overview

##### Project type and purpose
- This is a full-stack RAG (Retrieval-Augmented Generation) system for Contract Q&A.
- Front-end: React single-page application (SPA) for user interaction.
- Back-end: Python service implementing ingestion, retrieval, and generation stages.
- Data layer: a local vector store (SQLite/Chroma) plus contract storage.
- External service: LLM API (e.g., OpenAI) for answer generation.

##### File structure
Top level:
- backend/ – Python notebooks (prototypes) under notebooks/, core service under src/
- database/ – vectorstore.py, DB access wrappers
- frontend/ – React app (public/, src/, package.json)
- environment.yml, requirements.txt – Python dependencies
Key back-end modules (backend/src):
- upload.py – handles PDF/text ingestion
- retriever.py – queries vector store
- generator.py – wraps LLM call
- main.py – HTTP API entry point
- constants.py, init_conf.py – configuration
Data files: backend/src/uploads/contract.pdf/.txt, notebooks/db/chroma.sqlite3

##### Insights from README
- Entry point: python src/main.py
- Two phases of implementation: prototype (notebooks) vs. production code (src)
- React UI demonstrates chat interface components (ChatHistory, ChatInput, TopBar)

##### Components & interactions
a. Main components
1. Client (React SPA)
2. API Layer (Flask/FastAPI in main.py)
3. Ingestion Module (upload.py)
4. Vector Store (database/vectorstore.py + SQLite/Chroma)
5. Retrieval Module (retriever.py)
6. Generation Module (generator.py → LLM API)
7. Notebooks (research/proto, optional)
b. Relationships & data flow
1. User types question in ChatInput → React sends HTTP POST /ask → API Layer
2. API calls retriever → queries Vector Store → returns top-k passages
3. Passages + user query → generator → calls external LLM → returns answer
4. API returns JSON answer → React updates ChatHistory
5. Ingestion: Admin uploads contract via HTTP POST /upload → upload.py extracts text → vectorizes embeddings → stores in Vector Store
c. Architectural patterns
- Separation of concerns: Ingestion, Retrieval, Generation as distinct modules
- RAG pipeline: “retrieve then generate”
- SPA ↔ API pairing
- Data store abstraction (vectorstore.py)
d. Technologies/frameworks
- Front-end: React, JavaScript, CSS (create-react-app)
- Back-end: Python (Flask or FastAPI), Jupyter notebooks for prototyping
- Data store: Chroma (SQLite) for vector embeddings
- LLM integration: OpenAI (or similar) via generator.py
- Env management: requirements.txt, environment.yml

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Client Layer
  subgraph "Client Layer"
    direction TB
    Client["React SPA"]:::frontend
    Index["index.js"]:::frontend
    App["App.js"]:::frontend
    ChatHist["ChatHistory.js"]:::frontend
    ChatInput["ChatInput.js"]:::frontend
    TopBar["TopBar.js"]:::frontend
  end

  %% API Layer
  subgraph "API Layer"
    direction TB
    API["API Layer\n(main.py)"]:::backend
    Config["Configuration\n(constants.py, init_conf.py)"]:::backend
  end

  %% Processing Layer
  subgraph "Processing Layer"
    direction TB
    Ingest["Ingestion Module\n(upload.py)"]:::backend
    Retrieval["Retrieval Module\n(retriever.py)"]:::backend
    Generate["Generation Module\n(generator.py)"]:::backend
  end

  %% Data Layer
  subgraph "Data Layer"
    direction TB
    VS["Vector Store\n(vectorstore.py)"]:::data
    ContractPDF["contract.pdf"]:::data
    ContractTXT["contract.txt"]:::data
  end

  %% External Services
  subgraph "External Services"
    direction TB
    LLM["LLM API"]:::external
  end

  %% Notebooks
  subgraph "Prototype Notebooks"
    direction TB
    NB1["RAG-Chatbot.ipynb"]:::backend
    NB2["simple_rag.ipynb"]:::backend
    NB3["final-rag-pipline.ipynb"]:::backend
    ChromaDB["chroma.sqlite3"]:::data
  end

  %% Relationships
  Client -->|"POST /ask"| API
  Client -->|"POST /upload"| API
  API -->|"load config"| Config
  API -->|"ingest endpoint"| Ingest
  Ingest -->|"extract & embed"| VS
  Ingest -->|stores| ContractPDF
  Ingest -->|stores| ContractTXT
  API -->|"ask endpoint"| Retrieval
  Retrieval -->|"query"| VS
  VS -->|"return passages"| Retrieval
  Retrieval -->|"passages + query"| Generate
  Generate -->|"call LLM"| LLM
  LLM -->|"response"| Generate
  Generate -->|"answer"| API
  API -->|"return JSON"| Client

  %% Notebooks links
  NB1 --> ChromaDB
  NB2 --> ChromaDB
  NB3 --> ChromaDB

  %% Click Events
  click Client "https://github.com/lillianassefa/contract-ai-chatbot/tree/main/frontend/"
  click Index "https://github.com/lillianassefa/contract-ai-chatbot/blob/main/frontend/src/index.js"
  click App "https://github.com/lillianassefa/contract-ai-chatbot/blob/main/frontend/src/App.js"
  click ChatHist "https://github.com/lillianassefa/contract-ai-chatbot/blob/main/frontend/src/pages/chat/ChatHistory.js"
  click ChatInput "https://github.com/lillianassefa/contract-ai-chatbot/blob/main/frontend/src/pages/chat/ChatInput.js"
  click TopBar "https://github.com/lillianassefa/contract-ai-chatbot/blob/main/frontend/src/pages/TopBar/TopBar.js"
  click API "https://github.com/lillianassefa/contract-ai-chatbot/blob/main/backend/src/main.py"
  click Config "https://github.com/lillianassefa/contract-ai-chatbot/blob/main/backend/src/constants.py"
  click Config "https://github.com/lillianassefa/contract-ai-chatbot/blob/main/backend/src/init_conf.py"
  click Ingest "https://github.com/lillianassefa/contract-ai-chatbot/blob/main/backend/src/upload.py"
  click Retrieval "https://github.com/lillianassefa/contract-ai-chatbot/blob/main/backend/src/retriver.py"
  click Generate "https://github.com/lillianassefa/contract-ai-chatbot/blob/main/backend/src/generator.py"
  click ContractPDF "https://github.com/lillianassefa/contract-ai-chatbot/blob/main/backend/src/uploads/contract.pdf"
  click ContractTXT "https://github.com/lillianassefa/contract-ai-chatbot/blob/main/backend/src/uploads/contract.txt"
  click VS "https://github.com/lillianassefa/contract-ai-chatbot/blob/main/database/vectorstore.py"
  click NB1 "https://github.com/lillianassefa/contract-ai-chatbot/blob/main/backend/notebooks/RAG-Chatbot.ipynb"
  click NB2 "https://github.com/lillianassefa/contract-ai-chatbot/blob/main/backend/notebooks/simple_rag.ipynb"
  click NB3 "https://github.com/lillianassefa/contract-ai-chatbot/blob/main/backend/notebooks/final-rag-pipline.ipynb"
  click ChromaDB "https://github.com/lillianassefa/contract-ai-chatbot/blob/main/backend/notebooks/db/chroma.sqlite3"

  %% Styles
  classDef frontend fill:#E3F2FD,stroke:#2196F3,color:#0D47A1,stroke-width:1px
  classDef backend fill:#E8F5E9,stroke:#4CAF50,color:#1B5E20,stroke-width:1px
  classDef data fill:#FFF3E0,stroke:#FB8C00,color:#E65100,stroke-width:1px
  classDef external fill:#ECEFF1,stroke:#90A4AE,color:#37474F,stroke-width:1px
```
