# mabdullah005/nexusai-agentic-rag-assistant architecture

> Architecture diagram of the GitHub repository mabdullah005/nexusai-agentic-rag-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mabdullah005/nexusai-agentic-rag-assistant
- Repository: https://github.com/mabdullah005/nexusai-agentic-rag-assistant

## Overview

NexusAI is a full-stack conversational RAG assistant: users authenticate, manage threads and attached sources, then chat or resume a turn awaiting approval. The backend agent can retrieve grounded context, invoke tools, and pause for web-search approval; source ingestion covers PDFs, web pages, YouTube transcripts, and GitHub repositories. The README documents these product flows, while sampled source confirms selected implementation links. Some unsampled endpoint and graph details are represented only where explicitly documented.

Main entry points: [`frontend/src/components/sources/SourceWorkspace.tsx`](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/frontend/src/components/sources/SourceWorkspace.tsx) (Source workspace), [`app/graph/agent_graph.py`](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/graph/agent_graph.py) (LangGraph agent), [`frontend/src/lib/api/client.ts`](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/frontend/src/lib/api/client.ts) (API client), [`frontend/src/app/page.tsx`](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/frontend/src/app/page.tsx) (Chat workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_workspace["Chat workspace<br/>[page.tsx]"]
  node_chatui["Chat interface<br/>[ChatContainer.tsx]"]
  node_sourceui["Source workspace"]
  node_ingestui["Source upload UI"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_backend["API and identity"]
  node_fastapi["FastAPI endpoints<br/>[routes.py]"]
  node_auth["Authentication<br/>[routes.py]"]
end

subgraph group_agent["Agent and tools"]
  node_agent_graph["LangGraph agent<br/>[agent_graph.py]"]
  node_rag_tool["RAG tool"]
  node_toolset["Assistant tools"]
end

subgraph group_sources["Source knowledge"]
  node_pdf_ingest["PDF ingestion<br/>[pdf_ingest.py]"]
  node_web_ingest["Web ingestion<br/>[web_loader.py]"]
  node_youtube_ingest["YouTube ingestion<br/>[youtube_ingest.py]"]
  node_repo_api["Repo indexing API<br/>[main.py]"]
  node_repo_pipeline["Repo RAG pipeline<br/>[rag.py]"]
  node_retriever["Hybrid retriever<br/>[retriever.py]"]
  node_embeddings["Embedding provider<br/>[embeddings.py]"]
end

subgraph group_persistence["Memory and storage"]
  node_vector_index[("Vector indexes<br/>[vector_storage.py]")]
  node_conversation_memory[("Conversation memory<br/>[postgres_memory.py]")]
  node_historical_memory["Historical retrieval"]
  node_db_session["Database sessions<br/>[session.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_workspace
node_workspace -->|"renders"| node_chatui
node_workspace -->|"renders"| node_sourceui
node_chatui -.->|"sends chat"| node_api_client
node_sourceui -->|"submits sources"| node_api_client
node_api_client -->|"HTTP requests"| node_fastapi
node_api_client -->|"auth requests"| node_auth
node_fastapi -->|"invokes"| node_agent_graph
node_agent_graph -->|"routes retrieval"| node_rag_tool
node_agent_graph -->|"invokes tools"| node_toolset
node_agent_graph -->|"checkpoints and persists"| node_conversation_memory
node_agent_graph -->|"retrieves history"| node_historical_memory
node_rag_tool -->|"calls"| node_retriever
node_retriever -->|"queries"| node_vector_index
node_retriever -->|"retrieves past turns"| node_historical_memory
node_pdf_ingest -->|"embeds chunks"| node_embeddings
node_pdf_ingest -->|"stores FAISS index"| node_vector_index
node_youtube_ingest -->|"embeds chunks"| node_embeddings
node_sourceui -.->|"uploads PDF"| node_pdf_ingest
node_sourceui -.->|"submits URL"| node_web_ingest
node_sourceui -.->|"submits video"| node_youtube_ingest
node_repo_api -->|"indexes repository"| node_repo_pipeline
node_repo_pipeline -->|"stores chunks"| node_vector_index
node_repo_pipeline -.->|"creates embeddings"| node_embeddings
node_conversation_memory -->|"uses sessions"| node_db_session
node_historical_memory -->|"reads messages"| node_conversation_memory

click node_workspace "https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/frontend/src/app/page.tsx"
click node_chatui "https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/frontend/src/components/chat/ChatContainer.tsx"
click node_sourceui "https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/frontend/src/components/sources/SourceWorkspace.tsx"
click node_ingestui "https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/frontend/src/components/sidebar/SourceIngestModal.tsx"
click node_api_client "https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/frontend/src/lib/api/client.ts"
click node_fastapi "https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/api/routes.py"
click node_auth "https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/auth/routes.py"
click node_agent_graph "https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/graph/agent_graph.py"
click node_rag_tool "https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/tools/unified_rag_tool.py"
click node_toolset "https://github.com/mabdullah005/nexusai-agentic-rag-assistant/tree/main/app/tools"
click node_pdf_ingest "https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/services/pdf_ingest.py"
click node_web_ingest "https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/services/web_loader.py"
click node_youtube_ingest "https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/services/youtube_ingest.py"
click node_repo_api "https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/repocore/main.py"
click node_repo_pipeline "https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/repocore/rag.py"
click node_retriever "https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/core/retriever.py"
click node_embeddings "https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/llm/embeddings.py"
click node_vector_index "https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/repocore/vector_storage.py"
click node_conversation_memory "https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/memory/postgres_memory.py"
click node_historical_memory "https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/memory/historical_retriever.py"
click node_db_session "https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/db/session.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_workspace,node_chatui,node_sourceui,node_ingestui,node_api_client,node_user toneBlue
class node_fastapi,node_auth toneAmber
class node_agent_graph,node_rag_tool,node_toolset toneMint
class node_pdf_ingest,node_web_ingest,node_youtube_ingest,node_repo_api,node_repo_pipeline,node_retriever,node_embeddings toneRose
class node_vector_index,node_conversation_memory,node_historical_memory,node_db_session toneIndigo
```

## Components

### User experience

- [Chat workspace](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Chat interface](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/frontend/src/components/chat/ChatContainer.tsx): `frontend/src/components/chat/ChatContainer.tsx`
- [Source workspace](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/frontend/src/components/sources/SourceWorkspace.tsx): `frontend/src/components/sources/SourceWorkspace.tsx`
- [Source upload UI](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/frontend/src/components/sidebar/SourceIngestModal.tsx): `frontend/src/components/sidebar/SourceIngestModal.tsx`
- [API client](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/frontend/src/lib/api/client.ts): `frontend/src/lib/api/client.ts`

### API and identity

- [FastAPI endpoints](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/api/routes.py): `app/api/routes.py`
- [Authentication](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/auth/routes.py): `app/auth/routes.py`

### Agent and tools

- [LangGraph agent](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/graph/agent_graph.py): `app/graph/agent_graph.py`
- [RAG tool](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/tools/unified_rag_tool.py): `app/tools/unified_rag_tool.py`
- [Assistant tools](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/tree/main/app/tools): `app/tools`

### Source knowledge

- [PDF ingestion](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/services/pdf_ingest.py): `app/services/pdf_ingest.py`
- [Web ingestion](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/services/web_loader.py): `app/services/web_loader.py`
- [YouTube ingestion](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/services/youtube_ingest.py): `app/services/youtube_ingest.py`
- [Repo indexing API](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/repocore/main.py): `app/repocore/main.py`
- [Repo RAG pipeline](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/repocore/rag.py): `app/repocore/rag.py`
- [Hybrid retriever](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/core/retriever.py): `app/core/retriever.py`
- [Embedding provider](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/llm/embeddings.py): `app/llm/embeddings.py`

### Memory and storage

- [Vector indexes](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/repocore/vector_storage.py): `app/repocore/vector_storage.py`
- [Conversation memory](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/memory/postgres_memory.py): `app/memory/postgres_memory.py`
- [Historical retrieval](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/memory/historical_retriever.py): `app/memory/historical_retriever.py`
- [Database sessions](https://github.com/mabdullah005/nexusai-agentic-rag-assistant/blob/main/app/db/session.py): `app/db/session.py`

### Other components

- **User**

## Connections

- User → Chat workspace: uses (evidence: `README.md`)
- Chat workspace → Chat interface: renders (evidence: `frontend/src/app/page.tsx`)
- Chat workspace → Source workspace: renders (evidence: `frontend/src/app/page.tsx`)
- Chat interface → API client: sends chat
- Source workspace → API client: submits sources
- API client → FastAPI endpoints: HTTP requests (evidence: `README.md`)
- API client → Authentication: auth requests (evidence: `README.md`)
- FastAPI endpoints → LangGraph agent: invokes (evidence: `app/api/routes.py`)
- LangGraph agent → RAG tool: routes retrieval (evidence: `README.md`)
- LangGraph agent → Assistant tools: invokes tools (evidence: `README.md`)
- LangGraph agent → Conversation memory: checkpoints and persists (evidence: `app/graph/agent_graph.py`)
- LangGraph agent → Historical retrieval: retrieves history (evidence: `README.md`)
- RAG tool → Hybrid retriever: calls (evidence: `app/tools/unified_rag_tool.py`)
- Hybrid retriever → Vector indexes: queries (evidence: `app/core/retriever.py`)
- Hybrid retriever → Historical retrieval: retrieves past turns (evidence: `app/core/retriever.py`)
- PDF ingestion → Embedding provider: embeds chunks (evidence: `app/services/pdf_ingest.py`)
- PDF ingestion → Vector indexes: stores FAISS index (evidence: `app/services/pdf_ingest.py`)
- YouTube ingestion → Embedding provider: embeds chunks (evidence: `app/services/youtube_ingest.py`)
- Source workspace → PDF ingestion: uploads PDF
- Source workspace → Web ingestion: submits URL
- Source workspace → YouTube ingestion: submits video
- Repo indexing API → Repo RAG pipeline: indexes repository (evidence: `app/repocore/main.py`)
- Repo RAG pipeline → Vector indexes: stores chunks (evidence: `app/repocore/rag.py`)
- Repo RAG pipeline → Embedding provider: creates embeddings
- Conversation memory → Database sessions: uses sessions (evidence: `app/memory/postgres_memory.py`)
- Historical retrieval → Conversation memory: reads messages (evidence: `app/memory/historical_retriever.py`)