The Problem Enterprise teams that need to answer questions over heterogeneous document collections (PDFs, slides, tables, images) often end up with a brittle pipeline: simple text‑only chunking, a single vector store, and no traceable citations. Maintaining provenance, handling rich media, and keeping the retrieval logic modular quickly becomes a maintenance burden.

What This Does NexusRAG delivers a single‑service RAG stack that preserves document structure, extracts visual elements, builds a lightweight knowledge graph (LightRAG), and reranks results with a cross‑encoder. The backend lives in backend/app/ (FastAPI) and exposes REST endpoints such as POST /api/chat (implemented in backend/app/api/chat_agent.py). The React front‑end (frontend/src/) provides an agentic chat UI with inline citations, powered by the /api/chat endpoint. Model selection is configurable (gemini, local ollama, or sentence‑transformers) via the environment variable NEXUSRAG_LLM_PROVIDER defined in .env.example.

How It Is Wired

frontend/src/components/rag/ChatPanel.tsx
   └─ uses useChatHistory → frontend/src/hooks/useChatHistory.ts
          └─ calls lib/api.ts → fetch('/api/chat', …)
                └─ FastAPI router in backend/app/api/chat_agent.py (router.registered in backend/app/api/router.py)
                       └─ validates request → backend/app/core/deps.py (dependency injection)
                       └─ builds prompt → backend/app/services/llm/gemini.py | ollama.py | sentence_transformer.py
                       └─ retrieves context →
                            ├─ backend/app/services/rag_service.py
                            │    ├─ vector_store → backend/app/services/vector_store.py
                            │    ├─ KG lookup → backend/app/services/knowledge_graph_service.py
                            │    └─ cross‑encoder rerank → backend/app/services/reranker.py
                            └─ post‑process citations → backend/app/services/nexus_rag_service.py
  • Entry points – backend/app/main.py starts the FastAPI server, frontend/main.tsx boots the Vite dev server, mcp-server/src/index.ts runs an auxiliary micro‑controller service.
  • Database – SQLite file defined in backend/app/core/database.py; migrations live under backend/alembic/.
  • Most‑connected front‑end modules – DataPanel (frontend/src/components/rag/DataPanel), VisualPanel, and SearchResults each import six, four, and three other modules respectively; they are UI “leaf” components with no downstream imports, making them low‑risk to modify.
  • Blast radius – The oversized API files (backend/app/api/chat_agent.py, backend/app/api/rag.py) and the monolithic ChatPanel.tsx own the majority of request handling and UI state; changes here ripple through many services and UI components.

How To Use It

# 1. Clone the repo
git clone https://github.com/moses-y/NexusRAG.git
cd NexusRAG

# 2. Build containers (backend, frontend, optional mcp‑server)
docker compose -f docker-compose.yml up --build -d

# 3. Install front‑end deps (pnpm is locked)
cd frontend
pnpm install

# 4. Create runtime env from example
cp .env.example .env          # edit as needed (e.g., NEXUSRAG_LLM_PROVIDER, DB_PATH)

# 5. Start development servers
#    Backend API
docker exec -it nexusrag_backend uvicorn backend.app.main:app --host 0.0.0.0 --port 8000
#    Front‑end UI
cd ../frontend
pnpm dev                      # Vite serves on http://localhost:5173

Configuration – All required keys are documented in .env.example. The backend reads them via backend/app/api/config.py. No secret keys are committed.

Real‑World Use A legal‑ops team could drop a batch of contracts (PDF, DOCX) into the upload zone (frontend/src/components/rag/UploadZone.tsx). The parser (backend/app/services/document_parser/docling_parser.py or marker_parser.py) extracts headings, tables, and images, stores vector embeddings in the SQLite‑backed vector store, and populates the LightRAG graph. An analyst then asks “What termination clauses exist in contracts signed after 2022?” The chat UI returns a cited answer with links to the exact pages, and the KG view (KnowledgeGraphView.tsx) highlights related entities, allowing quick navigation to source documents.

Code Health & Issues

Measured findings

  • HIGH – Duplicated code blocks (e.g., backend/app/api/chat_agent.py, backend/app/api/rag.py, backend/app/core/database.py).
  • HIGH – Deep nesting (max indentation depth 8 in chat_agent.py, document_parser/base.py).
  • HIGH – Oversized files (ChatPanel.tsx, chat_agent.py, rag.py > 1.6 k lines).
  • MEDIUM – Broad exception handling (bare except: in several API and parser modules).

Health audit

  • HIGH – No LICENSE (root).
  • HIGH – No test suite (102 source files, 0 tests).
  • HIGH – No CI workflow (no .github/ pipelines).
  • HIGH – No build gate for Docker images (docker-compose.yml unchecked).
  • HIGH – SQL string interpolation (backend/app/main.py).
  • MEDIUM – Dependabot disabled (no update bot).
  • MEDIUM – Base images not pinned (Dockerfile.backend).
  • MEDIUM – Large binaries in repo (showcase/demo_nexus_video.mp4).
  • MEDIUM – Containers run as root (Dockerfile.backend).
  • LOW – Missing repo conventions (.editorconfig, formatter config).

The Bottom Line NexusRAG provides a fully containerised, multi‑modal RAG pipeline with citation support and a knowledge‑graph layer, making it a solid foundation for teams that need traceable answers over rich documents. However, the codebase suffers from high technical debt (large, duplicated modules and deep nesting) and lacks essential production safeguards (tests, CI, licence). It is best suited for teams prepared to invest in refactoring and adding DevOps hygiene before a production rollout.