# srivarun-04/neural-core architecture

> Architecture diagram of the GitHub repository srivarun-04/neural-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/srivarun-04/neural-core
- Repository: https://github.com/srivarun-04/neural-core

## Overview

NuraVault is a React and FastAPI knowledge-and-chat workspace. Users chat with a tool-calling agent that can answer directly, calculate, or retrieve document context; responses can include citations and stream to the chat UI. Separate workflows manage uploaded documents and multi-session history, while the knowledge dashboard and sidebar expose those capabilities. The README documents broader UI features; relationships below are limited to README statements and the shown source excerpts or SOURCE INDEX references, so some unsampled internals are represented at subsystem level.

Main entry points: [`backend/services/document_manager.py`](https://github.com/srivarun-04/neural-core/blob/main/backend/services/document_manager.py) (Document lifecycle), [`frontend/src/App.tsx`](https://github.com/srivarun-04/neural-core/blob/main/frontend/src/App.tsx) (Workspace shell), [`main.py`](https://github.com/srivarun-04/neural-core/blob/main/main.py) (FastAPI application), [`frontend/src/services/api.ts`](https://github.com/srivarun-04/neural-core/blob/main/frontend/src/services/api.ts) (HTTP and SSE client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Workspace UI"]
  node_app["Workspace shell<br/>[App.tsx]"]
  node_chat_ui["Chat workspace<br/>[ChatArea.tsx]"]
  node_session_ui["Session manager<br/>[Sidebar.tsx]"]
  node_knowledge_ui["Knowledge dashboard<br/>[KnowledgeBase.tsx]"]
  node_chat_hook["Chat state<br/>[useChat.ts]"]
  node_api_client["HTTP and SSE client<br/>[api.ts]"]
  node_local_storage[("Local preferences<br/>[storage.ts]")]
end

subgraph group_api["API Layer"]
  node_fastapi["FastAPI application<br/>[main.py]"]
  node_chat_api["Chat endpoints<br/>[chat.py]"]
  node_session_api["Session endpoints<br/>[chats.py]"]
  node_document_api["Document endpoints<br/>[documents.py]"]
  node_upload_api["Upload endpoint<br/>[upload.py]"]
  node_health_api["Health endpoint<br/>[health.py]"]
end

subgraph group_agent["Agent and Retrieval"]
  node_agent_core["Neural agent<br/>[neural_agent.py]"]
  node_calculator["Safe calculator<br/>[calculator_tool.py]"]
  node_rag_tool["Knowledge search tool<br/>[rag_tool.py]"]
end

subgraph group_knowledge["Knowledge Ingestion"]
  node_document_manager["Document lifecycle"]
  node_loaders["File loaders<br/>[loaders.py]"]
  node_splitter["Chunk preparation<br/>[splitter.py]"]
  node_embeddings["Text embeddings<br/>[embeddings.py]"]
  node_vector_store[("FAISS index<br/>[vector_store.py]")]
end

subgraph group_memory["Conversation Memory"]
  node_conversation_service["Session persistence"]
  node_memory_service["Sliding history<br/>[memory_service.py]"]
  node_sqlite[("SQLite history<br/>[sqlite_db.py]")]
end

node_user(("Workspace user"))
node_llm{{"OpenRouter model"}}

node_user -->|"uses"| node_app
node_app -->|"shows"| node_chat_ui
node_app -->|"shows"| node_session_ui
node_app -->|"shows"| node_knowledge_ui
node_app -->|"uses"| node_chat_hook
node_chat_hook -->|"calls"| node_api_client
node_app -->|"persists settings"| node_local_storage
node_api_client -->|"HTTP / SSE"| node_chat_api
node_api_client -.->|"manages sessions"| node_session_api
node_api_client -.->|"reads documents"| node_document_api
node_api_client -.->|"uploads files"| node_upload_api
node_app -->|"polls health"| node_health_api
node_fastapi -->|"mounts router"| node_chat_api
node_fastapi -->|"mounts router"| node_session_api
node_fastapi -->|"mounts router"| node_document_api
node_fastapi -->|"mounts router"| node_upload_api
node_fastapi -->|"mounts router"| node_health_api
node_chat_api -->|"invokes"| node_agent_core
node_chat_api -->|"loads history"| node_memory_service
node_chat_api -->|"stores turns"| node_conversation_service
node_session_api -->|"manages sessions"| node_conversation_service
node_document_api -->|"manages documents"| node_document_manager
node_upload_api -->|"indexes uploads"| node_document_manager
node_health_api -->|"reports status"| node_document_manager
node_health_api -->|"reports status"| node_agent_core
node_agent_core -->|"requests completions"| node_llm
node_agent_core -->|"dispatches calculations"| node_calculator
node_agent_core -->|"dispatches searches"| node_rag_tool
node_rag_tool -->|"retrieves context"| node_document_manager
node_document_manager -->|"loads files"| node_loaders
node_document_manager -->|"chunks content"| node_splitter
node_document_manager -->|"creates vectors"| node_embeddings
node_document_manager -->|"updates index"| node_vector_store
node_rag_tool -->|"searches index"| node_vector_store
node_memory_service -->|"reads recent turns"| node_conversation_service
node_conversation_service -->|"queries and writes"| node_sqlite
node_fastapi -->|"syncs at startup"| node_document_manager

click node_app "https://github.com/srivarun-04/neural-core/blob/main/frontend/src/App.tsx"
click node_chat_ui "https://github.com/srivarun-04/neural-core/blob/main/frontend/src/components/Chat/ChatArea.tsx"
click node_session_ui "https://github.com/srivarun-04/neural-core/blob/main/frontend/src/components/Sidebar/Sidebar.tsx"
click node_knowledge_ui "https://github.com/srivarun-04/neural-core/blob/main/frontend/src/components/KnowledgeBase/KnowledgeBase.tsx"
click node_chat_hook "https://github.com/srivarun-04/neural-core/blob/main/frontend/src/hooks/useChat.ts"
click node_api_client "https://github.com/srivarun-04/neural-core/blob/main/frontend/src/services/api.ts"
click node_local_storage "https://github.com/srivarun-04/neural-core/blob/main/frontend/src/utils/storage.ts"
click node_fastapi "https://github.com/srivarun-04/neural-core/blob/main/main.py"
click node_chat_api "https://github.com/srivarun-04/neural-core/blob/main/backend/api/chat.py"
click node_session_api "https://github.com/srivarun-04/neural-core/blob/main/backend/api/chats.py"
click node_document_api "https://github.com/srivarun-04/neural-core/blob/main/backend/api/documents.py"
click node_upload_api "https://github.com/srivarun-04/neural-core/blob/main/backend/api/upload.py"
click node_health_api "https://github.com/srivarun-04/neural-core/blob/main/backend/api/health.py"
click node_agent_core "https://github.com/srivarun-04/neural-core/blob/main/backend/agents/neural_agent.py"
click node_calculator "https://github.com/srivarun-04/neural-core/blob/main/backend/tools/calculator_tool.py"
click node_rag_tool "https://github.com/srivarun-04/neural-core/blob/main/backend/tools/rag_tool.py"
click node_document_manager "https://github.com/srivarun-04/neural-core/blob/main/backend/services/document_manager.py"
click node_loaders "https://github.com/srivarun-04/neural-core/blob/main/backend/rag/loaders.py"
click node_splitter "https://github.com/srivarun-04/neural-core/blob/main/backend/rag/splitter.py"
click node_embeddings "https://github.com/srivarun-04/neural-core/blob/main/backend/rag/embeddings.py"
click node_vector_store "https://github.com/srivarun-04/neural-core/blob/main/backend/database/vector_store.py"
click node_conversation_service "https://github.com/srivarun-04/neural-core/blob/main/backend/services/conversation_service.py"
click node_memory_service "https://github.com/srivarun-04/neural-core/blob/main/backend/services/memory_service.py"
click node_sqlite "https://github.com/srivarun-04/neural-core/blob/main/backend/database/sqlite_db.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_app,node_chat_ui,node_session_ui,node_knowledge_ui,node_chat_hook,node_api_client,node_local_storage,node_user toneBlue
class node_fastapi,node_chat_api,node_session_api,node_document_api,node_upload_api,node_health_api toneAmber
class node_agent_core,node_calculator,node_rag_tool,node_llm toneMint
class node_document_manager,node_loaders,node_splitter,node_embeddings,node_vector_store toneRose
class node_conversation_service,node_memory_service,node_sqlite toneIndigo
```

## Components

### Workspace UI

- [Workspace shell](https://github.com/srivarun-04/neural-core/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Chat workspace](https://github.com/srivarun-04/neural-core/blob/main/frontend/src/components/Chat/ChatArea.tsx): `frontend/src/components/Chat/ChatArea.tsx`
- [Session manager](https://github.com/srivarun-04/neural-core/blob/main/frontend/src/components/Sidebar/Sidebar.tsx): `frontend/src/components/Sidebar/Sidebar.tsx`
- [Knowledge dashboard](https://github.com/srivarun-04/neural-core/blob/main/frontend/src/components/KnowledgeBase/KnowledgeBase.tsx): `frontend/src/components/KnowledgeBase/KnowledgeBase.tsx`
- [Chat state](https://github.com/srivarun-04/neural-core/blob/main/frontend/src/hooks/useChat.ts): `frontend/src/hooks/useChat.ts`
- [HTTP and SSE client](https://github.com/srivarun-04/neural-core/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Local preferences](https://github.com/srivarun-04/neural-core/blob/main/frontend/src/utils/storage.ts): `frontend/src/utils/storage.ts`

### API Layer

- [FastAPI application](https://github.com/srivarun-04/neural-core/blob/main/main.py): `main.py`
- [Chat endpoints](https://github.com/srivarun-04/neural-core/blob/main/backend/api/chat.py): `backend/api/chat.py`
- [Session endpoints](https://github.com/srivarun-04/neural-core/blob/main/backend/api/chats.py): `backend/api/chats.py`
- [Document endpoints](https://github.com/srivarun-04/neural-core/blob/main/backend/api/documents.py): `backend/api/documents.py`
- [Upload endpoint](https://github.com/srivarun-04/neural-core/blob/main/backend/api/upload.py): `backend/api/upload.py`
- [Health endpoint](https://github.com/srivarun-04/neural-core/blob/main/backend/api/health.py): `backend/api/health.py`

### Agent and Retrieval

- [Neural agent](https://github.com/srivarun-04/neural-core/blob/main/backend/agents/neural_agent.py): `backend/agents/neural_agent.py`
- [Safe calculator](https://github.com/srivarun-04/neural-core/blob/main/backend/tools/calculator_tool.py): `backend/tools/calculator_tool.py`
- [Knowledge search tool](https://github.com/srivarun-04/neural-core/blob/main/backend/tools/rag_tool.py): `backend/tools/rag_tool.py`

### Knowledge Ingestion

- [Document lifecycle](https://github.com/srivarun-04/neural-core/blob/main/backend/services/document_manager.py): `backend/services/document_manager.py`
- [File loaders](https://github.com/srivarun-04/neural-core/blob/main/backend/rag/loaders.py): `backend/rag/loaders.py`
- [Chunk preparation](https://github.com/srivarun-04/neural-core/blob/main/backend/rag/splitter.py): `backend/rag/splitter.py`
- [Text embeddings](https://github.com/srivarun-04/neural-core/blob/main/backend/rag/embeddings.py): `backend/rag/embeddings.py`
- [FAISS index](https://github.com/srivarun-04/neural-core/blob/main/backend/database/vector_store.py): `backend/database/vector_store.py`

### Conversation Memory

- [Session persistence](https://github.com/srivarun-04/neural-core/blob/main/backend/services/conversation_service.py): `backend/services/conversation_service.py`
- [Sliding history](https://github.com/srivarun-04/neural-core/blob/main/backend/services/memory_service.py): `backend/services/memory_service.py`
- [SQLite history](https://github.com/srivarun-04/neural-core/blob/main/backend/database/sqlite_db.py): `backend/database/sqlite_db.py`

### Other components

- **Workspace user**
- **OpenRouter model**

## Connections

- Workspace user → Workspace shell: uses
- Workspace shell → Chat workspace: shows (evidence: `frontend/src/App.tsx`)
- Workspace shell → Session manager: shows (evidence: `frontend/src/App.tsx`)
- Workspace shell → Knowledge dashboard: shows (evidence: `frontend/src/App.tsx`)
- Workspace shell → Chat state: uses (evidence: `frontend/src/App.tsx`)
- Chat state → HTTP and SSE client: calls (evidence: `frontend/src/hooks/useChat.ts`)
- Workspace shell → Local preferences: persists settings (evidence: `frontend/src/App.tsx`)
- HTTP and SSE client → Chat endpoints: HTTP / SSE
- HTTP and SSE client → Session endpoints: manages sessions
- HTTP and SSE client → Document endpoints: reads documents
- HTTP and SSE client → Upload endpoint: uploads files
- Workspace shell → Health endpoint: polls health (evidence: `frontend/src/App.tsx`)
- FastAPI application → Chat endpoints: mounts router (evidence: `main.py`)
- FastAPI application → Session endpoints: mounts router (evidence: `main.py`)
- FastAPI application → Document endpoints: mounts router (evidence: `main.py`)
- FastAPI application → Upload endpoint: mounts router (evidence: `main.py`)
- FastAPI application → Health endpoint: mounts router (evidence: `main.py`)
- Chat endpoints → Neural agent: invokes (evidence: `backend/api/chat.py`)
- Chat endpoints → Sliding history: loads history (evidence: `backend/api/chat.py`)
- Chat endpoints → Session persistence: stores turns (evidence: `backend/api/chat.py`)
- Session endpoints → Session persistence: manages sessions (evidence: `backend/api/chats.py`)
- Document endpoints → Document lifecycle: manages documents (evidence: `backend/api/documents.py`)
- Upload endpoint → Document lifecycle: indexes uploads (evidence: `backend/api/upload.py`)
- Health endpoint → Document lifecycle: reports status (evidence: `backend/api/health.py`)
- Health endpoint → Neural agent: reports status (evidence: `backend/api/health.py`)
- Neural agent → OpenRouter model: requests completions
- Neural agent → Safe calculator: dispatches calculations (evidence: `backend/agents/neural_agent.py`)
- Neural agent → Knowledge search tool: dispatches searches (evidence: `backend/agents/neural_agent.py`)
- Knowledge search tool → Document lifecycle: retrieves context (evidence: `backend/tools/rag_tool.py`)
- Document lifecycle → File loaders: loads files (evidence: `backend/services/document_manager.py`)
- Document lifecycle → Chunk preparation: chunks content (evidence: `backend/services/document_manager.py`)
- Document lifecycle → Text embeddings: creates vectors (evidence: `backend/services/document_manager.py`)
- Document lifecycle → FAISS index: updates index (evidence: `backend/services/document_manager.py`)
- Knowledge search tool → FAISS index: searches index (evidence: `backend/tools/rag_tool.py`)
- Sliding history → Session persistence: reads recent turns (evidence: `backend/services/memory_service.py`)
- Session persistence → SQLite history: queries and writes (evidence: `backend/services/conversation_service.py`)
- FastAPI application → Document lifecycle: syncs at startup (evidence: `main.py`)
