# itx-shivansh/aria architecture

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

- Interactive diagram: https://gitdiagram.com/itx-shivansh/aria
- Repository: https://github.com/itx-shivansh/aria

## Overview

#### Purpose and Runtime

ARIA is a personal desktop AI assistant. Electron hosts the desktop process, React/Vite renders the UI, and Ollama supplies the default local LLM. It supports conversational assistance plus routed actions for WhatsApp, code, email, calendar, files, and system operations.

Primary startup boundaries:
- Electron main process: `src/main.js`
- Renderer preload bridge: `src/preload.js`
- React renderer root: `src/renderer/app.jsx`
- Electron packaging/runtime configuration: `electron.config.js`

#### Desktop Process and Renderer Boundary

`src/main.js` creates and controls the Electron application/window lifecycle. `src/preload.js` is the isolation boundary between privileged Electron/Node capabilities and browser-like renderer code; IPC should cross through this bridge rather than exposing direct system access to React.

The renderer is a local React interface, not a web deployment:
- `src/renderer/index.html`
- `src/renderer/app.jsx`
- `src/renderer/chat/ChatWindow.jsx`

#### User Interaction Surface

The main interaction is chat. `ChatWindow.jsx` collects prompts and presents assistant responses, while `Sidebar.jsx` and `StatusBar.jsx` provide application navigation/status context. The dashboard is a separate presentation area.

Relevant UI components:
- `src/renderer/chat/ChatWindow.jsx`
- `src/renderer/dashboard/Dashboard.jsx`
- `src/renderer/components/Sidebar.jsx`

#### Agent Orchestration Pipeline

`ariaAgent.js` is the central assistant coordinator. A typical request flow is: chat input → agent → intent classification → optional capability module → model response/action result → UI response. The agent also incorporates persistent conversation/context memory.

Core stages:
- Agent coordinator: `src/agent/ariaAgent.js`
- Intent routing: `src/agent/intentParser.js`
- Persistent memory: `src/agent/memoryStore.js`

This layer is the principal control boundary between natural-language reasoning and side-effecting integrations.

#### Capability Modules

Intent-selected modules isolate domain actions from core conversation handling. They represent the operational surface of the assistant and may require elevated local access or third-party authentication.

Key modules:
- WhatsApp automation: `src/agent/modules/whatsappModule.js`
- Code writing/debugging/execution: `src/agent/modules/codeModule.js`
- Email drafting: `src/agent/modules/emailModule.js`
- Calendar/scheduling: `src/agent/modules/calendarModule.js`
- File and system actions: `src/agent/modules/fileModule.js`, `src/agent/modules/systemModule.js`

#### AI Provider Boundary

The API layer abstracts LLM access from agent behavior. Ollama is the intended local runtime and requires a separately running `ollama serve` process and a pulled model such as `llama3`. Groq support appears to provide an alternate remote provider path, likely requiring credentials.

Provider routing and clients:
- `src/api/aiRouter.js`
- `src/api/ollamaClient.js`
- `src/api/groqClient.js`

#### External Dependencies and Operational Setup

Material runtime dependencies are Node.js 18+, Electron 31, React 18, Vite 5, and Ollama. WhatsApp functionality depends on `whatsapp-web.js`; setup UX is represented in `src/renderer/components/WhatsAppSetup.jsx`. Ollama setup guidance is surfaced through `src/renderer/components/OllamaSetupGuide.jsx`.

Environment-sensitive configuration is indicated by:
- `.env.example`
- `package.json`

Main entry points: [`src/agent/ariaAgent.js`](https://github.com/itx-shivansh/aria/blob/main/src/agent/ariaAgent.js) (ARIA agent), [`src/agent/intentParser.js`](https://github.com/itx-shivansh/aria/blob/main/src/agent/intentParser.js) (Intent parser), [`src/renderer/app.jsx`](https://github.com/itx-shivansh/aria/blob/main/src/renderer/app.jsx) (React renderer root), [`src/api/aiRouter.js`](https://github.com/itx-shivansh/aria/blob/main/src/api/aiRouter.js) (AI router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Electron Desktop"]
  node_electron_main["Electron main<br/>desktop host<br/>[main.js]"]
  node_preload["Preload bridge<br/>IPC boundary<br/>[preload.js]"]
end

subgraph group_renderer["Local React UI"]
  node_react_root["React renderer root<br/>renderer bootstrap<br/>[app.jsx]"]
  node_chat_window["Chat window<br/>chat UI<br/>[ChatWindow.jsx]"]
  node_dashboard["Dashboard<br/>presentation UI<br/>[Dashboard.jsx]"]
  node_sidebar["Sidebar<br/>navigation UI<br/>[Sidebar.jsx]"]
end

subgraph group_agent["Agent Pipeline"]
  node_aria_agent{{"ARIA agent<br/>agent coordinator<br/>[ariaAgent.js]"}}
  node_intent_parser["Intent parser<br/>intent routing<br/>[intentParser.js]"]
  node_memory_store[("Memory store<br/>persistent context<br/>[memoryStore.js]")]
end

subgraph group_providers["AI Providers"]
  node_ai_router{{"AI router<br/>provider abstraction<br/>[aiRouter.js]"}}
  node_ollama_client["Ollama client<br/>local LLM client<br/>[ollamaClient.js]"]
  node_groq_client["Groq client<br/>remote LLM client<br/>[groqClient.js]"]
end

subgraph group_capabilities["Action Modules"]
  node_whatsapp["WhatsApp automation<br/>capability module<br/>[whatsappModule.js]"]
  node_code["Code actions<br/>capability module<br/>[codeModule.js]"]
  node_email["Email drafting<br/>capability module<br/>[emailModule.js]"]
  node_calendar["Calendar scheduling<br/>capability module<br/>[calendarModule.js]"]
  node_file_actions["File actions<br/>capability module<br/>[fileModule.js]"]
  node_system_actions["System actions<br/>capability module<br/>[systemModule.js]"]
end

node_electron_main -->|"loads"| node_preload
node_preload -->|"bridges IPC"| node_react_root
node_react_root -->|"renders"| node_chat_window
node_react_root -->|"renders"| node_dashboard
node_react_root -->|"renders"| node_sidebar
node_chat_window -->|"prompt / response"| node_aria_agent
node_aria_agent -->|"classifies intent"| node_intent_parser
node_aria_agent -->|"reads and persists context"| node_memory_store
node_aria_agent -->|"requests model response"| node_ai_router
node_ai_router -->|"default local provider"| node_ollama_client
node_ai_router -.->|"alternate remote provider"| node_groq_client
node_intent_parser -->|"routes WhatsApp intent"| node_whatsapp
node_intent_parser -->|"routes code intent"| node_code
node_intent_parser -->|"routes email intent"| node_email
node_intent_parser -->|"routes calendar intent"| node_calendar
node_intent_parser -->|"routes file intent"| node_file_actions
node_intent_parser -->|"routes system intent"| node_system_actions
node_whatsapp -.->|"action result"| node_aria_agent
node_code -.->|"action result"| node_aria_agent
node_file_actions -.->|"action result"| node_aria_agent
node_system_actions -.->|"action result"| node_aria_agent

click node_electron_main "https://github.com/itx-shivansh/aria/blob/main/src/main.js"
click node_preload "https://github.com/itx-shivansh/aria/blob/main/src/preload.js"
click node_react_root "https://github.com/itx-shivansh/aria/blob/main/src/renderer/app.jsx"
click node_chat_window "https://github.com/itx-shivansh/aria/blob/main/src/renderer/chat/ChatWindow.jsx"
click node_dashboard "https://github.com/itx-shivansh/aria/blob/main/src/renderer/dashboard/Dashboard.jsx"
click node_sidebar "https://github.com/itx-shivansh/aria/blob/main/src/renderer/components/Sidebar.jsx"
click node_aria_agent "https://github.com/itx-shivansh/aria/blob/main/src/agent/ariaAgent.js"
click node_intent_parser "https://github.com/itx-shivansh/aria/blob/main/src/agent/intentParser.js"
click node_memory_store "https://github.com/itx-shivansh/aria/blob/main/src/agent/memoryStore.js"
click node_ai_router "https://github.com/itx-shivansh/aria/blob/main/src/api/aiRouter.js"
click node_ollama_client "https://github.com/itx-shivansh/aria/blob/main/src/api/ollamaClient.js"
click node_groq_client "https://github.com/itx-shivansh/aria/blob/main/src/api/groqClient.js"
click node_whatsapp "https://github.com/itx-shivansh/aria/blob/main/src/agent/modules/whatsappModule.js"
click node_code "https://github.com/itx-shivansh/aria/blob/main/src/agent/modules/codeModule.js"
click node_email "https://github.com/itx-shivansh/aria/blob/main/src/agent/modules/emailModule.js"
click node_calendar "https://github.com/itx-shivansh/aria/blob/main/src/agent/modules/calendarModule.js"
click node_file_actions "https://github.com/itx-shivansh/aria/blob/main/src/agent/modules/fileModule.js"
click node_system_actions "https://github.com/itx-shivansh/aria/blob/main/src/agent/modules/systemModule.js"

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_main,node_preload toneBlue
class node_react_root,node_chat_window,node_dashboard,node_sidebar toneAmber
class node_aria_agent,node_intent_parser,node_memory_store toneMint
class node_ai_router,node_ollama_client,node_groq_client toneRose
class node_whatsapp,node_code,node_email,node_calendar,node_file_actions,node_system_actions toneIndigo
```

## Components

### Electron Desktop

- [Electron main](https://github.com/itx-shivansh/aria/blob/main/src/main.js): desktop host · Owns application and window lifecycle. · `src/main.js`
- [Preload bridge](https://github.com/itx-shivansh/aria/blob/main/src/preload.js): IPC boundary · Exposes approved privileged capabilities to the renderer. · `src/preload.js`

### Local React UI

- [React renderer root](https://github.com/itx-shivansh/aria/blob/main/src/renderer/app.jsx): renderer bootstrap · `src/renderer/app.jsx`
- [Chat window](https://github.com/itx-shivansh/aria/blob/main/src/renderer/chat/ChatWindow.jsx): chat UI · Collects prompts and presents responses. · `src/renderer/chat/ChatWindow.jsx`
- [Dashboard](https://github.com/itx-shivansh/aria/blob/main/src/renderer/dashboard/Dashboard.jsx): presentation UI · `src/renderer/dashboard/Dashboard.jsx`
- [Sidebar](https://github.com/itx-shivansh/aria/blob/main/src/renderer/components/Sidebar.jsx): navigation UI · `src/renderer/components/Sidebar.jsx`

### Agent Pipeline

- [ARIA agent](https://github.com/itx-shivansh/aria/blob/main/src/agent/ariaAgent.js): agent coordinator · Coordinates conversation, routing, memory, and action results. · `src/agent/ariaAgent.js`
- [Intent parser](https://github.com/itx-shivansh/aria/blob/main/src/agent/intentParser.js): intent routing · `src/agent/intentParser.js`
- [Memory store](https://github.com/itx-shivansh/aria/blob/main/src/agent/memoryStore.js): persistent context · `src/agent/memoryStore.js`

### AI Providers

- [AI router](https://github.com/itx-shivansh/aria/blob/main/src/api/aiRouter.js): provider abstraction · `src/api/aiRouter.js`
- [Ollama client](https://github.com/itx-shivansh/aria/blob/main/src/api/ollamaClient.js): local LLM client · Connects to a separately running Ollama runtime. · `src/api/ollamaClient.js`
- [Groq client](https://github.com/itx-shivansh/aria/blob/main/src/api/groqClient.js): remote LLM client · `src/api/groqClient.js`

### Action Modules

- [WhatsApp automation](https://github.com/itx-shivansh/aria/blob/main/src/agent/modules/whatsappModule.js): capability module · `src/agent/modules/whatsappModule.js`
- [Code actions](https://github.com/itx-shivansh/aria/blob/main/src/agent/modules/codeModule.js): capability module · Writes, debugs, and executes code. · `src/agent/modules/codeModule.js`
- [Email drafting](https://github.com/itx-shivansh/aria/blob/main/src/agent/modules/emailModule.js): capability module · `src/agent/modules/emailModule.js`
- [Calendar scheduling](https://github.com/itx-shivansh/aria/blob/main/src/agent/modules/calendarModule.js): capability module · `src/agent/modules/calendarModule.js`
- [File actions](https://github.com/itx-shivansh/aria/blob/main/src/agent/modules/fileModule.js): capability module · `src/agent/modules/fileModule.js`
- [System actions](https://github.com/itx-shivansh/aria/blob/main/src/agent/modules/systemModule.js): capability module · `src/agent/modules/systemModule.js`

## Connections

- Electron main → Preload bridge: loads
- Preload bridge → React renderer root: bridges IPC
- React renderer root → Chat window: renders
- React renderer root → Dashboard: renders
- React renderer root → Sidebar: renders
- Chat window → ARIA agent: prompt / response · Requests cross the desktop isolation boundary.
- ARIA agent → Intent parser: classifies intent
- ARIA agent → Memory store: reads and persists context
- ARIA agent → AI router: requests model response
- AI router → Ollama client: default local provider
- AI router → Groq client: alternate remote provider
- Intent parser → WhatsApp automation: routes WhatsApp intent
- Intent parser → Code actions: routes code intent
- Intent parser → Email drafting: routes email intent
- Intent parser → Calendar scheduling: routes calendar intent
- Intent parser → File actions: routes file intent
- Intent parser → System actions: routes system intent
- WhatsApp automation → ARIA agent: action result
- Code actions → ARIA agent: action result
- File actions → ARIA agent: action result
- System actions → ARIA agent: action result