📚 Documentation — Lawyer Assistant
Everything you need to build, debug, or understand the app — organized so you find answers fast. Official repository: github.com/haal-lab/Lawyer-Assistant · issues & PRs welcome.
🔥 Start here
| I want to... | Read this |
|---|---|
| Use the app | QUICKSTART.md — from clone to first query |
| Fix something broken | TROUBLESHOOTING.md — 12 failure scenarios with exact fixes |
| Understand the architecture | ARCHITECTURE.md — system diagram, ports, runtime modes |
📖 Full index
| Document | What's inside | Who it's for |
|---|---|---|
| 🚀 QUICKSTART.md | Clone → install → run → first query → verify | New developers |
| 🩺 TROUBLESHOOTING.md | Backend down, Ollama missing, stale ports, empty results, GPU OOM, slow first query | Anyone debugging |
| 📋 CHANGELOG.md | Recent feature history — answers "what changed recently?" | Everyone tracking progress |
| 🏗️ ARCHITECTURE.md | System overview, Electron/Vite/FastAPI components, ports, runtime modes | High-level understanding |
| 🐍 BACKEND.md | FastAPI endpoints, AI routers, tools, retrieval pipeline, compliance scan, config | API & backend questions |
| ⚛️ FRONTEND.md | React layout, chat flow, Zustand stores, streaming events, theming, API layer | UI/UX & state management |
| 🎨 PIPELINE_EDITOR.md | Visual canvas: sub-nodes, toggles, bypass edges, persistence, export/import | Pipeline feature |
| 📐 PIPELINE_JSON.md | Exact JSON schema — write a valid layout from scratch | AI models & hand-editors |
| 🖥️ GPU_MANAGEMENT.md | Smart VRAM sharing, RAM-first residency, priority, batch auto-tuning, per-project profiles | GPU tuning & low-end hardware |
| 🤖 AGENT_KNOWLEDGE_BASE.md | Quick Q&A — the fastest path to a correct answer | AI agents answering questions |
| 📖 GLOSSARY.md | One-line definitions for every term (RAG, HNSW, BM25, SSE, HITL, …) | Terminology lookup |
| 🔍 CHATBOT_FLOW.md | Step-by-step: user types message → intent → tools → rerank → LLM → answer | Deep-dive: chat request end-to-end |
| 📊 DATA_FLOW.md | Document ingestion: parse → chunk → embed → ChromaDB + BM25 | Deep-dive: data pipeline |
| 🗺️ PIPELINE_ROADMAP.md | Planned improvements to the RAG pipeline | Roadmap |
| 🎨 API_PROVIDER.md | Cloud mode: providers, env vars, mixing providers, rerank modes, extended thinking | API mode setup |
| 🚀 LAUNCHER.md | Setup page internals: install steps, provider picker, Ollama automation | Launcher development |
🗺️ Quick topic map
How do I run it? → QUICKSTART.md
Something broken? → TROUBLESHOOTING.md
What changed recently? → CHANGELOG.md
What is this app? → ARCHITECTURE.md
What ports does it use? → ARCHITECTURE.md §2
How does a chat flow work? → BACKEND.md §3 / CHATBOT_FLOW.md
What API endpoints exist? → BACKEND.md §2
How does retrieval work? → BACKEND.md §5
How does compliance scan? → BACKEND.md §6
How does the GPU manager? → GPU_MANAGEMENT.md
How is the UI structured? → FRONTEND.md
Where is state stored? → FRONTEND.md §3
What is the pipeline editor? → PIPELINE_EDITOR.md
How do I write a layout JSON? → PIPELINE_JSON.md
How do I set up API mode? → API_PROVIDER.md
How does the launcher work? → LAUNCHER.md
What does a term mean? → GLOSSARY.md
Quick answers to questions? → AGENT_KNOWLEDGE_BASE.md🤖 For AI agents
- Start with AGENT_KNOWLEDGE_BASE.md for the fastest correct answer.
- Follow cross-references to ARCHITECTURE.md, BACKEND.md, FRONTEND.md for depth.
- Verify facts against source code:
backend/main.py,backend/legal_retrieval/*.py,frontend/src/**.
📁 Project layout
Lawyer-Assistant/
├── backend/ # Python — FastAPI + RAG engine + AI agents
│ ├── main.py # Server entry point (port 8765)
│ ├── legal_retrieval/ # Core engine (embedder, reranker, router, tools)
│ ├── scripts/ # CLI helpers (ingest_all.py, query.py)
│ ├── tests/ # Phase-based test suites
│ └── requirements.txt # Single dependency file
├── frontend/ # React + TypeScript + Tailwind
│ ├── src/ # App.tsx, components/, store/, services/
│ └── electron/ # Electron shell (main process, python bridge)
├── launcher/ # Setup page (no dependencies needed)
├── assets/ # README screenshots
├── docs/ # This knowledge base
├── data/ # ChromaDB, BM25, processed files
└── models/ # BGE-M3, BGE-Reranker (downloaded on first run)