Levy — AI Legal Assistant for Zambia

Ask questions about Zambian law and get answers grounded in actual legislation, with citations to specific Acts, sections, and pages.

• Live: https://levylegal.ai
• API: https://levy-api-production.up.railway.app

Architecture

┌─────────────────────────┐      ┌───────────────────────────┐      ┌─────────────────────────┐
│  Next.js 16 (App Router)│      │  FastAPI (Python 3.12)    │      │  Supabase Postgres      │
│  Vercel — levy-ten      │ ───▶ │  Railway — levy-api       │ ───▶ │  + pgvector (HNSW, 768) │
│  @supabase/ssr auth     │      │  RAG: embed → search → LLM│      │  3,882 chunks · 12 Acts │
└─────────────────────────┘      └───────────────────────────┘      └─────────────────────────┘
            │                              │                                    │
            │                              ▼                                    │
            │                  ┌───────────────────────┐                        │
            │                  │  Anthropic Claude     │                        │
            │                  │  claude-sonnet-4      │                        │
            │                  └───────────────────────┘                        │
            ▼                                                                   ▼
┌─────────────────────────┐                                       ┌─────────────────────────┐
│  Supabase Auth          │                                       │  BGE-base-en-v1.5       │
│  + Resend email         │                                       │  (sentence-transformers,│
│  sender: [email protected]                             │   embedded in API image)│
└─────────────────────────┘                                       └─────────────────────────┘

Repo layout

backend/      FastAPI service — RAG pipeline, deployed to Railway
frontend/     Next.js 16 app — deployed to Vercel
supabase/     SQL migrations (pgvector schema, 768-dim chunks, search RPC)
scripts/      One-off ingestion / DB-setup / CLI ask scripts
docs/         ARCHITECTURE.md — RAG strategy & evolution timeline

API endpoints

Method	Path	Purpose
GET	/health	Liveness check
POST	/api/chat	Full RAG: embed → retrieve → generate with citations
POST	/api/chat/stream	Same, server-sent events
POST	/api/search	Retrieval only (no LLM) — for evaluating retrieval quality
GET	/api/documents	List ingested Acts and chunk counts
POST	/api/documents/upload	Ingest a new PDF (parse → chunk → embed → store)
POST	/api/brief/generate	IRAC brief from a conversation

Local development

Backend

cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # fill in SUPABASE_URL, SUPABASE_KEY, ANTHROPIC_API_KEY
uvicorn app.main:app --reload

Required env (backend/.env):

SUPABASE_URL=https://zpdhoijcmotycbyelkbk.supabase.co
SUPABASE_KEY=<anon key>
ANTHROPIC_API_KEY=sk-ant-...
EMBEDDING_PROVIDER=local       # uses BAAI/bge-base-en-v1.5 (768-dim)
EMBEDDING_DIMENSIONS=768
RETRIEVAL_TOP_K=5
SIMILARITY_THRESHOLD=0.6

Frontend

cd frontend
npm install
cp .env.example .env.local     # see below
npm run dev                    # http://localhost:3000

Required env (frontend/.env.local):

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_SUPABASE_URL=https://zpdhoijcmotycbyelkbk.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=<anon key>

Deploy

Component	Tool	Command
Backend	push to main	auto-deploys when backend/** changes
Frontend	push to main	auto-deploys
DB schema	Supabase Mgmt API	Apply files in supabase/migrations/

Both deploy on push to main. Vercel and Railway are each connected to Mukela12/levy. Railway only rebuilds when something under backend/** changes, so a frontend-only commit does not trigger a five-minute image build.

Each has a root directory set, because a git build clones the repo root: Vercel's is frontend, Railway's is backend.

Manual deploys now run from the repo root, both of them. The root directory is applied on top of whatever you upload, so deploying from inside frontend/ or backend/ makes the builder look for frontend/frontend or backend/backend and fail:

Build Failed: lstat .../snapshot-target-unpack/backend: no such file or directory

cd ~/levy && vercel --prod        # frontend
cd ~/levy && railway up --detach  # backend

.railwayignore keeps that upload small, since the repo root also holds the frontend's node_modules and a local venv.

railway link is stored per directory and has drifted three times now, putting a "successful" command into an unrelated project. The repo root was linked to welcoming-light the first time railway up was tried from there. Always confirm railway status prints levy-api before running anything that writes.

Never commit backend/.env, and keep it in backend/.dockerignore. app/config.py calls load_dotenv(override=True), so a .env inside the image outranks the real environment. When railway up was baking one in, production silently ran the developer's local settings and every variable configured on Railway was dead config that looked live.

The Railway image bakes the BGE-base model (~440MB) into the image at build time so the first request doesn't pay model-load latency. Build uses CPU-only torch (+cpu index) — full CUDA torch is ~5GB and unnecessary on Railway's CPU runners.

Auth flow

Signup uses Supabase Auth (@supabase/ssr browser client). Levy-branded app emails now go through Resend (RESEND_API_KEY) using the frontend/src/app/api/email/* routes and reusable templates in frontend/src/lib/email/templates.ts. The welcome route verifies the caller's Supabase bearer token before sending to the signed-in user, and the tester-update route is protected by LEVY_EMAIL_ADMIN_TOKEN for manual preview/broadcast sends.

At the moment email confirmation is disabled on the project, so signup returns an active session immediately and the UI fires a best-effort Levy welcome email after account creation. If confirmation mode is re-enabled later, Supabase's auth mailer can still stay on Resend/SMTP separately while the app keeps using the same branded notification layer.

A public.profiles row is auto-created on signup via the handle_new_user trigger on auth.users.

Embedding model

Chunks were ingested with BAAI/bge-base-en-v1.5 (768-dim). The DB column is vector(768) with an HNSW cosine index. Switching providers requires re-ingesting the corpus — vectors from different models aren't comparable. The original Voyage voyage-law-2 (1024-dim) path is still in backend/app/services/embedder.py but disabled by default.

What's ingested

12 Acts, 3,882 chunks, 4,300+ sections — Constitution, Penal Code, Companies Act, Employment Code, Mines & Minerals Development Act, Environmental Management Act, Public Procurement Act, Lands Act, Lands & Deeds Registry Act, Government of Zambia Act, and others.

Documentation

• docs/ARCHITECTURE.md — RAG strategy, chunking decisions, evaluation approach, and the broader RAG evolution timeline.