QUICKSTART.md

Quick Start Guide: Frontend & Backend

System: RBAC-Enforced RAG Chatbot (Groq + SentenceTransformer)
Date: March 26, 2026

---

🚀 Quick Start (2 Minutes)

Option 1: Using Two Terminal Windows (Recommended)

Terminal 1: Start Backend

cd c:\development\CodeBasics\Bootcamp\Assignment\Assignment1\app\backend

python -m uvicorn main:app --reload

Expected Output:

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000

Terminal 2: Start Frontend

cd c:\development\CodeBasics\Bootcamp\Assignment\Assignment1\app\frontend-nextjs

npm run dev

Expected Output:

> next dev
  ▲ Next.js 14.0.0
  - Local:        http://localhost:3000
  - Environments: .env.local

 ✓ Ready in 2.3s

3. Open Browser

http://localhost:3000

---

⚙️ Pre-Startup Checklist

1. Backend Already Has GROQ_API_KEY ✅

# Check .env file
cat app\backend\.env

Current value:

GROQ_API_KEY=gsk_your_groq_api_key_here

✅ Already configured!

2. Frontend Dependencies

# Navigate to frontend
cd app\frontend-nextjs

# Check if node_modules exists
dir node_modules

# If not, install dependencies
npm install

# Run dev server
npm run dev

3. Backend Dependencies (If Issues)

# Navigate to backend
cd app\backend

# Check Python version (must be 3.8+)
python --version

# Option A: Create fresh virtual environment
python -m venv venv

# Activate (Windows)
venv\Scripts\activate

# Option B: Use existing Python
# Install dependencies
pip install -r requirements.txt

---

📋 Full Setup Process

Step 1: Setup Backend

# Navigate to backend
cd c:\development\CodeBasics\Bootcamp\Assignment\Assignment1\app\backend

# Option A: Fresh environment (RECOMMENDED for clean state)
python -m venv venv
venv\Scripts\activate

# Install all dependencies
pip install -r requirements.txt

# Verify Python syntax (all files)
python -m py_compile main.py

# Start backend
python -m uvicorn main:app --reload

Step 2: Setup Frontend (New Terminal)

# Navigate to frontend
cd c:\development\CodeBasics\Bootcamp\Assignment\Assignment1\app\frontend-nextjs

# Install dependencies (if not already done)
npm install

# Start dev server
npm run dev

Step 3: Open in Browser

http://localhost:3000

---

🔐 Login with Demo Users

Available Demo Users

Username	Password	Role	Access
emp_john	password123	employee	general docs only
fin_alice	password123	finance	general + finance docs
eng_bob	password123	engineering	general + engineering docs
mkt_sarah	password123	marketing	general + marketing docs
ceo_mary	password123	c_level	ALL docs

Demo Login Steps:

1. Go to http://localhost:3000
2. Click "Login"
3. Enter username (e.g., emp_john)
4. Enter password: password123
5. Click "Login"

Admin Access:

username: admin
password: admin123

---

📊 Infrastructure Configuration

Service	Port	URL	Status
Backend API	8000	http://localhost:8000	✅ POST /api/chat
Frontend	3000	http://localhost:3000	✅ GUI
Qdrant Cloud	6333	cloud.qdrant.io	✅ Persistent Cloud

---

🔍 Testing the System

1. Test Backend Health

# In any terminal/PowerShell
curl http://localhost:8000/api/health

Expected Response:

{"status": "ok", "timestamp": "2026-03-26T..."}

2. Test Chat Endpoint

curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_001",
    "user_role": "finance",
    "query": "What is financial policy?"
  }'

Expected Response:

{
  "answer": "The financial policy states...",
  "sources": ["chunk_001", "chunk_002"],
  "route": "finance",
  "flags": {"hallucination": false, "pii": false},
  "rbac_denied": false
}

3. Test Frontend

Open browser: http://localhost:3000
Login with: emp_john / password123
Chat about available documents

---

⚠️ Troubleshooting

Backend Won't Start

Error: ModuleNotFoundError: No module named 'pydantic_core'

Cause: Pydantic dependency conflict (environment-specific issue)

Solution Options:

Option 1: Fresh Virtual Environment (RECOMMENDED)

# Remove old env
Remove-Item -Recurse -Force venv

# Create fresh env
python -m venv venv

# Activate
venv\Scripts\activate

# Install
pip install -r requirements.txt

# Start
python -m uvicorn main:app --reload

Option 2: Force Reinstall

pip install --force-reinstall --no-cache-dir -r requirements.txt

Option 3: Use Python in Docker (If Local Issues Persist)

# Install Docker
# Then run backend in container
docker build -t finbot-backend .
docker run -p 8000:8000 finbot-backend

---

Error: GROQ_API_KEY not found

Solution: Verify .env file

# Check .env exists
dir .env

# Check content
type .env

# Should show: GROQ_API_KEY=gsk_...

If missing, add it:

# Get your Groq API key from: https://console.groq.com/keys
# Then edit .env and add:
GROQ_API_KEY=your_key_here

---

Error: Port 8000 already in use

Solution: Use different port or kill existing process

# Find process using port 8000
netstat -ano | findstr :8000

# Kill process (replace PID with actual number)
taskkill /PID 12345 /F

# Or start on different port
python -m uvicorn main:app --reload --port 8001

---

Frontend Won't Start

Error: npm: command not found

Solution: Install Node.js

Download from: https://nodejs.org
Install Node.js (includes npm)
Restart terminal
Verify: npm --version

---

Error: Port 3000 already in use

Solution: Kill existing process

# Find process using port 3000
netstat -ano | findstr :3000

# Kill process
taskkill /PID 12345 /F

# Or use different port
npm run dev -- --port 3001

---

Error: Cannot find module 'next'

Solution: Install dependencies

cd app\frontend-nextjs
npm install
npm run dev

---

Services Won't Communicate

Symptom: Frontend shows "Connection refused" error

Check:

1. Backend running on port 8000? ✅
2. Frontend running on port 3000? ✅
3. CORS enabled in backend? ✅ (FastAPI automatically enables)

Debug:

# From frontend terminal, test backend
curl http://localhost:8000/api/health

Should return JSON response.

---

🎯 Startup Workflow

START HERE
    │
    ▼
┌─────────────────────┐
│ 1. Check Groq Key   │
│    (.env configured)│
└────────┬────────────┘
    YES │
    │
    ▼
┌─────────────────────┐
│ 2. Install Backend  │
│    pip install -r.. │
└────────┬────────────┘
    │
    ▼
┌─────────────────────┐
│ 3. Start Backend    │
│    Terminal 1       │
│    port 8000        │
└────────┬────────────┘
    │
    ▼
┌─────────────────────┐
│ 4. Install Frontend │
│    npm install      │
└────────┬────────────┘
    │
    ▼
┌─────────────────────┐
│ 5. Start Frontend   │
│    Terminal 2       │
│    port 3000        │
└────────┬────────────┘
    │
    ▼
┌─────────────────────┐
│ 6. Open Browser     │
│ localhost:3000      │
└────────┬────────────┘
    │
    ▼
┌─────────────────────┐
│ 7. Login & Chat!    │
│ emp_john / pwd123   │
└─────────────────────┘

---

📦 What Gets Started

Backend (Port 8000)

Services Started:

• ✅ FastAPI server
• ✅ Document converter (Docling)
• ✅ Vector store (Qdrant) - in-memory mode
• ✅ Embeddings model (SentenceTransformer) - auto-downloaded on first use
• ✅ Groq LLM API client (uses external API)

API Endpoints:

• POST /api/chat — Chat with RBAC
• GET /api/health — Health check
• GET /api/users/{username} — User lookup
• POST /admin/create-user — Add user
• POST /admin/ingest — Upload documents

Frontend (Port 3000)

Next.js Components:

• ✅ Login screen with demo users
• ✅ Chat interface (real-time messages)
• ✅ User profile display
• ✅ Document sources viewer
• ✅ Admin panel (user management)
• ✅ Safety flags display

---

🔄 Development Workflow

Making Changes

Backend Code Changes

Edit: app/backend/pipeline/rag_pipeline.py
     ↓
[Uvicorn hot-reload active]
     ↓
Backend automatically restarts
     ↓
Test in browser/Postman

Frontend Code Changes

Edit: app/frontend-nextjs/components/ChatInterface.tsx
     ↓
[Next.js hot-reload active]
     ↓
Frontend automatically refreshes
     ↓
Test in browser

No Manual Restart Needed

Both services have hot-reload enabled:

• Backend: --reload flag in uvicorn
• Frontend: Built-in Next.js dev server reload

Just save files and changes appear instantly!

---

📊 Performance Expectations

First Run

• Backend startup: 3-5 seconds
• SentenceTransformer download: 1-2 minutes (first time only, ~500MB)
• Frontend startup: 5-10 seconds
• First chat response: 2-3 seconds (model needs to initialize)

Subsequent Runs

• Backend startup: 2-3 seconds
• Frontend startup: 3-5 seconds
• Chat response: 1-1.2 seconds ⚡

---

💡 Tips & Best Practices

1. Use Debug Mode

# Backend with verbose logging
DEBUG=True python -m uvicorn main:app --reload --log-level debug

2. Test with curl/Postman

# Health check
curl http://localhost:8000/api/health

# Chat request
curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"user_id": "u1", "user_role": "employee", "query": "test"}'

3. Watch Logs

Backend logs show:

• Received queries ✅
• RBAC decisions ✅
• Groq API calls ✅
• Error traceback ✅

4. Keep Both Terminals Open

Don't close either terminal while developing:

Terminal 1: Backend (port 8000)   [Keep Running]
Terminal 2: Frontend (port 3000)  [Keep Running]
Terminal 3: Testing/Git commands  [Optional]

To reset vector store, delete:

app/backend/qdrant_storage/

---

## 🎓 Next Steps After Startup

1. **Ingest Documents** (Admin Panel)
   - Navigate to http://localhost:3000/admin
   - Click "Ingest Document"
   - Upload PDF/DOCX/MD file
   - Select collection (general, finance, engineering, etc.)
   - Specify accessible roles

2. **Test RBAC**
   - Login as `emp_john` (employee)
   - Chat about available docs
   - Try asking about finance → "No access"
   - Login as `fin_alice` (finance)
   - Same question → See finance docs ✅

3. **Monitor System**
   - Check backend logs for errors
   - Watch RBAC decisions
   - Track embedding latency
   - Monitor token usage (Groq)

4. **Customize**
   - Edit roles in `config.py`
   - Adjust chunk size in `hierarchical_chunker.py`
   - Change embedding model in `vector_store.py`
   - Modify guardrails in `guardrails/`

---

## ✅ Verification Checklist

After startup, verify:

- [ ] Backend healthcheck: `curl http://localhost:8000/api/health`
- [ ] Frontend loads: `http://localhost:3000`
- [ ] Can login with demo user
- [ ] Chat endpoint responds
- [ ] RBAC filters work (test with different roles)
- [ ] Logs show no critical errors
- [ ] Both terminals show "Running"

---

## 📞 Support

**If Backend Won't Start:**
1. Check `.env` for GROQ_API_KEY
2. Try fresh `venv` (clean install)
3. Verify Python 3.8+
4. Check port 8000 not in use
5. View error logs carefully

**If Frontend Won't Start:**
1. Verify Node.js installed (`node --version`)
2. Try `npm install` again
3. Check port 3000 not in use
4. Clear `.next` cache: `rm -r .next`

**If Services Won't Communicate:**
1. Both running on correct ports?
2. Firewall blocking local traffic?
3. Check CORS headers in browser DevTools
4. Test endpoints with curl

---

**You're all set! 🚀 Happy chatting!**

Run the quick start commands above and your RBAC RAG chatbot will be live in minutes!