ArchitectureAdrADR-0022: Documentation & RAG Stack

ADR-0022: Documentation & RAG Stack

ADR-0022: Documentation & RAG Stack

Canonical markdown page for this topic. Rendered reference version: adr-0022-documentation-rag-stack.

Status

Accepted

Context

Jorvis needs a self-hosted documentation and Q&A stack that integrates with the existing platform (Open WebUI + pgvector), supports Mermaid diagrams, and minimizes additional runtime infrastructure and dependencies. Options considered included all-in-one wiki systems (e.g., DeepWiki-Open) and generator-based approaches (e.g., CodeWiki + MkDocs) alongside Open WebUI RAG.

Key constraints:

  • Existing stack: Open WebUI, pgvector, NestJS/TypeScript + Python
  • Self-hosted (data sovereignty)
  • Minimal runtime overhead
  • Mermaid visualization support
  • Prefer no new heavy services that duplicate current RAG/UI

Decision

Adopt the following stack for documentation and RAG:

  • MkDocs (static docs presentation)
  • Open WebUI + pgvector (RAG + chat UI)
  • Gemini-3.0-flash as primary LLM
  • Ollama as fallback LLM

Notes:

  • DeepWiki-Open may be used only as a temporary PoC if needed, but is not the primary stack.
  • Dify is not adopted due to duplication of existing Open WebUI + pgvector capabilities.

Consequences

  • Documentation remains in docs/ and is rendered via MkDocs.
  • RAG continues to use the existing pgvector infrastructure.
  • LLM routing prioritizes Gemini-3.0-flash with Ollama fallback for local/offline scenarios.
  • No new always-on services are required beyond current Open WebUI and pgvector.

References

  • docs/handoff/HANDOFF_TO_NEXT_AGENT.md
  • docs/agent_ops/GO_NO_GO.md
  • docs/agent_ops/TASK_BOARD.md