# chroma-core/gpt4-pdf-chatbot-langchain-chroma architecture

> Architecture diagram of the GitHub repository chroma-core/gpt4-pdf-chatbot-langchain-chroma, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chroma-core/gpt4-pdf-chatbot-langchain-chroma
- Repository: https://github.com/chroma-core/gpt4-pdf-chatbot-langchain-chroma

## Overview

##### Project type and purpose
- This is a full-stack Next.js application that builds a ChatGPT-style chatbot for querying multiple PDF files.
- The primary libraries are Next.js (frontend + serverless API), LangChain (chain creation for LLM workflows), Chroma (vector store for embeddings), and OpenAI (GPT-4/other models).

##### File structure
- Top-level directories:
- components – React UI components and layout
- pages – Next.js pages and API routes (`pages/api/chat.ts`)
- scripts – data ingestion script (`scripts/ingest-data.ts`)
- utils – helper functions and chain setup (`utils/makechain.ts`, `utils/customPDFLoader.ts`)
- config – Chroma configuration (`config/chroma.ts`)
- public, styles, types, declarations – static assets, styling, TypeScript types
- Key config files: `.env.example`, `next.config.js`, `tsconfig.json`, `package.json`
- The ingestion process is decoupled into a standalone script that runs in Node, whereas the main app uses Next.js serverless functions.

##### README for additional insights
- Describes a two-step workflow:
a. Convert PDF files into embeddings via the ingestion script and store them in Chroma (Docker container).
b. Run the Next.js app, where client chat input hits a serverless API that retrieves relevant embeddings from Chroma, adds context to a prompt, and calls OpenAI for an answer.
- Mentions key env vars (OPENAI_API_KEY, COLLECTION_NAME) and Docker for Chroma.

##### Main components
a. Frontend UI (Next.js pages + React components)
b. Backend API (Next.js `pages/api/chat.ts`)
c. Ingestion service (Node.js script `scripts/ingest-data.ts`)
d. PDF storage (local `docs` folder)
e. Vector database (Chroma running in Docker)
f. External LLM service (OpenAI API)

##### Relationships and data flow
- Ingestion flow: PDF files → custom PDF loader → LangChain splitter/embeddings → Chroma vector store
- Runtime flow: User in browser → Next.js frontend → API route `/api/chat` → LangChain retrieval via Chroma → constructs prompt → OpenAI API → response → frontend displays answer
- Environment: `.env` provides API keys and collection name injected into both ingestion script and API route

##### Architectural patterns and design principles
- Separation of concerns: data ingestion vs. real-time chat
- Serverless functions for API endpoints (Next.js pattern)
- Use of a vector database for retrieval-augmented generation (RAG)
- Functional composition in LangChain (chains, prompt templates)
- Containerization of Chroma DB for easy local deployment

## Diagram (Mermaid)

```mermaid
graph TB
    %% Ingestion Pipeline
    subgraph "Ingestion Pipeline"
        direction TB
        PDF["PDF Storage (docs folder)"]:::datastore
        Loader["Custom PDF Loader\n(utils/customPDFLoader.ts)"]:::service
        SplitEmb["LangChain Embeddings & Splitter\n(utils/makechain.ts)"]:::service
        IngestScript["Ingestion Script\n(scripts/ingest-data.ts)"]:::service
        ChromaDB["Chroma Vector DB\n(Docker Container)"]:::datastore
    end

    PDF -->|reads PDFs| Loader
    Loader -->|splits & embeds| SplitEmb
    SplitEmb -->|runs ingestion| IngestScript
    IngestScript -->|stores embeddings| ChromaDB

    %% Runtime Chat Pipeline
    subgraph "Runtime Chat Pipeline"
        direction TB
        Browser["Browser (User)"]:::frontend
        subgraph "Next.js Frontend UI"
            direction TB
            App["_app.tsx"]:::frontend
            Index["index.tsx"]:::frontend
            Layout["layout.tsx\n(components/layout.tsx)"]:::frontend
            LoadingDots["LoadingDots.tsx\n(components/ui/LoadingDots.tsx)"]:::frontend
            TextArea["TextArea.tsx\n(components/ui/TextArea.tsx)"]:::frontend
            Accordion["Accordion.tsx\n(components/ui/accordion.tsx)"]:::frontend
        end
        ChatAPI["Next.js API\n(pages/api/chat.ts)"]:::backend
        Retriever["LangChain Retrieval & Chain\n(utils/makechain.ts)"]:::service
        ChromaDB2["Chroma Vector DB\n(Docker Container)"]:::datastore
        OpenAI["OpenAI API"]:::external
    end

    Browser -->|navigates| Index
    Index -->|renders| Layout
    Layout --> LoadingDots
    Layout --> TextArea
    Layout --> Accordion
    Index -->|submits question| ChatAPI

    ChatAPI -->|calls retriever| Retriever
    Retriever -->|queries embeddings| ChromaDB2
    Retriever -->|sends prompt| OpenAI
    OpenAI -->|response| ChatAPI
    ChatAPI -->|returns answer| Index
    Index -->|displays answer| Browser

    %% Configuration and Env
    subgraph "Configuration"
        direction TB
        Env[".env.example"]:::config
        ConfigChroma["Chroma Config\n(config/chroma.ts)"]:::config
    end

    Env --> IngestScript
    Env --> ChatAPI
    ConfigChroma --> IngestScript
    ConfigChroma --> ChatAPI

    %% Click Events
    click Loader "https://github.com/chroma-core/gpt4-pdf-chatbot-langchain-chroma/blob/main/utils/customPDFLoader.ts"
    click SplitEmb "https://github.com/chroma-core/gpt4-pdf-chatbot-langchain-chroma/blob/main/utils/makechain.ts"
    click IngestScript "https://github.com/chroma-core/gpt4-pdf-chatbot-langchain-chroma/blob/main/scripts/ingest-data.ts"
    click App "https://github.com/chroma-core/gpt4-pdf-chatbot-langchain-chroma/blob/main/pages/_app.tsx"
    click Index "https://github.com/chroma-core/gpt4-pdf-chatbot-langchain-chroma/blob/main/pages/index.tsx"
    click Layout "https://github.com/chroma-core/gpt4-pdf-chatbot-langchain-chroma/blob/main/components/layout.tsx"
    click LoadingDots "https://github.com/chroma-core/gpt4-pdf-chatbot-langchain-chroma/blob/main/components/ui/LoadingDots.tsx"
    click TextArea "https://github.com/chroma-core/gpt4-pdf-chatbot-langchain-chroma/blob/main/components/ui/TextArea.tsx"
    click Accordion "https://github.com/chroma-core/gpt4-pdf-chatbot-langchain-chroma/blob/main/components/ui/accordion.tsx"
    click ChatAPI "https://github.com/chroma-core/gpt4-pdf-chatbot-langchain-chroma/blob/main/pages/api/chat.ts"
    click ConfigChroma "https://github.com/chroma-core/gpt4-pdf-chatbot-langchain-chroma/blob/main/config/chroma.ts"
    click Env "https://github.com/chroma-core/gpt4-pdf-chatbot-langchain-chroma/blob/main/.env.example"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#1E88E5,stroke-width:1px;
    classDef backend fill:#C8E6C9,stroke:#388E3C,stroke-width:1px;
    classDef service fill:#E8F5E9,stroke:#43A047,stroke-width:1px;
    classDef datastore fill:#FFF9C4,stroke:#FBC02D,stroke-width:1px,stroke-dasharray: 5 5;
    classDef external fill:#FFE0B2,stroke:#FB8C00,stroke-width:1px;
    classDef config fill:#E1BEE7,stroke:#8E24AA,stroke-width:1px;
```
