How ayushd64/interior-design-rag-app works
1. Overall shape
- This repo is split into a Python backend and a Next.js frontend.
- The backend owns all AI orchestration, retrieval, auth verification, persistence, and evaluation.
- The frontend is a thin interactive client for chat, login/register, and the metrics dashboard.
2. Frontend boundary
- frontend/app uses the Next.js App Router with separate routes for chat/home, login, register, and dashboard.
- components/ holds the chat UI pieces: message list, input bar, sidebar, and protected route wrapper.
- app/context/AuthContext.tsx and ThemeContext.tsx provide session and theme state across the UI.
- app/lib/firebase.ts is the browser-side Firebase config used for authentication.
3. Backend API surface
- backend/main.py starts the FastAPI app.
- backend/api/ is the HTTP boundary, separated by feature:
- chat_routes.py for conversational requests
- agent_routes.py for the agent mode
- dashboard_routes.py for metrics/evaluation reads
- routes.py as the shared router assembly
- api/schemas.py defines the request/response contracts that connect frontend and backend.
4. Authentication and user isolation
- backend/auth/firebase_auth.py verifies Firebase tokens server-side.
- backend/auth/dependencies.py likely injects authenticated user context into protected routes.
- The architecture is explicitly multi-user: conversations and metrics are stored per user, and access is mediated by Firebase identity rather than session cookies.
5. Two AI execution paths
- The backend has two distinct orchestration modes:
- backend/src/graph.py implements the classic RAG pipeline
- backend/src/agent.py implements the agentic ReAct-style path
- This dual-mode design is a core architectural boundary: one path is deterministic and pipeline-based, the other is tool-driven and autonomous.
6. Classic RAG pipeline
- The graph-based path in src/graph.py, nodes.py, state.py, and prompts.py performs the core retrieval flow.
- From the README and file layout, the pipeline includes topic guarding, user-level classification, retrieval, document grading, generation, and hallucination checks.
- src/session_manager.py and src/state.py provide conversation continuity across turns.
- src/evaluator.py and src/eval_prompts.py are tied to quality scoring after responses are produced.
7. Agentic layer and tools
- backend/src/agent_tools.py defines the tools the agent can call.
- The README indicates at least two tools matter architecturally:
- semantic knowledge search over the design corpus
- image generation for interior renders
- src/agent.py routes user requests through an autonomous decision loop, so the agent can choose between search, image generation, or direct response.
8. Retrieval and embeddings subsystem
- backend/src/data_loader.py, embeddings.py, and vectorstore.py support ingestion and embedding generation.
- backend/src/vector_db/ contains the abstraction layer for vector storage with two implementations:
- chromadb_repo.py for local ChromaDB
- pinecone_repo.py for Pinecone
- vector_db/factory.py selects the implementation based on environment configuration, making retrieval storage swappable without changing the API or graph code.
9. Chat persistence and metrics storage
- backend/database/ is the persistent store abstraction for chat data and analytics.
- It also uses a factory pattern:
- mongodb_repo.py for local MongoDB
- firestore_repo.py for Firestore
- metrics_models.py, metrics_crud.py, and crud.py indicate a separate metrics path from normal chat history, which supports the dashboard and evaluation features.
10. End-to-end request flow
- A user sends a message from the Next.js UI with a Firebase-authenticated identity.
- FastAPI validates the token, loads user context, and dispatches to either the classic RAG graph or the agent.
- The AI path retrieves from the vector store and/or invokes tools, then writes conversation state and metrics to the chat database.
- The backend streams output back to the frontend, enabling the token-by-token chat experience described in the README.
11. Evaluation and dashboard
- The dashboard is not just a UI page; it is backed by runtime telemetry from the AI pipeline.
- The evaluation subsystem computes RAG-style metrics such as faithfulness, answer relevancy, and context precision.
- dashboard_routes.py likely exposes these metrics so the frontend dashboard can show quality trends, latency, retrieval counts, and user-level distributions.
12. Local-first infrastructure
- The architecture is designed to run on local or free infrastructure:
- Ollama for the LLM
- ChromaDB or Pinecone for retrieval
- MongoDB or Firestore for chat persistence
- Firebase for auth
- That means the system boundaries are intentionally abstracted so the same backend code can run in a local-only setup or be pointed at cloud services through environment variables.
13. Operational / offline assets
- backend/vectorstore/chromadb/ contains persisted local vector index files, so the repo includes a concrete local retrieval store, not just code.
- backend/test_agent.py and backend/test_tool_calling.py suggest focused backend checks around orchestration and tool use rather than a broad end-to-end test suite.
14. What to diagram
- The key boxes are: Frontend UI, FastAPI API, Auth verification, Classic RAG graph, Agent tool loop, Vector store, Chat/metrics DB, LLM/embeddings services, and Evaluation/dashboard.
- The most important arrows are:
- frontend to API with Firebase token
- API to auth verification
- API to retrieval store and chat DB
- API to Ollama and image-generation tool
- pipeline/agent to metrics storage
- dashboard reads back from metrics routes
Main entry points: api API Routes · graph.py RAG Graph · agent.py Agent Loop · auth Auth Verify
Components 16
Frontend
Next.js client for chat, auth, and dashboard views.
- App UI · App Router pages for chat, login, register, and dashboard.
frontend/app - Chat Comps · Message list, input bar, sidebar, and protected chat shell.
frontend/components - UI State · Auth and theme contexts shared across the client.
frontend/app/context - Firebase Client · Frontend Firebase setup for user sign-in and registration.
frontend/app/lib/firebase.ts - API Client · Browser-side service layer for calling backend endpoints.
frontend/app/services/api.ts
Backend
FastAPI API, AI orchestration, storage, and evaluation.
- FastAPI App · Backend application entrypoint and router assembly.
backend/main.py - API Routes · Chat, agent, and dashboard HTTP boundaries.
backend/api - Auth Verify · Server-side Firebase token validation and user context injection.
backend/auth - RAG Graph · Classic retrieval pipeline with grading, generation, and safeguards.
backend/src/graph.py - Agent Loop · Tool-driven orchestration path for autonomous responses.
backend/src/agent.py - Agent Tools · Search and image-generation tools available to the agent.
backend/src/agent_tools.py - Retrieval Stack · Data loading, embedding generation, and vector-store access.
backend/src - Vector DB · Swappable ChromaDB or Pinecone backend for semantic search.
backend/src/vector_db - Chat Store · MongoDB or Firestore-backed conversation and metrics storage.
backend/database - Eval & Dash · Response evaluation and dashboard metrics exposure.
backend/src/evaluator.py - Session State · Turn-level state and session continuity for multi-turn chat.
backend/src/state.py
Connections 22
- Chat Comps → App UI: renders · UI components compose the chat and sidebar experience.
- UI State → App UI: provides state · Auth and theme context are available across pages.
- Firebase Client → UI State: sign-in · Client auth state is sourced from Firebase.
- App UI → API Client: calls API · Pages invoke backend endpoints for chat and dashboard data.
- API Client → API Routes: HTTP requests · Frontend requests land on feature-specific backend routes.
- FastAPI App → API Routes: mounts · FastAPI assembles the feature routers.
- API Routes → Auth Verify: protects · Protected endpoints validate Firebase identity server-side.
- Auth Verify → RAG Graph: user context · Authenticated user identity scopes retrieval and persistence.
- Auth Verify → Agent Loop: user context · Agent requests are also tied to a verified user.
- API Routes → RAG Graph: chat mode · Conversational requests enter the classic RAG pipeline.
- API Routes → Agent Loop: agent mode · Agent routes dispatch to the autonomous loop.
- RAG Graph → Retrieval Stack: retrieves · Pipeline queries embeddings and vector search.
- Agent Loop → Agent Tools: uses tools · The agent decides when to search or generate images.
- Agent Tools → Retrieval Stack: search tool · Semantic knowledge search is powered by retrieval infrastructure.
- Retrieval Stack → Vector DB: stores/searches · Embeddings are persisted and queried in the vector backend.
- RAG Graph → Session State: maintains · Multi-turn context is carried through the graph.
- Agent Loop → Session State: maintains · Agent conversations also persist turn context.
- RAG Graph → Chat Store: persists · Messages and run metadata are written per user.
- Agent Loop → Chat Store: persists · Agent interactions and metrics are stored per user.
- RAG Graph → Eval & Dash: scores · Pipeline responses are evaluated for quality metrics.
- Eval & Dash → Chat Store: reads metrics · Dashboard views are backed by stored telemetry and results.
- API Routes → Eval & Dash: dashboard reads · Dashboard endpoint exposes evaluation and usage summaries.