# vuhai2002/chatbot-ai architecture

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

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

## Overview

##### Project Type and Purpose
- This is a backend API service (no UI/front end) that allows users to upload documents, converts them into vector embeddings, stores metadata and embeddings, and answers natural-language queries.
- It’s an open-source tool / microservice built on FastAPI, leveraging OpenAI, a vector DB (FAISS/ChromaDB), PostgreSQL, and Firebase Storage.

##### File Structure
- Top-level:
– main.py (entry point)
– app/ (application package)
– app/api/routes/ (FastAPI routers for upload, ask, list, delete)
– app/core/ (business logic: document_processor, embedding, qa_chain, storage)
– app/db/ (vector_store, models for metadata)
– app/utils/ (logger)
– config.py (.env integration)
- Key patterns:
– Layered architecture (API layer, core services layer, data layer)
– Clear separation of concerns

##### Extract Insights from README
- Components: FastAPI, OpenAI, Firebase Storage, FAISS/ChromaDB, PostgreSQL
- Data flow: Upload → vectorize → store → semantic search → QA
- Endpoints: /documents/upload, /ask, /documents, DELETE /documents/{id}

a. Main components:
1) Client (e.g., Postman or frontend)
2) FastAPI Service (app/main.py)
3) API Routers (app/api/routes)
4) Core Services (document_processor, embedding, qa_chain, storage)
5) Metadata DB (PostgreSQL)
6) Vector DB (FAISS or ChromaDB)
7) File Storage (Firebase Storage)
8) External API (OpenAI Embeddings & Completion)
b. Data flows / interactions:
- Client → HTTP POST /documents/upload → FastAPI Router
- Router calls document_processor → chunks & cleans document
- document_processor → OpenAI Embeddings → returns vectors
- Core/storage → save original file to Firebase Storage
- Core/storage → save metadata to PostgreSQL
- Core/storage → save embeddings to vector DB
- Client → HTTP POST /ask → Router → qa_chain
- qa_chain → vector DB (semantic similarity search) → top-k chunks
- qa_chain → OpenAI Completion API → answer synthesis → client
- Client → GET/DELETE /documents → Router → storage → PostgreSQL & (optionally) vector DB & Storage
c. Architectural patterns:
- Layered architecture (Presentation/API → Business/Core → Data/Storage)
- Adapter pattern for interchangeable vector DB (faiss vs chroma)
- Dependency injection via FastAPI for services and config
d. Key technologies: FastAPI, SQLAlchemy (PostgreSQL), FAISS/Chroma, Firebase SDK, OpenAI Python SDK

1) Sketch the user/client on the left.
5) Connect:
- Client → API Routers → Core Services
- Core → Firebase (store files)
- Core → OpenAI (embeddings & QA)
- Core → PostgreSQL (metadata)
- Core → Vector DB (vectors)
- Client ← Core (answers, document list, delete confirmations)

## Diagram (Mermaid)

```mermaid
flowchart TB
    Client["Client (e.g., Postman)"]:::external

    Service["FastAPI Service\n(app/main.py)"]:::api
    click Service "https://github.com/vuhai2002/chatbot-ai/blob/main/app/main.py"

    CLI["CLI Launcher\n(main.py)"]:::api
    click CLI "https://github.com/vuhai2002/chatbot-ai/blob/main/main.py"

    Config["Configuration\n(app/config.py)"]:::api
    click Config "https://github.com/vuhai2002/chatbot-ai/blob/main/app/config.py"

    subgraph "API Layer"
        DocRouter["Documents Router\n(app/api/routes/documents.py)"]:::api
        click DocRouter "https://github.com/vuhai2002/chatbot-ai/blob/main/app/api/routes/documents.py"
        QARouter["QA Router\n(app/api/routes/qa.py)"]:::api
        click QARouter "https://github.com/vuhai2002/chatbot-ai/blob/main/app/api/routes/qa.py"
    end

    subgraph "Core Services"
        DocProc["Document Processor\n(app/core/document_processor.py)"]:::core
        click DocProc "https://github.com/vuhai2002/chatbot-ai/blob/main/app/core/document_processor.py"
        Embedding["Embedding Service\n(app/core/embedding.py)"]:::core
        click Embedding "https://github.com/vuhai2002/chatbot-ai/blob/main/app/core/embedding.py"
        QAChain["QA Chain\n(app/core/qa_chain.py)"]:::core
        click QAChain "https://github.com/vuhai2002/chatbot-ai/blob/main/app/core/qa_chain.py"
        Storage["Storage Service\n(app/core/storage.py)"]:::core
        click Storage "https://github.com/vuhai2002/chatbot-ai/blob/main/app/core/storage.py"
    end

    subgraph "Data Layer"
        Postgres["PostgreSQL\n(app/db/models.py)"]:::data
        click Postgres "https://github.com/vuhai2002/chatbot-ai/blob/main/app/db/models.py"
        VectorDB["Vector DB\n(app/db/vector_store.py)"]:::data
        click VectorDB "https://github.com/vuhai2002/chatbot-ai/blob/main/app/db/vector_store.py"
    end

    Logger["Logger Utility\n(app/utils/logger.py)"]:::util
    click Logger "https://github.com/vuhai2002/chatbot-ai/blob/main/app/utils/logger.py"

    subgraph "External Services"
        OpenAI["OpenAI API"]:::external
        Firebase["Firebase Storage"]:::external
    end

    README["Project Docs\n(README.md)"]:::util
    click README "https://github.com/vuhai2002/chatbot-ai/blob/main/README.md"
    Req["Dependencies\n(requirements.txt)"]:::util
    click Req "https://github.com/vuhai2002/chatbot-ai/blob/main/requirements.txt"

    Client --> Service
    Service --> Config
    Service --> DocRouter
    Service --> QARouter

    DocRouter --> DocProc
    QARouter --> QAChain

    DocProc --> Embedding
    Embedding --> OpenAI
    DocProc --> Storage

    Storage --> Firebase
    Storage --> Postgres
    Storage --> VectorDB

    QAChain --> VectorDB
    QAChain --> OpenAI

    DocProc -.-> Logger
    Embedding -.-> Logger
    QAChain -.-> Logger
    Storage -.-> Logger
    DocRouter -.-> Logger
    QARouter -.-> Logger
    Service -.-> Logger

    classDef api fill:#cce5ff,stroke:#1e70bf,color:#0b2948;
    classDef core fill:#d4edda,stroke:#287d41,color:#155724;
    classDef data fill:#fff3cd,stroke:#856404,color:#795e26;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#495057,stroke-dasharray: 2 2;
    classDef util fill:#f0e6ff,stroke:#7e3ec0,color:#3d1556,stroke-dasharray: 2 2;
```
