# gaurav-nova1702/aria architecture

> Architecture diagram of the GitHub repository gaurav-nova1702/aria, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gaurav-nova1702/aria
- Repository: https://github.com/gaurav-nova1702/aria

## Overview

NeuralMind is a React/FastAPI self-learning agent. A user signs in, sends a chat message through the frontend API to the backend chat endpoint, and the orchestrator enriches generation with memory, knowledge, research and positive feedback examples before returning a response. Users can also search and save knowledge, run research, rate answers, use browser speech, and view metrics. The source excerpts establish several backend calls; other links below are supported by the README or SOURCE INDEX, so unsampled internals are not inferred.

Main entry points: [`frontend/src/api/client.js`](https://github.com/gaurav-nova1702/aria/blob/main/frontend/src/api/client.js) (API client), [`backend/agent/orchestrator.py`](https://github.com/gaurav-nova1702/aria/blob/main/backend/agent/orchestrator.py) (Agent orchestrator), [`frontend/src/App.jsx`](https://github.com/gaurav-nova1702/aria/blob/main/frontend/src/App.jsx) (App shell), [`backend/agent/knowledge.py`](https://github.com/gaurav-nova1702/aria/blob/main/backend/agent/knowledge.py) (Knowledge manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend experience"]
  node_app["App shell<br/>[App.jsx]"]
  node_chat_ui["Chat interface<br/>[ChatWindow.jsx]"]
  node_chat_hook["Chat state hook<br/>[useChat.js]"]
  node_store["Agent state<br/>[agentStore.js]"]
  node_voice["Voice interaction<br/>[useVoice.js]"]
  node_research_ui["Research panel<br/>[ResearchPanel.jsx]"]
  node_knowledge_ui["Knowledge browser<br/>[KnowledgeBase.jsx]"]
  node_metrics_ui["Metrics dashboard<br/>[MetricsPanel.jsx]"]
  node_feedback_ui["Feedback controls"]
end

subgraph group_api["API and identity"]
  node_api_client["API client<br/>[client.js]"]
  node_auth["Token verification<br/>[auth.py]"]
  node_chat_api["Chat endpoints<br/>[chat.py]"]
  node_knowledge_api["Knowledge endpoints<br/>[knowledge.py]"]
  node_research_api["Research endpoint<br/>[research.py]"]
  node_feedback_api["Feedback endpoints<br/>[feedback.py]"]
end

subgraph group_agent["Agent capabilities"]
  node_orchestrator["Agent orchestrator<br/>[orchestrator.py]"]
  node_memory["Conversation memory<br/>[memory.py]"]
  node_knowledge["Knowledge manager<br/>[knowledge.py]"]
  node_document["Document processing"]
  node_research["Web research<br/>[research.py]"]
  node_feedback["Feedback learning<br/>[feedback.py]"]
end

subgraph group_data["Persistence and retrieval"]
  node_embeddings["Embedding service<br/>[embeddings.py]"]
  node_vector[("Vector storage<br/>[pgvector_store.py]")]
  node_database[("Relational database<br/>[database.py]")]
end

node_user(("User"))
node_gemini{{"Google Gemini"}}
node_supabase{{"Supabase Auth"}}
node_web{{"Web search and pages"}}

node_user -->|"uses"| node_app
node_app -->|"renders"| node_chat_ui
node_app -->|"renders"| node_research_ui
node_app -->|"renders"| node_knowledge_ui
node_app -->|"renders"| node_metrics_ui
node_chat_ui -.->|"uses"| node_chat_hook
node_chat_hook -->|"calls"| node_api_client
node_chat_hook -->|"updates"| node_store
node_voice -->|"updates"| node_store
node_research_ui -->|"searches through"| node_api_client
node_feedback_ui -.->|"submits through"| node_api_client
node_knowledge_ui -.->|"requests through"| node_api_client
node_metrics_ui -.->|"requests through"| node_api_client
node_api_client -->|"gets session token"| node_supabase
node_api_client -->|"calls REST"| node_chat_api
node_api_client -->|"calls REST"| node_knowledge_api
node_api_client -->|"calls REST"| node_research_api
node_api_client -->|"calls REST"| node_feedback_api
node_chat_api -->|"verifies identity"| node_auth
node_knowledge_api -->|"verifies identity"| node_auth
node_research_api -->|"verifies identity"| node_auth
node_chat_api -->|"dispatches chat"| node_orchestrator
node_knowledge_api -->|"processes uploads"| node_document
node_knowledge_api -->|"manages entries"| node_knowledge
node_research_api -->|"runs search"| node_research
node_feedback_api -.->|"handles ratings"| node_feedback
node_orchestrator -->|"retrieves history"| node_memory
node_orchestrator -->|"searches knowledge"| node_knowledge
node_orchestrator -->|"requests research"| node_research
node_orchestrator -->|"gets examples"| node_feedback
node_orchestrator -.->|"generates response"| node_gemini
node_knowledge -->|"creates vectors"| node_embeddings
node_knowledge -->|"searches vectors"| node_vector
node_knowledge -->|"persists entries"| node_database
node_research -->|"searches and fetches"| node_web
node_research -->|"summarizes pages"| node_gemini
node_research -->|"caches results"| node_database
node_feedback -->|"reads ratings"| node_database
node_memory -.->|"stores exchanges"| node_database

click node_app "https://github.com/gaurav-nova1702/aria/blob/main/frontend/src/App.jsx"
click node_chat_ui "https://github.com/gaurav-nova1702/aria/blob/main/frontend/src/components/ChatWindow.jsx"
click node_chat_hook "https://github.com/gaurav-nova1702/aria/blob/main/frontend/src/hooks/useChat.js"
click node_store "https://github.com/gaurav-nova1702/aria/blob/main/frontend/src/store/agentStore.js"
click node_voice "https://github.com/gaurav-nova1702/aria/blob/main/frontend/src/hooks/useVoice.js"
click node_research_ui "https://github.com/gaurav-nova1702/aria/blob/main/frontend/src/components/ResearchPanel.jsx"
click node_knowledge_ui "https://github.com/gaurav-nova1702/aria/blob/main/frontend/src/components/KnowledgeBase.jsx"
click node_metrics_ui "https://github.com/gaurav-nova1702/aria/blob/main/frontend/src/components/MetricsPanel.jsx"
click node_feedback_ui "https://github.com/gaurav-nova1702/aria/blob/main/frontend/src/components/FeedbackButtons.jsx"
click node_api_client "https://github.com/gaurav-nova1702/aria/blob/main/frontend/src/api/client.js"
click node_auth "https://github.com/gaurav-nova1702/aria/blob/main/backend/utils/auth.py"
click node_chat_api "https://github.com/gaurav-nova1702/aria/blob/main/backend/api/chat.py"
click node_knowledge_api "https://github.com/gaurav-nova1702/aria/blob/main/backend/api/knowledge.py"
click node_research_api "https://github.com/gaurav-nova1702/aria/blob/main/backend/api/research.py"
click node_feedback_api "https://github.com/gaurav-nova1702/aria/blob/main/backend/api/feedback.py"
click node_orchestrator "https://github.com/gaurav-nova1702/aria/blob/main/backend/agent/orchestrator.py"
click node_memory "https://github.com/gaurav-nova1702/aria/blob/main/backend/agent/memory.py"
click node_knowledge "https://github.com/gaurav-nova1702/aria/blob/main/backend/agent/knowledge.py"
click node_document "https://github.com/gaurav-nova1702/aria/blob/main/backend/agent/document_processor.py"
click node_research "https://github.com/gaurav-nova1702/aria/blob/main/backend/agent/research.py"
click node_feedback "https://github.com/gaurav-nova1702/aria/blob/main/backend/agent/feedback.py"
click node_embeddings "https://github.com/gaurav-nova1702/aria/blob/main/backend/utils/embeddings.py"
click node_vector "https://github.com/gaurav-nova1702/aria/blob/main/backend/agent/pgvector_store.py"
click node_database "https://github.com/gaurav-nova1702/aria/blob/main/backend/models/database.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_chat_hook,node_store,node_voice,node_research_ui,node_knowledge_ui,node_metrics_ui,node_feedback_ui,node_user toneBlue
class node_api_client,node_auth,node_chat_api,node_knowledge_api,node_research_api,node_feedback_api toneAmber
class node_orchestrator,node_memory,node_knowledge,node_document,node_research,node_feedback toneMint
class node_embeddings,node_vector,node_database toneRose
class node_gemini,node_supabase,node_web toneIndigo
```

## Components

### Frontend experience

- [App shell](https://github.com/gaurav-nova1702/aria/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Chat interface](https://github.com/gaurav-nova1702/aria/blob/main/frontend/src/components/ChatWindow.jsx): `frontend/src/components/ChatWindow.jsx`
- [Chat state hook](https://github.com/gaurav-nova1702/aria/blob/main/frontend/src/hooks/useChat.js): `frontend/src/hooks/useChat.js`
- [Agent state](https://github.com/gaurav-nova1702/aria/blob/main/frontend/src/store/agentStore.js): `frontend/src/store/agentStore.js`
- [Voice interaction](https://github.com/gaurav-nova1702/aria/blob/main/frontend/src/hooks/useVoice.js): `frontend/src/hooks/useVoice.js`
- [Research panel](https://github.com/gaurav-nova1702/aria/blob/main/frontend/src/components/ResearchPanel.jsx): `frontend/src/components/ResearchPanel.jsx`
- [Knowledge browser](https://github.com/gaurav-nova1702/aria/blob/main/frontend/src/components/KnowledgeBase.jsx): `frontend/src/components/KnowledgeBase.jsx`
- [Metrics dashboard](https://github.com/gaurav-nova1702/aria/blob/main/frontend/src/components/MetricsPanel.jsx): `frontend/src/components/MetricsPanel.jsx`
- [Feedback controls](https://github.com/gaurav-nova1702/aria/blob/main/frontend/src/components/FeedbackButtons.jsx): `frontend/src/components/FeedbackButtons.jsx`

### API and identity

- [API client](https://github.com/gaurav-nova1702/aria/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`
- [Token verification](https://github.com/gaurav-nova1702/aria/blob/main/backend/utils/auth.py): `backend/utils/auth.py`
- [Chat endpoints](https://github.com/gaurav-nova1702/aria/blob/main/backend/api/chat.py): `backend/api/chat.py`
- [Knowledge endpoints](https://github.com/gaurav-nova1702/aria/blob/main/backend/api/knowledge.py): `backend/api/knowledge.py`
- [Research endpoint](https://github.com/gaurav-nova1702/aria/blob/main/backend/api/research.py): `backend/api/research.py`
- [Feedback endpoints](https://github.com/gaurav-nova1702/aria/blob/main/backend/api/feedback.py): `backend/api/feedback.py`

### Agent capabilities

- [Agent orchestrator](https://github.com/gaurav-nova1702/aria/blob/main/backend/agent/orchestrator.py): `backend/agent/orchestrator.py`
- [Conversation memory](https://github.com/gaurav-nova1702/aria/blob/main/backend/agent/memory.py): `backend/agent/memory.py`
- [Knowledge manager](https://github.com/gaurav-nova1702/aria/blob/main/backend/agent/knowledge.py): `backend/agent/knowledge.py`
- [Document processing](https://github.com/gaurav-nova1702/aria/blob/main/backend/agent/document_processor.py): `backend/agent/document_processor.py`
- [Web research](https://github.com/gaurav-nova1702/aria/blob/main/backend/agent/research.py): `backend/agent/research.py`
- [Feedback learning](https://github.com/gaurav-nova1702/aria/blob/main/backend/agent/feedback.py): `backend/agent/feedback.py`

### Persistence and retrieval

- [Embedding service](https://github.com/gaurav-nova1702/aria/blob/main/backend/utils/embeddings.py): `backend/utils/embeddings.py`
- [Vector storage](https://github.com/gaurav-nova1702/aria/blob/main/backend/agent/pgvector_store.py): `backend/agent/pgvector_store.py`
- [Relational database](https://github.com/gaurav-nova1702/aria/blob/main/backend/models/database.py): `backend/models/database.py`

### Other components

- **User**
- **Google Gemini**
- **Supabase Auth**
- **Web search and pages**

## Connections

- User → App shell: uses
- App shell → Chat interface: renders (evidence: `frontend/src/App.jsx`)
- App shell → Research panel: renders (evidence: `frontend/src/App.jsx`)
- App shell → Knowledge browser: renders (evidence: `frontend/src/App.jsx`)
- App shell → Metrics dashboard: renders (evidence: `frontend/src/App.jsx`)
- Chat interface → Chat state hook: uses
- Chat state hook → API client: calls (evidence: `frontend/src/hooks/useChat.js`)
- Chat state hook → Agent state: updates (evidence: `frontend/src/hooks/useChat.js`)
- Voice interaction → Agent state: updates (evidence: `frontend/src/hooks/useVoice.js`)
- Research panel → API client: searches through (evidence: `frontend/src/components/ResearchPanel.jsx`)
- Feedback controls → API client: submits through
- Knowledge browser → API client: requests through
- Metrics dashboard → API client: requests through
- API client → Supabase Auth: gets session token (evidence: `frontend/src/api/client.js`)
- API client → Chat endpoints: calls REST
- API client → Knowledge endpoints: calls REST
- API client → Research endpoint: calls REST
- API client → Feedback endpoints: calls REST
- Chat endpoints → Token verification: verifies identity (evidence: `backend/api/chat.py`)
- Knowledge endpoints → Token verification: verifies identity (evidence: `backend/api/knowledge.py`)
- Research endpoint → Token verification: verifies identity (evidence: `backend/api/research.py`)
- Chat endpoints → Agent orchestrator: dispatches chat (evidence: `backend/api/chat.py`)
- Knowledge endpoints → Document processing: processes uploads (evidence: `backend/api/knowledge.py`)
- Knowledge endpoints → Knowledge manager: manages entries (evidence: `backend/api/knowledge.py`)
- Research endpoint → Web research: runs search (evidence: `backend/api/research.py`)
- Feedback endpoints → Feedback learning: handles ratings
- Agent orchestrator → Conversation memory: retrieves history (evidence: `backend/agent/orchestrator.py`)
- Agent orchestrator → Knowledge manager: searches knowledge (evidence: `backend/agent/orchestrator.py`)
- Agent orchestrator → Web research: requests research (evidence: `backend/agent/orchestrator.py`)
- Agent orchestrator → Feedback learning: gets examples (evidence: `backend/agent/orchestrator.py`)
- Agent orchestrator → Google Gemini: generates response
- Knowledge manager → Embedding service: creates vectors (evidence: `backend/agent/knowledge.py`)
- Knowledge manager → Vector storage: searches vectors (evidence: `backend/agent/knowledge.py`)
- Knowledge manager → Relational database: persists entries (evidence: `backend/agent/knowledge.py`)
- Web research → Web search and pages: searches and fetches (evidence: `backend/agent/research.py`)
- Web research → Google Gemini: summarizes pages (evidence: `backend/agent/research.py`)
- Web research → Relational database: caches results (evidence: `backend/agent/research.py`)
- Feedback learning → Relational database: reads ratings (evidence: `backend/agent/feedback.py`)
- Conversation memory → Relational database: stores exchanges
