How the platform works

The site is a static documentation frontend. It is not an interactive chat UI for the backend.

Request flow

CLI or HTTP client
  → FastAPI authentication and validation
  → Optional SQLite / semantic conversation context
  → ChromaDB knowledge retrieval
  → Prompt construction
  → Model routing and availability check
  → Ollama generation
  → Response, source content, optional history writes

Component responsibilities

Component	Responsibility
FastAPI	Request contract, authentication, orchestration
Embedded ChromaDB	Knowledge and conversation vector collections
SQLite	Conversation records and messages
Ollama	Model inventory and generation
Model router	Task analysis, metadata extraction, scoring, availability
Astro/Starlight	Build and serve documentation pages
GitLab CI	Documentation checks/build and separately triggered backend deployment

Retrieval versus training

RAG retrieves text at request time; ingestion does not retrain model weights. QLoRA training in distill/ is a separate experiment. Source retrieval can support an answer, but the model can still add unsupported details.

Failure boundaries

Generation uses synchronous HTTP inside an async handler. Retrieval errors can degrade to missing context; embedding errors can return dummy vectors. Router availability is cached and execution-time retries are not wired through the standalone fallback manager. These behaviors explain why health, routing, and answer quality must be checked separately.

Trust boundaries

The API uses a shared key. Conversation IDs and user IDs are not isolation guarantees. Metadata selects a model; it does not grant execution authority. See security and engineering framework.

Next: Storage paths or routing guide.