Backend Handbook Overview
This handbook is for backend developers, architects, and integration engineers, helping you quickly understand MimirQ backend's module boundaries, API contracts, and internal flows. Use OpenAPI / Redoc as the authoritative Schema reference; this handbook focuses on navigation indexes, state-machine descriptions, and troubleshooting guides.
Tech Stack
| Layer | Technology | Version / Notes |
|---|---|---|
| Web Framework | FastAPI | 0.135 |
| ORM | SQLAlchemy | 2.0 (async) |
| Vector Database | Milvus | 2.x (BM25 + SPLADE + ColBERT ANN hybrid retrieval) |
| Relational Database | PostgreSQL | Primary storage |
| Cache / Queue | Redis | Session, rate limiting & Pub/Sub |
| Task Queue | Arq | Async parsing, indexing, evaluation tasks |
| Object Storage | MinIO / S3-compatible | Raw document files |
System Architecture
Module Map
| Domain | Overview | API Index | State Machine / Troubleshooting |
|---|---|---|---|
| Datasets | Overview | API Index | State & Jobs / Troubleshooting |
| Documents | Overview | API Index | State & Jobs / Troubleshooting |
| Chat | Chat Module | — | — |
| Retrieval | Retrieval Module | — | — |
| Knowledge Graph (KG) | KG Module | — | — |
| Evaluations | Evaluations Module | — | — |
| Governance | Governance Module | — | — |
| Parsing | Parsing Module | — | — |
| Evidence | Evidence Module | — | — |
| Platform | Platform Module | — | — |
Suggested Reading Order
- This page -- Establish the big picture
- Datasets -- Overview → API Index → Schema → State & Jobs
- Documents -- Overview → Pipeline → State & Jobs
- Retrieval & RAG -- Retrieval → KG → Chat
- Governance & Evaluations -- Governance → Evaluations
- Integration Troubleshooting -- Each domain's
troubleshootingpage + Integration Overview
Embedding & Model Support
The backend ships with 15 embedding models across 7 providers. The repository's .env.example defaults to BAAI/bge-m3; if EMBEDDING_MODEL is not set, the backend code still falls back to text-embedding-3-small. Production and team environments should follow .env.example / deployment config rather than the process fallback. The RAG Engine supports hybrid orchestration of four retrieval modes -- Vector, BM25, SPLADE, and ColBERT ANN -- and can be flexibly switched via configuration.
Key Configuration & File Paths
| File | Purpose |
|---|---|
app/core/config.py | 1200+ config entries, driven by pydantic-settings |
alembic.ini / alembic/ | Database migrations |
docker-compose.yml | Local dev environment orchestration |
app/rag/engine.py | RAGEngine main flow (streaming) |
app/rag/retriever.py | HybridRetriever hybrid retrieval |
app/rag/pipelines/langgraph.py | LangGraph Functional API pipeline |
app/rag/kg/ | Knowledge graph extraction / recall / expansion / reranking |
Environment variables > .env file > config.py defaults. For production deployments, inject sensitive configuration via environment variables.