Bard

Bard is an offline, full-stack AI chatbot application designed as a showcase for AI engineering skills. It demonstrates the integration of a local Large Language Model (LLM) with a modern web frontend, robust backend, and persistent chat memory, all orchestrated with best practices in software engineering.

Features

• 💻 Modern Frontend – Built with React (Vite), TanStack Start, TailwindCSS, and Shadcn UI.
• 🔌 Pluggable LLM – Any OpenAI-compatible API (e.g. Fireworks AI) or a local Ollama server
• 💾 Persistent Chat – Session Handling and Conversation History via langchain-postgres
• 🚀 Chat Streaming – Chat completions are streamed from server for UX
• ⏱️ Rate Limiting – Per-user message caps (n messages per rolling window) enforced in the backend
• 🐳 Fully Containerized – Easy to setup and run with Docker Compose

Tech Stack

• Database: Supabase (Postgres)
• LLM: OpenAI-compatible API (e.g. Fireworks AI) or Ollama (via LangChain)
• Backend: FastAPI (Python)
• Frontend: React (Vite, TanStack Start), TailwindCSS, Shadcn UI
• Deployment: Docker & Docker Compose

Documentation

Project documentation is available via a Jupyter Notebook

Usage

The application follows the typical workflow and user experience of most chat applications:

• select your Username, as this is used to identify each user's sessions and chats
• once on the chat screen, use the text input to send a message (you can shift + enter to create a new line, but clicking enter automatically sends the message!)
• you can view your past and current thread on the sidebar on the left (you can ctrl/cmd + b on your keyboard to show/hide the sidebar at any time)

Getting Started

Note

The project was develoepd and tested on a machine running Ubuntu 24.04 LTS with a x64 Ryzen 5 CPU, 16 GB RAM, and Nvidia GPU. However, it was tested to work in Windows 11 on the same system, then on MacOS Sequoia running on Apple Silicon (M2)

Requirements

• Docker
• NVIDIA Container Toolkit (only for the optional Ollama GPU profile)
• Python
• Node.js

Important

The default LLM provider is an OpenAI-compatible API (Fireworks AI running deepseek-v4p1-flash). Set your OPENAI_API_KEY in .env. To run fully local instead, set LLM_PROVIDER=ollama and start the optional Ollama profile as described below. docker-compose.nvidia.yml adds GPU support to that optional Ollama service.

Quickstart via Docker

1. Clone the repository

git clone https://github.com/reddiedev/bluedrive-chat 
cd bluedrive-chat

2. Load the default environment variables and add your API key and Supabase connection string

cp .env.example .env
cp .env.example frontend/.env
cp .env.example backend/.env
# then set OPENAI_API_KEY (and OPENAI_MODEL/OPENAI_BASE_URL if not using the defaults)
# and DATABASE_URL (the session pooler connection string from the Supabase dashboard)

3. Reserve Host Ports Please pause/stop any services running on the following ports to prevent port conflict. Otherwise, please update the .env files or the docker-compose files

• 3000 - Frontend React App
• 8000 - Backend FastAPI Server
• 11434 - Ollama API (only when using the optional ollama profile)

4. Start the application stack

docker compose down -v # remove old containers and volumes, if any

# default: OpenAI-compatible provider (Fireworks AI)
docker compose up --build

# optional: local Ollama instead
# (set LLM_PROVIDER=ollama in .env first)
docker compose --profile ollama up --build

On my machine, it takes roughly ~1 minute to build all services without cache.

5. On your browser, you can view the app at http://localhost:3000

Note

The Ollama profile downloads its models on first start, which can take a few minutes and ~10 GB of disk space. When using the default OpenAI-compatible provider, no local models are downloaded.

Database (Supabase)

The database is hosted on Supabase. Schema changes are versioned as migrations under supabase/migrations/, and demo data lives in supabase/seed.sql.

supabase link --project-ref <your-project-ref>  # once, links the CLI to the project
supabase db push                                # apply migrations to the hosted database
supabase db reset --linked                      # re-apply migrations + seed (wipes data)

For local development you can instead run a full local Supabase stack (requires Docker). Point DATABASE_URL at the connection string printed by supabase start:

supabase start

Optional: Local Ollama

Add the optional Ollama profile if you want a local LLM:

docker compose --profile ollama up -d --build ollama

FastAPI Backend

1. Install Python 3.12 on your Local machine

python --version
>>> Python 3.12.7

For managing python instances, I usually prefer using a virtual env using uv

cd backend
uv venv 
source .venv/bin/activate
uv pip install -r requirements.txt

2. Install requirements then run the main.py app via Uvicorn

cd backend
pip install -r requirements.txt

uv run main.py
python main.py
python3 main.py

React Frontend

1. Install Node.js v20 and pnpm on your Local machine

node -v
>>> v20.18.0

npm install -g pnpm
pnpm setup # if you haven't used pnpm before

For managing Node environments, I prefer to use it via nvm

nvm i 20
nvm use 20

2. Install the requirements and use the .env example

cp .env frontend/.env
cd frontend
pnpm install --frozen-lockfile

3. Run the app

pnpm run dev

pnpm run build
pnpm run start

Tests

Please follow the same setup in FastAPI Backend

cd backend/tests
pytest -v

Acknowledgements

This project was heavenly inspired by open-webui as well as t3.chat

Troubleshooting

For any .env problems, please cd your terminal into the root directory, then run this command to load the .env to your terminal

export $(grep -v '^#' .env | xargs)