DocuChat

Give it your documents, ask it anything — DocuChat turns any knowledge base into a conversational AI assistant.

Demo: Tested on real-world data scraped from a live website, proving it works on any text content out of the box.

Preview

Architecture

Browser → React UI (Vite + Tailwind)
               │
               │  POST /api/chat/
               ▼
          FastAPI backend
         /       |       \
        /        |        \
   ChromaDB   Redis      Groq API
  (vectors)  (cache)     (LLM)

Request flow:

1. User sends a question from the React UI
2. FastAPI sanitizes the query and checks Redis cache
3. On cache miss: ChromaDB retrieves the most relevant document chunks
4. The chunks + query are sent to Groq's LLM as a prompt
5. The response is cached in Redis and returned to the frontend

Stack

Layer	Technology
Frontend	React 18, TypeScript, Vite, Tailwind CSS
Backend	Python, FastAPI, Uvicorn
Vector store	ChromaDB (persistent, local)
Embeddings	all-MiniLM-L6-v2 via sentence-transformers
LLM	Groq API (llama-3.1-8b-instant)
Cache	Redis

Prerequisites

• Python 3.10+
• Node.js 18+
• Redis running locally (or via Docker)
• A free Groq API key

Setup

1. Clone the repo

git clone https://github.com/your-username/docuchat.git
cd docuchat

2. Add your knowledge base

Replace backend/app/data/carbonjar_knowledgebase.txt with your own .txt or .md file:

cp your_data.txt backend/app/data/your_data.txt

Then update the path in backend/app/main.py:

kb = load_knowledge_base('app/data/your_data.txt')

The chunker works with any plain text or markdown file — no special formatting required.

3. Configure environment variables

cp backend/.env.example backend/.env

Edit backend/.env:

GROQ_API_KEY=your_groq_api_key_here
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
CHROMA_PATH=./chroma_data

4. Install backend dependencies

cd backend
python -m venv env
source env/bin/activate        # Windows: env\Scripts\activate
pip install -r requirements.txt

5. Install frontend dependencies

cd frontend
npm install

Running the app

Open three terminals:

Terminal 1 — Redis:

redis-server
# or via Docker:
docker run -d -p 6379:6379 redis

Terminal 2 — Backend:

cd backend
source env/bin/activate
uvicorn app.main:app --reload

On first run, the backend will automatically chunk your document, generate embeddings, and store them in ChromaDB. Subsequent restarts skip this step unless you delete backend/chroma_data/.

Terminal 3 — Frontend:

cd frontend
npm run dev

Customising the UI

Two components are designed to be adapted to your own project:

frontend/src/components/custom/chatinput.tsx — contains the suggested action buttons shown before the user types anything. Update the suggestedActions array to match your own data:

const suggestedActions = [
  {
    title: 'What is your product?',
    label: 'learn about us',
    action: 'What is your product?',
  },
  // add your own questions here
];

frontend/src/components/custom/overview.tsx — the welcome screen shown when the chat is empty. Update the title and subtitle to match your assistant's purpose:

<strong>Your Assistant Name</strong><br />
Your one-line description here.

Swapping the knowledge base

1. Add your new file to backend/app/data/
2. Update the path in backend/app/main.py
3. Delete the old vector store so it rebuilds:

rm -rf backend/chroma_data

4. Restart the backend — it will re-index automatically.

Chunking settings

Adjust chunk size and overlap in backend/scripts/load_documents.py:

CHUNK_SIZE    = 500   # characters per chunk — increase for longer context
CHUNK_OVERLAP = 50    # overlap between chunks — increase if answers feel cut off

Project structure

├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI app, startup, CORS
│   │   ├── config.py            # Environment variables
│   │   ├── routes/
│   │   │   └── chat.py          # POST /api/chat/ endpoint
│   │   ├── services/
│   │   │   ├── chatbot.py       # Orchestration: cache → retrieve → LLM
│   │   │   ├── retriever.py     # ChromaDB similarity search
│   │   │   ├── sanitizer.py     # Input sanitization
│   │   │   └── llm.py           # Groq API client
│   │   └── data/                # Your knowledge base files go here
│   ├── scripts/
│   │   └── load_documents.py    # Chunking + embedding + ChromaDB indexing
│   └── requirements.txt
├── frontend/
│   └── src/
│       ├── components/
│       │   └── custom/
│       │       ├── chatinput.tsx   # ← customise suggested actions here
│       │       └── overview.tsx    # ← customise welcome screen here
│       └── pages/chat/
│           └── chat.tsx
├── docs/
│   ├── chatbot.png
│   └── chatbot_architecture.svg
├── .gitignore
└── README.md

Troubleshooting

API error: 401 — your Groq API key is invalid or not loaded. Check backend/.env and make sure you're running uvicorn from inside the backend/ directory.

OPTIONS ... 400 Bad Request — CORS preflight failing. Make sure your frontend URL is in allow_origins in backend/app/main.py.

Answers seem off-topic — try reducing CHUNK_SIZE so retrieved chunks are more focused, or increase top_k in backend/app/services/chatbot.py.

ChromaDB rebuilds on every restart — this happens if chroma_data/ was deleted or is empty. It only indexes once unless you remove the folder.

License

MIT