# m-awais-11/nova-neural-operations-virtual-assistant architecture

> Architecture diagram of the GitHub repository m-awais-11/nova-neural-operations-virtual-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/m-awais-11/nova-neural-operations-virtual-assistant
- Repository: https://github.com/m-awais-11/nova-neural-operations-virtual-assistant

## Overview

This is a local Windows desktop agent that turns natural-language requests into allowlisted computer actions. Users enter commands through the CLI or Tkinter GUI; the agent plans tool calls with a configured language-model service, executes them behind validation and confirmation gates, verifies outcomes, and returns a response. The product also includes file and application tools, browser tools, and SQLite history with sensitive-data redaction. README capabilities inform the browser/tool coverage; unsampled module internals are not expanded, and uncertain connections are omitted.

Main entry points: [`agent/executor.py`](https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/agent/executor.py) (Tool executor), [`agent/agent.py`](https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/agent/agent.py) (Agent orchestrator), [`agent/planner.py`](https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/agent/planner.py) (Task planner), [`memory/memory.py`](https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/memory/memory.py) (Interaction memory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[main.py]"]
  node_gui["Desktop GUI<br/>[gui.py]"]
end

subgraph group_orchestration["Agent orchestration"]
  node_agent["Agent orchestrator<br/>[agent.py]"]
  node_planner["Task planner<br/>[planner.py]"]
  node_executor["Tool executor<br/>[executor.py]"]
  node_verifier["Outcome verifier<br/>[verifier.py]"]
end

subgraph group_tools["Allowlisted tools"]
  node_registry["Tool registry<br/>[registry.py]"]
  node_filetools["File tools<br/>[file_tools.py]"]
  node_apptools["Application tools<br/>[app_tools.py]"]
  node_browsertools["Browser tools<br/>[browser_tools.py]"]
end

subgraph group_security["Security controls"]
  node_pathvalidator["Path sandbox<br/>[path_validator.py]"]
  node_permissions["Permissions<br/>[permissions.py]"]
  node_confirmation["Confirmation gate<br/>[confirmation.py]"]
end

subgraph group_state["Configuration and memory"]
  node_settings["Agent settings<br/>[settings.py]"]
  node_memory["Interaction memory<br/>[memory.py]"]
  node_sqlite[("SQLite database")]
end

node_user(("User"))
node_llm{{"LLM service"}}
node_filesystem[("Local files")]
node_applications{{"Desktop applications"}}

node_user -->|"enters command"| node_cli
node_user -->|"enters command"| node_gui
node_cli -->|"runs task"| node_agent
node_gui -->|"runs task"| node_agent
node_agent -->|"requests plan"| node_planner
node_planner -->|"gets tool specs"| node_registry
node_planner -->|"sends request"| node_llm
node_llm -->|"returns plan"| node_planner
node_agent -->|"dispatches calls"| node_executor
node_executor -->|"looks up tool"| node_registry
node_executor -->|"requests approval"| node_confirmation
node_executor -->|"checks outcome"| node_verifier
node_executor -->|"executes tool"| node_filetools
node_executor -->|"executes tool"| node_apptools
node_executor -->|"executes tool"| node_browsertools
node_filetools -->|"validates paths"| node_pathvalidator
node_apptools -->|"validates target"| node_pathvalidator
node_filetools -->|"reads and writes"| node_filesystem
node_verifier -->|"checks disk state"| node_filesystem
node_apptools -->|"launches process"| node_applications
node_verifier -->|"checks process state"| node_applications
node_pathvalidator -->|"reads allowed roots"| node_settings
node_confirmation -->|"reads policy"| node_settings
node_executor -->|"handles access errors"| node_permissions
node_agent -->|"logs interactions"| node_memory
node_cli -->|"reads history"| node_memory
node_memory -->|"reads and writes"| node_sqlite
node_memory -->|"reads database path"| node_settings

click node_cli "https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/main.py"
click node_gui "https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/gui.py"
click node_agent "https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/agent/agent.py"
click node_planner "https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/agent/planner.py"
click node_executor "https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/agent/executor.py"
click node_verifier "https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/agent/verifier.py"
click node_registry "https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/tools/registry.py"
click node_filetools "https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/tools/file_tools.py"
click node_apptools "https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/tools/app_tools.py"
click node_browsertools "https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/tools/browser_tools.py"
click node_pathvalidator "https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/security/path_validator.py"
click node_permissions "https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/security/permissions.py"
click node_confirmation "https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/security/confirmation.py"
click node_settings "https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/config/settings.py"
click node_memory "https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/memory/memory.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_cli,node_gui,node_user toneBlue
class node_agent,node_planner,node_executor,node_verifier,node_filesystem toneAmber
class node_registry,node_filetools,node_apptools,node_browsertools toneMint
class node_pathvalidator,node_permissions,node_confirmation toneRose
class node_settings,node_memory,node_sqlite,node_llm,node_applications toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/main.py): `main.py`
- [Desktop GUI](https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/gui.py): `gui.py`

### Agent orchestration

- [Agent orchestrator](https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/agent/agent.py): `agent/agent.py`
- [Task planner](https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/agent/planner.py): `agent/planner.py`
- [Tool executor](https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/agent/executor.py): `agent/executor.py`
- [Outcome verifier](https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/agent/verifier.py): `agent/verifier.py`

### Allowlisted tools

- [Tool registry](https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/tools/registry.py): `tools/registry.py`
- [File tools](https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/tools/file_tools.py): `tools/file_tools.py`
- [Application tools](https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/tools/app_tools.py): `tools/app_tools.py`
- [Browser tools](https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/tools/browser_tools.py): `tools/browser_tools.py`

### Security controls

- [Path sandbox](https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/security/path_validator.py): `security/path_validator.py`
- [Permissions](https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/security/permissions.py): `security/permissions.py`
- [Confirmation gate](https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/security/confirmation.py): `security/confirmation.py`

### Configuration and memory

- [Agent settings](https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/config/settings.py): `config/settings.py`
- [Interaction memory](https://github.com/m-awais-11/nova-neural-operations-virtual-assistant/blob/main/memory/memory.py): `memory/memory.py`
- **SQLite database**

### Other components

- **User**
- **LLM service**
- **Local files**
- **Desktop applications**

## Connections

- User → CLI: enters command
- User → Desktop GUI: enters command
- CLI → Agent orchestrator: runs task
- Desktop GUI → Agent orchestrator: runs task
- Agent orchestrator → Task planner: requests plan
- Task planner → Tool registry: gets tool specs
- Task planner → LLM service: sends request
- LLM service → Task planner: returns plan
- Agent orchestrator → Tool executor: dispatches calls
- Tool executor → Tool registry: looks up tool
- Tool executor → Confirmation gate: requests approval
- Tool executor → Outcome verifier: checks outcome
- Tool executor → File tools: executes tool
- Tool executor → Application tools: executes tool
- Tool executor → Browser tools: executes tool
- File tools → Path sandbox: validates paths
- Application tools → Path sandbox: validates target
- File tools → Local files: reads and writes
- Outcome verifier → Local files: checks disk state
- Application tools → Desktop applications: launches process
- Outcome verifier → Desktop applications: checks process state
- Path sandbox → Agent settings: reads allowed roots
- Confirmation gate → Agent settings: reads policy
- Tool executor → Permissions: handles access errors
- Agent orchestrator → Interaction memory: logs interactions
- CLI → Interaction memory: reads history
- Interaction memory → SQLite database: reads and writes
- Interaction memory → Agent settings: reads database path