RAGChatbot (Client + Server)

Full‑stack RAG chatbot with a React + Vite frontend and a FastAPI backend. This README covers local development and production deployment on AWS (App Runner for the backend, Amplify for the frontend).

Monorepo Layout

RAGChatbot/
├── Client/   # React + Vite + TypeScript frontend
└── Server/   # FastAPI backend

Prerequisites

• Node.js 18+ (recommended 20)
• Python 3.11+
• PostgreSQL (local or managed)

Quick Start (Local)

1) Backend (FastAPI)

From Server/:

# Create and activate a virtualenv (optional but recommended)
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp env.example .env
# Edit .env (DB URL, SECRET_KEY, embeddings provider/model, API keys, etc.)

# Create DB and run migrations (alembic is already configured)
alembic upgrade head

# Run API
env DEBUG=true uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Health checks:

• GET / returns a running message
• GET /health returns { "status": "healthy" }

2) Frontend (Vite React)

From Client/:

# Install deps
npm install

# Configure environment
cp env.example .env
# Ensure VITE_API_URL points to the backend (e.g. http://localhost:8000)

# Run dev server
npm run dev

Open http://localhost:5173 and ensure API calls hit VITE_API_URL.

Environment Variables

Server (Server/.env)

See Server/env.example for the full list. Common ones:

• DATABASE_URL (e.g. postgresql://user:password@localhost/ragchatbot)
• SECRET_KEY
• Embeddings:
  • EMBEDDING_PROVIDER = openai | nvidia | sentence_transformers
  • EMBEDDING_MODEL (e.g. text-embedding-ada-002 for OpenAI, nvidia/llama-text-embed-v2 for NVIDIA)
  • For OpenAI: OPENAI_API_KEY
  • For NVIDIA NIM (OpenAI-compatible): NVIDIA_API_KEY, optional NVIDIA_BASE_URL (default https://integrate.api.nvidia.com/v1)
  • Pinecone index should be 1024-d for llama-text-embed-v2
• Pinecone: PINECONE_API_KEY, PINECONE_ENVIRONMENT, PINECONE_INDEX_NAME
• DEBUG (true/false)
• CORS: update ALLOWED_ORIGINS in app/core/config.py to include your frontend origin(s)

Client (Client/.env)

• VITE_API_URL (e.g. http://localhost:8000 or your production API URL)

Embedding Providers

You can switch embedding backends without code changes using environment variables.

• OpenAI
  • .env:

    EMBEDDING_PROVIDER=openai
    EMBEDDING_MODEL=text-embedding-3-small
    OPENAI_API_KEY=sk-...
    

• NVIDIA NIM (Llama Text Embed v2)
  • .env:

    EMBEDDING_PROVIDER=nvidia
    EMBEDDING_MODEL=nvidia/nv-embed-v1
    NVIDIA_API_KEY=nvapi-...
    # NVIDIA_BASE_URL (optional, defaults to https://integrate.api.nvidia.com/v1)
    

Linting & Formatting

Backend (Ruff)

From Server/:

# Lint
ruff check .
# Auto-fix
ruff check --fix .
# Format
ruff format .

Frontend (ESLint + Prettier)

From Client/:

npm run lint
npm run format

Production Deployment on AWS

Backend: AWS App Runner

You can deploy the FastAPI service with App Runner using the repo as the source.

Recommended settings:

• Source directory: Server
• Runtime: Python 3.11
• Port: 8000
• Health check path: /health
• Environment variables: set all from Server/env.example (especially DATABASE_URL, secrets, embeddings provider/API keys)

Commands:

• Build command:

  pip install -r requirements.txt

• Start command:

  alembic upgrade head && uvicorn app.main:app --host 0.0.0.0 --port 8000

Database:

• Use Amazon RDS (PostgreSQL). Provide the RDS connection string in DATABASE_URL.

CORS:

• Ensure the frontend domain is included in ALLOWED_ORIGINS (see Server/app/core/config.py).

Custom domain (optional):

• Attach a custom domain to App Runner and add it to ALLOWED_ORIGINS.

Frontend: AWS Amplify Hosting

You can host the Vite site with Amplify connected to this repository.

Recommended settings:

• App root: Client
• Node version: 18 or 20
• Build settings (Amplify auto-detects Vite). If needed, use:

  version: 1
  applications:
    - appRoot: Client
      frontend:
        phases:
          preBuild:
            commands:
              - npm ci
          build:
            commands:
              - npm run build
        artifacts:
          baseDirectory: dist
          files:
            - '**/*'
        cache:
          paths:
            - node_modules/**

• Environment variables: set VITE_API_URL to your App Runner URL or your custom API domain

Custom domain (optional):

• Connect your domain in Amplify and point it to the Amplify app.

API Overview

• Auth: /api/v1/auth/*
• Chat: /api/v1/chat/*

Notes & Best Practices

• Keep secrets out of the repo; use AWS parameter store/Secrets Manager for production values.
• For production, set DEBUG=false.
• Scale App Runner based on traffic; use RDS instance classes and storage suitable for expected load.
• Monitor with CloudWatch; add structured logging as needed.