Frontend (React)¶

The production UI is the Next.js/React frontend in frontend/, backed by the FastAPI service through Next.js server routes.

Architecture boundary¶

Browser requests go to the frontend domain and Next.js routes under /api/*.
Next.js server routes proxy requests to FastAPI using RAG_API_URL (frontend/src/app/api/_proxy.ts).
Proxy routes attach x-api-key when RAG_API_KEY is set.
Auth is enforced on both page render and proxy routes:
unauthenticated page requests redirect to /login
unauthenticated proxy requests return 401

Local development¶

Prerequisites¶

Node.js 20+
pnpm
FastAPI reachable from the frontend host (default: http://localhost:8000)

1) Install and configure¶

PowerShell
cd frontend
pnpm install
Copy-Item .env.example .env.local

Required in frontend/.env.local:

RAG_API_URL=http://localhost:8000
AUTH_SECRET=<random hex>
AUTH_USERS=<username:scrypt:salt_hex:hash_hex>

Generate a random AUTH_SECRET:

PowerShell
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Generate one AUTH_USERS entry:

PowerShell
node -e 'const c=require("crypto");const u="admin";const p="change-me";const s=c.randomBytes(16);const h=c.scryptSync(p,s,32,{N:16384,r:8,p:1});console.log(`${u}:scrypt:${s.toString("hex")}:${h.toString("hex")}`)'

Optional values are documented in:

frontend/.env.example
deploy/.env.DOKPLOY.example

2) Run locally¶

PowerShell
cd frontend
pnpm dev

Open http://localhost:3000, sign in, then run retrieval/synthesis/chat flows.

Build and quality checks¶

PowerShell
cd frontend
pnpm lint
pnpm build
pnpm start

Deployment notes¶

Frontend service runs on container port 3000 (deploy/docker-compose.yml).
Domain routing should target the frontend service.
In container networking, set RAG_API_URL=http://api:8000.
Do not call http://api:8000 directly from the browser; keep browser traffic on frontend routes (/api/*).
Keep AUTH_SECRET and AUTH_USERS server-side only.