# ayushd64/interior-design-rag-app architecture

> Architecture diagram of the GitHub repository ayushd64/interior-design-rag-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ayushd64/interior-design-rag-app
- Repository: https://github.com/ayushd64/interior-design-rag-app

## Overview

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: [`backend/api`](https://github.com/ayushd64/interior-design-rag-app/tree/main/backend/api) (API Routes), [`backend/src/graph.py`](https://github.com/ayushd64/interior-design-rag-app/blob/main/backend/src/graph.py) (RAG Graph), [`backend/src/agent.py`](https://github.com/ayushd64/interior-design-rag-app/blob/main/backend/src/agent.py) (Agent Loop), [`backend/auth`](https://github.com/ayushd64/interior-design-rag-app/tree/main/backend/auth) (Auth Verify)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_ui["App UI<br/>Next.js app"]
  node_chat_components["Chat Comps<br/>React components"]
  node_ui_state["UI State<br/>React context"]
  node_firebase_client["Firebase Client<br/>browser auth config<br/>[firebase.ts]"]
  node_api_client["API Client<br/>HTTP client<br/>[api.ts]"]
end

subgraph group_backend["Backend"]
  node_api_entry["FastAPI App<br/>HTTP server<br/>[main.py]"]
  node_api_routes["API Routes<br/>route layer"]
  node_auth_verify["Auth Verify<br/>Firebase auth"]
  node_chat_graph{{"RAG Graph<br/>pipeline<br/>[graph.py]"}}
  node_agent_loop{{"Agent Loop<br/>ReAct agent<br/>[agent.py]"}}
  node_agent_tools["Agent Tools<br/>tooling<br/>[agent_tools.py]"]
  node_retrieval_stack["Retrieval Stack<br/>ingestion + embeddings"]
  node_vector_db[("Vector DB<br/>vector storage")]
  node_chat_store[("Chat Store<br/>persistent data")]
  node_eval_dash["Eval & Dash<br/>metrics pipeline<br/>[evaluator.py]"]
  node_session_state["Session State<br/>conversation state<br/>[state.py]"]
end

node_chat_components -->|"renders"| node_frontend_ui
node_ui_state -->|"provides state"| node_frontend_ui
node_firebase_client -->|"sign-in"| node_ui_state
node_frontend_ui -->|"calls API"| node_api_client
node_api_client -->|"HTTP requests"| node_api_routes
node_api_entry -->|"mounts"| node_api_routes
node_api_routes -->|"protects"| node_auth_verify
node_auth_verify -->|"user context"| node_chat_graph
node_auth_verify -->|"user context"| node_agent_loop
node_api_routes -->|"chat mode"| node_chat_graph
node_api_routes -->|"agent mode"| node_agent_loop
node_chat_graph -->|"retrieves"| node_retrieval_stack
node_agent_loop -->|"uses tools"| node_agent_tools
node_agent_tools -->|"search tool"| node_retrieval_stack
node_retrieval_stack -->|"stores/searches"| node_vector_db
node_chat_graph -->|"maintains"| node_session_state
node_agent_loop -->|"maintains"| node_session_state
node_chat_graph -->|"persists"| node_chat_store
node_agent_loop -->|"persists"| node_chat_store
node_chat_graph -->|"scores"| node_eval_dash
node_eval_dash -->|"reads metrics"| node_chat_store
node_api_routes -->|"dashboard reads"| node_eval_dash

click node_frontend_ui "https://github.com/ayushd64/interior-design-rag-app/tree/main/frontend/app"
click node_chat_components "https://github.com/ayushd64/interior-design-rag-app/tree/main/frontend/components"
click node_ui_state "https://github.com/ayushd64/interior-design-rag-app/tree/main/frontend/app/context"
click node_firebase_client "https://github.com/ayushd64/interior-design-rag-app/blob/main/frontend/app/lib/firebase.ts"
click node_api_client "https://github.com/ayushd64/interior-design-rag-app/blob/main/frontend/app/services/api.ts"
click node_api_entry "https://github.com/ayushd64/interior-design-rag-app/blob/main/backend/main.py"
click node_api_routes "https://github.com/ayushd64/interior-design-rag-app/tree/main/backend/api"
click node_auth_verify "https://github.com/ayushd64/interior-design-rag-app/tree/main/backend/auth"
click node_chat_graph "https://github.com/ayushd64/interior-design-rag-app/blob/main/backend/src/graph.py"
click node_agent_loop "https://github.com/ayushd64/interior-design-rag-app/blob/main/backend/src/agent.py"
click node_agent_tools "https://github.com/ayushd64/interior-design-rag-app/blob/main/backend/src/agent_tools.py"
click node_retrieval_stack "https://github.com/ayushd64/interior-design-rag-app/tree/main/backend/src"
click node_vector_db "https://github.com/ayushd64/interior-design-rag-app/tree/main/backend/src/vector_db"
click node_chat_store "https://github.com/ayushd64/interior-design-rag-app/tree/main/backend/database"
click node_eval_dash "https://github.com/ayushd64/interior-design-rag-app/blob/main/backend/src/evaluator.py"
click node_session_state "https://github.com/ayushd64/interior-design-rag-app/blob/main/backend/src/state.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_ui,node_chat_components,node_ui_state,node_firebase_client,node_api_client toneBlue
class node_api_entry,node_api_routes,node_auth_verify,node_chat_graph,node_agent_loop,node_agent_tools,node_retrieval_stack,node_vector_db,node_chat_store,node_eval_dash,node_session_state toneAmber
```

## Components

### Frontend

Next.js client for chat, auth, and dashboard views.

- [App UI](https://github.com/ayushd64/interior-design-rag-app/tree/main/frontend/app): Next.js app · App Router pages for chat, login, register, and dashboard. · `frontend/app`
- [Chat Comps](https://github.com/ayushd64/interior-design-rag-app/tree/main/frontend/components): React components · Message list, input bar, sidebar, and protected chat shell. · `frontend/components`
- [UI State](https://github.com/ayushd64/interior-design-rag-app/tree/main/frontend/app/context): React context · Auth and theme contexts shared across the client. · `frontend/app/context`
- [Firebase Client](https://github.com/ayushd64/interior-design-rag-app/blob/main/frontend/app/lib/firebase.ts): browser auth config · Frontend Firebase setup for user sign-in and registration. · `frontend/app/lib/firebase.ts`
- [API Client](https://github.com/ayushd64/interior-design-rag-app/blob/main/frontend/app/services/api.ts): HTTP client · Browser-side service layer for calling backend endpoints. · `frontend/app/services/api.ts`

### Backend

FastAPI API, AI orchestration, storage, and evaluation.

- [FastAPI App](https://github.com/ayushd64/interior-design-rag-app/blob/main/backend/main.py): HTTP server · Backend application entrypoint and router assembly. · `backend/main.py`
- [API Routes](https://github.com/ayushd64/interior-design-rag-app/tree/main/backend/api): route layer · Chat, agent, and dashboard HTTP boundaries. · `backend/api`
- [Auth Verify](https://github.com/ayushd64/interior-design-rag-app/tree/main/backend/auth): Firebase auth · Server-side Firebase token validation and user context injection. · `backend/auth`
- [RAG Graph](https://github.com/ayushd64/interior-design-rag-app/blob/main/backend/src/graph.py): pipeline · Classic retrieval pipeline with grading, generation, and safeguards. · `backend/src/graph.py`
- [Agent Loop](https://github.com/ayushd64/interior-design-rag-app/blob/main/backend/src/agent.py): ReAct agent · Tool-driven orchestration path for autonomous responses. · `backend/src/agent.py`
- [Agent Tools](https://github.com/ayushd64/interior-design-rag-app/blob/main/backend/src/agent_tools.py): tooling · Search and image-generation tools available to the agent. · `backend/src/agent_tools.py`
- [Retrieval Stack](https://github.com/ayushd64/interior-design-rag-app/tree/main/backend/src): ingestion + embeddings · Data loading, embedding generation, and vector-store access. · `backend/src`
- [Vector DB](https://github.com/ayushd64/interior-design-rag-app/tree/main/backend/src/vector_db): vector storage · Swappable ChromaDB or Pinecone backend for semantic search. · `backend/src/vector_db`
- [Chat Store](https://github.com/ayushd64/interior-design-rag-app/tree/main/backend/database): persistent data · MongoDB or Firestore-backed conversation and metrics storage. · `backend/database`
- [Eval & Dash](https://github.com/ayushd64/interior-design-rag-app/blob/main/backend/src/evaluator.py): metrics pipeline · Response evaluation and dashboard metrics exposure. · `backend/src/evaluator.py`
- [Session State](https://github.com/ayushd64/interior-design-rag-app/blob/main/backend/src/state.py): conversation state · Turn-level state and session continuity for multi-turn chat. · `backend/src/state.py`

## Connections

- 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.