# hemachandranl2025cse-prog/jarvis-ai architecture

> Architecture diagram of the GitHub repository hemachandranl2025cse-prog/jarvis-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hemachandranl2025cse-prog/jarvis-ai
- Repository: https://github.com/hemachandranl2025cse-prog/jarvis-ai

## Overview

#### Purpose and Entry Points
JARVIS-AI is a Python personal-assistant system combining LLM-driven task planning with desktop, browser, file, and web automation. Primary application entry points are `main.py` for assistant startup and `ui.py` for the user-facing interface. `or_client.py` is the likely boundary to the external AI/model client.

#### Agent Orchestration
The `agent` package defines the execution pipeline:
- `agent/planner.py` translates user intent into a plan of actions.
- `agent/executor.py` dispatches planned work to action implementations.
- `agent/task_queue.py` sequences or manages pending tasks.
- `agent/error_handler.py` provides failure handling around planning/execution.

This separates intent interpretation from side-effecting automation, allowing the executor to act as the principal control boundary.

#### Action Capability Layer
The `actions` directory is the assistant’s tool surface. Action modules encapsulate concrete external effects and are selected by the agent runtime. Major capability groups include:
- Desktop/application control: `actions/computer_control.py`, `actions/open_app.py`, `actions/desktop.py`
- Browser and web operations: `actions/browser_control.py`, `actions/web_search.py`, `actions/youtube_video.py`
- Local file and screen processing: `actions/file_controller.py`, `actions/file_processor.py`, `actions/screen_processor.py`
- Communication and personal workflows: `actions/send_message.py`, `actions/reminder.py`, `actions/flight_finder.py`
- Development and system operations: `actions/code_helper.py`, `actions/dev_agent.py`, `actions/computer_settings.py`

These modules form the key safety and integration boundary because they interact with the OS, applications, browser, local files, and remote services.

#### Prompt and Model Boundary
`core/prompt.txt` contains the core prompt/instruction asset used to steer assistant behavior. `or_client.py` likely submits prompts and receives generated responses from an external AI provider; the exact provider is not identified in the supplied repository view. The planner consumes this model-facing behavior to decide which action sequence to execute.

#### State, Memory, and Configuration
Persistent assistant context is managed separately from execution:
- `memory/memory_manager.py` owns memory storage/retrieval behavior.
- `memory/config_manager.py` manages memory-related configuration.
- `config/__init__.py` establishes the project configuration package.

The expected flow is user input → prompt/model planning → queued execution → action results, with relevant context read from or written to the memory layer.

#### Runtime and Infrastructure
The project is Python-based, with package/install metadata in `setup.py` and runtime dependencies in `requirements.txt`. It operates as a local automation application rather than an explicitly defined web service. Material external dependencies include an AI/model endpoint through `or_client.py`, browser/web destinations used by search/video/flight actions, and the host operating system and installed applications controlled by desktop actions.

#### Primary Control Flow
1. `main.py` and/or `ui.py` accepts a user request.
2. The planner (`agent/planner.py`) uses prompt guidance (`core/prompt.txt`), memory, and the model client (`or_client.py`) to derive work.
3. Tasks move through `agent/task_queue.py`.
4. `agent/executor.py` invokes one or more modules in `actions/`.
5. Results and failures are handled by `agent/error_handler.py` and may update `memory/memory_manager.py`.

Main entry points: [`agent/executor.py`](https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/agent/executor.py) (Action executor), [`agent/planner.py`](https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/agent/planner.py) (Task planner), [`memory/memory_manager.py`](https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/memory/memory_manager.py) (Memory manager), [`agent/task_queue.py`](https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/agent/task_queue.py) (Task queue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry Points"]
  node_main["Assistant startup<br/>Python entry point<br/>[main.py]"]
  node_ui["User interface<br/>Python UI<br/>[ui.py]"]
end

subgraph group_agent["Agent Runtime"]
  node_planner["Task planner<br/>agent planner<br/>[planner.py]"]
  node_queue["Task queue<br/>task scheduler<br/>[task_queue.py]"]
  node_executor["Action executor<br/>execution boundary<br/>[executor.py]"]
  node_errors["Error handler<br/>failure handling<br/>[error_handler.py]"]
end

subgraph group_tools["Automation Capabilities"]
  node_desktop_actions["Desktop control<br/>action modules"]
  node_browser_actions["Browser &amp; web actions<br/>action modules<br/>[browser_control.py]"]
  node_file_actions["File &amp; screen actions<br/>action modules<br/>[file_controller.py]"]
  node_workflow_actions["Personal workflow actions<br/>action modules<br/>[send_message.py]"]
  node_dev_actions["Development &amp; settings<br/>action modules<br/>[code_helper.py]"]
end

subgraph group_state["Context &amp; Guidance"]
  node_model_client{{"Model client<br/>AI client<br/>[or_client.py]"}}
  node_prompt["Core prompt<br/>prompt asset<br/>[prompt.txt]"]
  node_memory[("Memory manager<br/>context store<br/>[memory_manager.py]")]
  node_memory_config["Memory configuration<br/>[config_manager.py]"]
end

node_ai_provider{{"External AI provider<br/>external service"}}
node_host_web(("Host OS, apps &amp; web<br/>external systems"))

node_main -->|"starts request flow"| node_planner
node_ui -->|"submits request"| node_planner
node_planner -->|"uses guidance"| node_prompt
node_planner -->|"reads context"| node_memory
node_planner -->|"requests plan"| node_model_client
node_model_client -->|"model request"| node_ai_provider
node_planner -->|"enqueues tasks"| node_queue
node_queue -->|"dequeues work"| node_executor
node_executor -->|"dispatches"| node_desktop_actions
node_executor -->|"dispatches"| node_browser_actions
node_executor -->|"dispatches"| node_file_actions
node_executor -->|"dispatches"| node_workflow_actions
node_executor -->|"dispatches"| node_dev_actions
node_executor -->|"handles failures"| node_errors
node_executor -->|"stores results"| node_memory
node_memory_config -->|"configures"| node_memory
node_desktop_actions -->|"controls"| node_host_web
node_browser_actions -->|"automates"| node_host_web
node_file_actions -->|"accesses"| node_host_web
node_workflow_actions -->|"uses services"| node_host_web
node_dev_actions -->|"operates on"| node_host_web

click node_main "https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/main.py"
click node_ui "https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/ui.py"
click node_planner "https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/agent/planner.py"
click node_queue "https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/agent/task_queue.py"
click node_executor "https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/agent/executor.py"
click node_errors "https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/agent/error_handler.py"
click node_model_client "https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/or_client.py"
click node_prompt "https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/core/prompt.txt"
click node_memory "https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/memory/memory_manager.py"
click node_memory_config "https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/memory/config_manager.py"
click node_desktop_actions "https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/actions/computer_control.py"
click node_browser_actions "https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/actions/browser_control.py"
click node_file_actions "https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/actions/file_controller.py"
click node_workflow_actions "https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/actions/send_message.py"
click node_dev_actions "https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/actions/code_helper.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_main,node_ui toneBlue
class node_planner,node_queue,node_executor,node_errors toneAmber
class node_desktop_actions,node_browser_actions,node_file_actions,node_workflow_actions,node_dev_actions toneMint
class node_model_client,node_prompt,node_memory,node_memory_config toneRose
class node_ai_provider,node_host_web toneNeutral
```

## Components

### Entry Points

- [Assistant startup](https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/main.py): Python entry point · `main.py`
- [User interface](https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/ui.py): Python UI · `ui.py`

### Agent Runtime

- [Task planner](https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/agent/planner.py): agent planner · Converts user intent into an action plan. · `agent/planner.py`
- [Task queue](https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/agent/task_queue.py): task scheduler · `agent/task_queue.py`
- [Action executor](https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/agent/executor.py): execution boundary · Dispatches plans to side-effecting actions. · `agent/executor.py`
- [Error handler](https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/agent/error_handler.py): failure handling · `agent/error_handler.py`

### Automation Capabilities

Side-effecting integrations with the local machine and web.

- [Desktop control](https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/actions/computer_control.py): action modules · Controls the OS and installed applications. · `actions/computer_control.py`
- [Browser & web actions](https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/actions/browser_control.py): action modules · Automates browser operations and web lookups. · `actions/browser_control.py`
- [File & screen actions](https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/actions/file_controller.py): action modules · Processes local files and screen content. · `actions/file_controller.py`
- [Personal workflow actions](https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/actions/send_message.py): action modules · Handles messaging, reminders, and flight lookup. · `actions/send_message.py`
- [Development & settings](https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/actions/code_helper.py): action modules · Provides coding, development, and system settings operations. · `actions/code_helper.py`

### Context & Guidance

- [Model client](https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/or_client.py): AI client · Boundary to an external AI/model provider. · `or_client.py`
- [Core prompt](https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/core/prompt.txt): prompt asset · `core/prompt.txt`
- [Memory manager](https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/memory/memory_manager.py): context store · Reads and writes persistent assistant context. · `memory/memory_manager.py`
- [Memory configuration](https://github.com/hemachandranl2025cse-prog/jarvis-ai/blob/main/memory/config_manager.py): configuration · `memory/config_manager.py`

### Other components

- **External AI provider**: external service
- **Host OS, apps & web**: external systems

## Connections

- Assistant startup → Task planner: starts request flow
- User interface → Task planner: submits request
- Task planner → Core prompt: uses guidance
- Task planner → Memory manager: reads context
- Task planner → Model client: requests plan
- Model client → External AI provider: model request
- Task planner → Task queue: enqueues tasks
- Task queue → Action executor: dequeues work
- Action executor → Desktop control: dispatches
- Action executor → Browser & web actions: dispatches
- Action executor → File & screen actions: dispatches
- Action executor → Personal workflow actions: dispatches
- Action executor → Development & settings: dispatches
- Action executor → Error handler: handles failures
- Action executor → Memory manager: stores results
- Memory configuration → Memory manager: configures
- Desktop control → Host OS, apps & web: controls
- Browser & web actions → Host OS, apps & web: automates
- File & screen actions → Host OS, apps & web: accesses
- Personal workflow actions → Host OS, apps & web: uses services
- Development & settings → Host OS, apps & web: operates on