# tentax143/neuralagentv1 architecture

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

- Interactive diagram: https://gitdiagram.com/tentax143/neuralagentv1
- Repository: https://github.com/tentax143/neuralagentv1

## Overview

NeuralAgent is a desktop AI automation product: users sign in, create task threads, and receive conversational or automated task results. The documented workflow combines a React interface in Electron, a FastAPI service, configurable LLM agents, and Python desktop automation; browser-only background automation is a separate capability. The graph also preserves authentication, thread persistence, and model-provider configuration. Some frontend-to-backend and desktop-agent wiring is documented only at a high level, so those links are dashed rather than asserted as inspected calls.

Main entry points: [`backend/main.py`](https://github.com/tentax143/neuralagentv1/blob/main/backend/main.py) (FastAPI application), [`backend/routers/apps/threads.py`](https://github.com/tentax143/neuralagentv1/blob/main/backend/routers/apps/threads.py) (Thread routes), [`backend/routers/aiagent/generic.py`](https://github.com/tentax143/neuralagentv1/blob/main/backend/routers/aiagent/generic.py) (Task agent), [`backend/routers/aiagent/background.py`](https://github.com/tentax143/neuralagentv1/blob/main/backend/routers/aiagent/background.py) (Background agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_electron["Electron shell<br/>[main.js]"]
  node_react["React application<br/>[App.js]"]
  node_thread_ui["Thread interface<br/>[Thread.js]"]
  node_overlay_ui["Automation overlay<br/>[Overlay.js]"]
  node_api_client["API client<br/>[axios.js]"]
end

subgraph group_service["Backend service"]
  node_api["FastAPI application<br/>[main.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_thread_routes["Thread routes<br/>[threads.py]"]
end

subgraph group_agents["AI and automation"]
  node_generic_agent["Task agent<br/>[generic.py]"]
  node_suggestor["Suggestion agent<br/>[suggestor.py]"]
  node_background_agent["Background agent<br/>[background.py]"]
  node_prompts["Agent prompts<br/>[ai_prompts.py]"]
  node_llm["Model provider<br/>[llm_provider.py]"]
  node_agent_tools["Agent tools<br/>[agentic_tools.py]"]
  node_desktop_agent["Desktop automation<br/>[main.py]"]
  node_ui_extract["UI extraction<br/>[ui_extraction.py]"]
  node_background_desktop["Browser background mode<br/>[main.py]"]
end

subgraph group_state["Identity and state"]
  node_auth_dependency["Token validation"]
  node_auth_helpers["Token and sessions<br/>[auth_helper.py]"]
  node_database[("Postgres access<br/>[database.py]")]
  node_models[("Domain records<br/>[models.py]")]
end

node_user(("Desktop user"))

node_user -.->|"uses"| node_electron
node_electron -.->|"hosts"| node_react
node_react -->|"routes to"| node_thread_ui
node_react -->|"routes to"| node_overlay_ui
node_thread_ui -.->|"requests data"| node_api_client
node_api_client -.->|"calls API"| node_api
node_api -->|"registers"| node_auth_routes
node_api -->|"registers"| node_thread_routes
node_api -->|"registers"| node_generic_agent
node_api -->|"registers"| node_suggestor
node_api -->|"registers"| node_background_agent
node_auth_routes -->|"gets sessions"| node_database
node_auth_routes -->|"creates tokens"| node_auth_helpers
node_auth_dependency -->|"decodes tokens"| node_auth_helpers
node_auth_dependency -->|"queries"| node_database
node_auth_dependency -->|"checks records"| node_models
node_thread_routes -->|"requires user"| node_auth_dependency
node_thread_routes -->|"reads and writes"| node_database
node_thread_routes -->|"uses records"| node_models
node_thread_routes -.->|"starts task flow"| node_generic_agent
node_generic_agent -->|"gets model"| node_llm
node_generic_agent -->|"uses prompts"| node_prompts
node_generic_agent -->|"runs tools"| node_agent_tools
node_background_agent -->|"gets model"| node_llm
node_background_agent -->|"uses prompts"| node_prompts
node_suggestor -->|"gets model"| node_llm
node_desktop_agent -->|"extracts interface"| node_ui_extract
node_desktop_agent -.->|"controls desktop"| node_user
node_background_desktop -.->|"automates browser"| node_user
node_background_agent -.->|"dispatches work"| node_background_desktop

click node_electron "https://github.com/tentax143/neuralagentv1/blob/main/desktop/main.js"
click node_react "https://github.com/tentax143/neuralagentv1/blob/main/desktop/neuralagent-app/src/App.js"
click node_thread_ui "https://github.com/tentax143/neuralagentv1/blob/main/desktop/neuralagent-app/src/views/Thread.js"
click node_overlay_ui "https://github.com/tentax143/neuralagentv1/blob/main/desktop/neuralagent-app/src/views/Overlay.js"
click node_api_client "https://github.com/tentax143/neuralagentv1/blob/main/desktop/neuralagent-app/src/utils/axios.js"
click node_api "https://github.com/tentax143/neuralagentv1/blob/main/backend/main.py"
click node_auth_routes "https://github.com/tentax143/neuralagentv1/blob/main/backend/routers/apps/auth.py"
click node_thread_routes "https://github.com/tentax143/neuralagentv1/blob/main/backend/routers/apps/threads.py"
click node_generic_agent "https://github.com/tentax143/neuralagentv1/blob/main/backend/routers/aiagent/generic.py"
click node_suggestor "https://github.com/tentax143/neuralagentv1/blob/main/backend/routers/aiagent/suggestor.py"
click node_background_agent "https://github.com/tentax143/neuralagentv1/blob/main/backend/routers/aiagent/background.py"
click node_prompts "https://github.com/tentax143/neuralagentv1/blob/main/backend/utils/ai_prompts.py"
click node_llm "https://github.com/tentax143/neuralagentv1/blob/main/backend/utils/llm_provider.py"
click node_agent_tools "https://github.com/tentax143/neuralagentv1/blob/main/backend/utils/agentic_tools.py"
click node_desktop_agent "https://github.com/tentax143/neuralagentv1/blob/main/desktop/aiagent/main.py"
click node_ui_extract "https://github.com/tentax143/neuralagentv1/blob/main/desktop/aiagent/ui_extraction.py"
click node_background_desktop "https://github.com/tentax143/neuralagentv1/blob/main/desktop/aiagent/background_mode/aiagent/main.py"
click node_auth_dependency "https://github.com/tentax143/neuralagentv1/blob/main/backend/dependencies/auth_dependencies.py"
click node_auth_helpers "https://github.com/tentax143/neuralagentv1/blob/main/backend/utils/auth_helper.py"
click node_database "https://github.com/tentax143/neuralagentv1/blob/main/backend/db/database.py"
click node_models "https://github.com/tentax143/neuralagentv1/blob/main/backend/db/models.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_electron,node_react,node_thread_ui,node_overlay_ui,node_api_client,node_user toneBlue
class node_api,node_auth_routes,node_thread_routes toneAmber
class node_generic_agent,node_suggestor,node_background_agent,node_prompts,node_llm,node_agent_tools,node_desktop_agent,node_ui_extract,node_background_desktop toneMint
class node_auth_dependency,node_auth_helpers,node_database,node_models toneRose
```

## Components

### Desktop experience

- [Electron shell](https://github.com/tentax143/neuralagentv1/blob/main/desktop/main.js): `desktop/main.js`
- [React application](https://github.com/tentax143/neuralagentv1/blob/main/desktop/neuralagent-app/src/App.js): `desktop/neuralagent-app/src/App.js`
- [Thread interface](https://github.com/tentax143/neuralagentv1/blob/main/desktop/neuralagent-app/src/views/Thread.js): `desktop/neuralagent-app/src/views/Thread.js`
- [Automation overlay](https://github.com/tentax143/neuralagentv1/blob/main/desktop/neuralagent-app/src/views/Overlay.js): `desktop/neuralagent-app/src/views/Overlay.js`
- [API client](https://github.com/tentax143/neuralagentv1/blob/main/desktop/neuralagent-app/src/utils/axios.js): `desktop/neuralagent-app/src/utils/axios.js`

### Backend service

- [FastAPI application](https://github.com/tentax143/neuralagentv1/blob/main/backend/main.py): `backend/main.py`
- [Authentication routes](https://github.com/tentax143/neuralagentv1/blob/main/backend/routers/apps/auth.py): `backend/routers/apps/auth.py`
- [Thread routes](https://github.com/tentax143/neuralagentv1/blob/main/backend/routers/apps/threads.py): `backend/routers/apps/threads.py`

### AI and automation

- [Task agent](https://github.com/tentax143/neuralagentv1/blob/main/backend/routers/aiagent/generic.py): `backend/routers/aiagent/generic.py`
- [Suggestion agent](https://github.com/tentax143/neuralagentv1/blob/main/backend/routers/aiagent/suggestor.py): `backend/routers/aiagent/suggestor.py`
- [Background agent](https://github.com/tentax143/neuralagentv1/blob/main/backend/routers/aiagent/background.py): `backend/routers/aiagent/background.py`
- [Agent prompts](https://github.com/tentax143/neuralagentv1/blob/main/backend/utils/ai_prompts.py): `backend/utils/ai_prompts.py`
- [Model provider](https://github.com/tentax143/neuralagentv1/blob/main/backend/utils/llm_provider.py): `backend/utils/llm_provider.py`
- [Agent tools](https://github.com/tentax143/neuralagentv1/blob/main/backend/utils/agentic_tools.py): `backend/utils/agentic_tools.py`
- [Desktop automation](https://github.com/tentax143/neuralagentv1/blob/main/desktop/aiagent/main.py): `desktop/aiagent/main.py`
- [UI extraction](https://github.com/tentax143/neuralagentv1/blob/main/desktop/aiagent/ui_extraction.py): `desktop/aiagent/ui_extraction.py`
- [Browser background mode](https://github.com/tentax143/neuralagentv1/blob/main/desktop/aiagent/background_mode/aiagent/main.py): `desktop/aiagent/background_mode/aiagent/main.py`

### Identity and state

- [Token validation](https://github.com/tentax143/neuralagentv1/blob/main/backend/dependencies/auth_dependencies.py): `backend/dependencies/auth_dependencies.py`
- [Token and sessions](https://github.com/tentax143/neuralagentv1/blob/main/backend/utils/auth_helper.py): `backend/utils/auth_helper.py`
- [Postgres access](https://github.com/tentax143/neuralagentv1/blob/main/backend/db/database.py): `backend/db/database.py`
- [Domain records](https://github.com/tentax143/neuralagentv1/blob/main/backend/db/models.py): `backend/db/models.py`

### Other components

- **Desktop user**

## Connections

- Desktop user → Electron shell: uses
- Electron shell → React application: hosts
- React application → Thread interface: routes to (evidence: `desktop/neuralagent-app/src/App.js`)
- React application → Automation overlay: routes to (evidence: `desktop/neuralagent-app/src/App.js`)
- Thread interface → API client: requests data
- API client → FastAPI application: calls API
- FastAPI application → Authentication routes: registers (evidence: `backend/main.py`)
- FastAPI application → Thread routes: registers (evidence: `backend/main.py`)
- FastAPI application → Task agent: registers (evidence: `backend/main.py`)
- FastAPI application → Suggestion agent: registers (evidence: `backend/main.py`)
- FastAPI application → Background agent: registers (evidence: `backend/main.py`)
- Authentication routes → Postgres access: gets sessions (evidence: `backend/routers/apps/auth.py`)
- Authentication routes → Token and sessions: creates tokens (evidence: `backend/routers/apps/auth.py`)
- Token validation → Token and sessions: decodes tokens (evidence: `backend/dependencies/auth_dependencies.py`)
- Token validation → Postgres access: queries (evidence: `backend/dependencies/auth_dependencies.py`)
- Token validation → Domain records: checks records (evidence: `backend/dependencies/auth_dependencies.py`)
- Thread routes → Token validation: requires user (evidence: `backend/routers/apps/threads.py`)
- Thread routes → Postgres access: reads and writes (evidence: `backend/routers/apps/threads.py`)
- Thread routes → Domain records: uses records (evidence: `backend/routers/apps/threads.py`)
- Thread routes → Task agent: starts task flow
- Task agent → Model provider: gets model (evidence: `backend/routers/aiagent/generic.py`)
- Task agent → Agent prompts: uses prompts (evidence: `backend/routers/aiagent/generic.py`)
- Task agent → Agent tools: runs tools (evidence: `backend/routers/aiagent/generic.py`)
- Background agent → Model provider: gets model (evidence: `backend/routers/aiagent/background.py`)
- Background agent → Agent prompts: uses prompts (evidence: `backend/routers/aiagent/background.py`)
- Suggestion agent → Model provider: gets model (evidence: `backend/routers/aiagent/suggestor.py`)
- Desktop automation → UI extraction: extracts interface (evidence: `desktop/aiagent/main.py`)
- Desktop automation → Desktop user: controls desktop
- Browser background mode → Desktop user: automates browser
- Background agent → Browser background mode: dispatches work
