# iblamelessly/ai-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/iblamelessly/ai-assistant
- Repository: https://github.com/iblamelessly/ai-assistant

## Overview

JARVIS is a personal desktop/CLI AI assistant. Users submit text or voice requests; the assistant routes conversation and invokes guarded automation or media/document tools, then streams results to the UI or terminal. The graph preserves README capabilities such as video, document generation, voice, and usage tracking. Several modules are indexed but not excerpted, so only documented or indexed relationships are shown; unsampled subsystem links are omitted where their callers are unclear.

Main entry points: [`core/tools.py`](https://github.com/iblamelessly/ai-assistant/blob/main/core/tools.py) (Tool registry), [`core/assistant.py`](https://github.com/iblamelessly/ai-assistant/blob/main/core/assistant.py) (Assistant dispatcher), [`ui/webview_app.py`](https://github.com/iblamelessly/ai-assistant/blob/main/ui/webview_app.py) (Desktop bridge), [`core/groq_client.py`](https://github.com/iblamelessly/ai-assistant/blob/main/core/groq_client.py) (Groq client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_launcher["Desktop launcher<br/>[app.py]"]
  node_cli["CLI entry<br/>[main.py]"]
  node_desktop["Desktop bridge<br/>[webview_app.py]"]
  node_webui["Webview interface<br/>[app.js]"]
end

subgraph group_assistant["Assistant Core"]
  node_engine["Assistant dispatcher<br/>[assistant.py]"]
  node_router["Model router<br/>[model_router.py]"]
  node_tools["Tool registry<br/>[tools.py]"]
end

subgraph group_automation["Automation &amp; Safety"]
  node_permissions["Approval guard<br/>[permissions.py]"]
  node_app_launch["App launching<br/>[app_launcher.py]"]
  node_file_search["File search<br/>[file_search.py]"]
end

subgraph group_creation["Media &amp; Documents"]
  node_media_edit["Image editing<br/>[media_editor.py]"]
  node_image_gen["Image generation<br/>[ai_image.py]"]
  node_video_gen["Video synthesis<br/>[ai_video.py]"]
  node_documents["Document generation"]
end

subgraph group_services["Models &amp; Persistence"]
  node_groq["Groq client<br/>[groq_client.py]"]
  node_gemini["Gemini client<br/>[gemini_client.py]"]
  node_memory[("Persistent memory<br/>[memory.py]")]
  node_history[("Chat sessions<br/>[history.py]")]
  node_config[("Configuration<br/>[config.py]")]
  node_voice["Speech synthesis<br/>[voice.py]"]
  node_mic["Voice input<br/>[mic.py]"]
end

node_user(("User"))
node_image_service{{"Pollinations service"}}
node_groq_service{{"Groq Cloud"}}
node_ollama{{"Local Ollama"}}

node_user -->|"submits request"| node_webui
node_webui -->|"calls bridge"| node_desktop
node_user -->|"enters request"| node_cli
node_cli -->|"streams chat"| node_engine
node_launcher -->|"starts desktop"| node_desktop
node_desktop -->|"dispatches chat"| node_engine
node_desktop -->|"uses memory"| node_memory
node_desktop -->|"manages sessions"| node_history
node_desktop -->|"loads settings"| node_config
node_desktop -->|"records speech"| node_mic
node_engine -->|"invokes tools"| node_tools
node_engine -->|"routes prompts"| node_router
node_engine -->|"requests inference"| node_groq
node_engine -->|"uses alternate model"| node_gemini
node_engine -->|"checks approvals"| node_permissions
node_engine -->|"synthesizes speech"| node_voice
node_tools -->|"launches applications"| node_app_launch
node_tools -->|"resolves files"| node_file_search
node_tools -->|"edits media"| node_media_edit
node_tools -->|"generates images"| node_image_gen
node_tools -->|"generates video"| node_video_gen
node_tools -->|"creates documents"| node_documents
node_tools -->|"tracks usage"| node_groq
node_gemini -->|"shares usage tracker"| node_groq
node_image_gen -->|"requests image"| node_image_service
node_video_gen -->|"uses scene imagery"| node_image_gen
node_groq -->|"streams inference"| node_groq_service
node_mic -->|"transcribes audio"| node_groq_service
node_launcher -->|"checks availability"| node_ollama

click node_launcher "https://github.com/iblamelessly/ai-assistant/blob/main/app.py"
click node_cli "https://github.com/iblamelessly/ai-assistant/blob/main/main.py"
click node_desktop "https://github.com/iblamelessly/ai-assistant/blob/main/ui/webview_app.py"
click node_webui "https://github.com/iblamelessly/ai-assistant/blob/main/ui/web/app.js"
click node_engine "https://github.com/iblamelessly/ai-assistant/blob/main/core/assistant.py"
click node_router "https://github.com/iblamelessly/ai-assistant/blob/main/core/model_router.py"
click node_tools "https://github.com/iblamelessly/ai-assistant/blob/main/core/tools.py"
click node_permissions "https://github.com/iblamelessly/ai-assistant/blob/main/core/permissions.py"
click node_app_launch "https://github.com/iblamelessly/ai-assistant/blob/main/core/app_launcher.py"
click node_file_search "https://github.com/iblamelessly/ai-assistant/blob/main/core/file_search.py"
click node_media_edit "https://github.com/iblamelessly/ai-assistant/blob/main/core/media_editor.py"
click node_image_gen "https://github.com/iblamelessly/ai-assistant/blob/main/core/ai_image.py"
click node_video_gen "https://github.com/iblamelessly/ai-assistant/blob/main/core/ai_video.py"
click node_documents "https://github.com/iblamelessly/ai-assistant/blob/main/core/document_generator.py"
click node_groq "https://github.com/iblamelessly/ai-assistant/blob/main/core/groq_client.py"
click node_gemini "https://github.com/iblamelessly/ai-assistant/blob/main/core/gemini_client.py"
click node_memory "https://github.com/iblamelessly/ai-assistant/blob/main/core/memory.py"
click node_history "https://github.com/iblamelessly/ai-assistant/blob/main/core/history.py"
click node_config "https://github.com/iblamelessly/ai-assistant/blob/main/core/config.py"
click node_voice "https://github.com/iblamelessly/ai-assistant/blob/main/core/voice.py"
click node_mic "https://github.com/iblamelessly/ai-assistant/blob/main/core/mic.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_launcher,node_cli,node_desktop,node_webui,node_user toneBlue
class node_engine,node_router,node_tools toneAmber
class node_permissions,node_app_launch,node_file_search toneMint
class node_media_edit,node_image_gen,node_video_gen,node_documents toneRose
class node_groq,node_gemini,node_memory,node_history,node_config,node_voice,node_mic,node_image_service,node_groq_service,node_ollama toneIndigo
```

## Components

### User Interfaces

- [Desktop launcher](https://github.com/iblamelessly/ai-assistant/blob/main/app.py): `app.py`
- [CLI entry](https://github.com/iblamelessly/ai-assistant/blob/main/main.py): `main.py`
- [Desktop bridge](https://github.com/iblamelessly/ai-assistant/blob/main/ui/webview_app.py): `ui/webview_app.py`
- [Webview interface](https://github.com/iblamelessly/ai-assistant/blob/main/ui/web/app.js): `ui/web/app.js`

### Assistant Core

- [Assistant dispatcher](https://github.com/iblamelessly/ai-assistant/blob/main/core/assistant.py): `core/assistant.py`
- [Model router](https://github.com/iblamelessly/ai-assistant/blob/main/core/model_router.py): `core/model_router.py`
- [Tool registry](https://github.com/iblamelessly/ai-assistant/blob/main/core/tools.py): `core/tools.py`

### Automation & Safety

- [Approval guard](https://github.com/iblamelessly/ai-assistant/blob/main/core/permissions.py): `core/permissions.py`
- [App launching](https://github.com/iblamelessly/ai-assistant/blob/main/core/app_launcher.py): `core/app_launcher.py`
- [File search](https://github.com/iblamelessly/ai-assistant/blob/main/core/file_search.py): `core/file_search.py`

### Media & Documents

- [Image editing](https://github.com/iblamelessly/ai-assistant/blob/main/core/media_editor.py): `core/media_editor.py`
- [Image generation](https://github.com/iblamelessly/ai-assistant/blob/main/core/ai_image.py): `core/ai_image.py`
- [Video synthesis](https://github.com/iblamelessly/ai-assistant/blob/main/core/ai_video.py): `core/ai_video.py`
- [Document generation](https://github.com/iblamelessly/ai-assistant/blob/main/core/document_generator.py): `core/document_generator.py`

### Models & Persistence

- [Groq client](https://github.com/iblamelessly/ai-assistant/blob/main/core/groq_client.py): `core/groq_client.py`
- [Gemini client](https://github.com/iblamelessly/ai-assistant/blob/main/core/gemini_client.py): `core/gemini_client.py`
- [Persistent memory](https://github.com/iblamelessly/ai-assistant/blob/main/core/memory.py): `core/memory.py`
- [Chat sessions](https://github.com/iblamelessly/ai-assistant/blob/main/core/history.py): `core/history.py`
- [Configuration](https://github.com/iblamelessly/ai-assistant/blob/main/core/config.py): `core/config.py`
- [Speech synthesis](https://github.com/iblamelessly/ai-assistant/blob/main/core/voice.py): `core/voice.py`
- [Voice input](https://github.com/iblamelessly/ai-assistant/blob/main/core/mic.py): `core/mic.py`

### Other components

- **User**
- **Pollinations service**
- **Groq Cloud**
- **Local Ollama**

## Connections

- User → Webview interface: submits request (evidence: `README.md`)
- Webview interface → Desktop bridge: calls bridge (evidence: `README.md`)
- User → CLI entry: enters request (evidence: `main.py`)
- CLI entry → Assistant dispatcher: streams chat (evidence: `main.py`)
- Desktop launcher → Desktop bridge: starts desktop (evidence: `app.py`)
- Desktop bridge → Assistant dispatcher: dispatches chat (evidence: `ui/webview_app.py`)
- Desktop bridge → Persistent memory: uses memory (evidence: `ui/webview_app.py`)
- Desktop bridge → Chat sessions: manages sessions (evidence: `ui/webview_app.py`)
- Desktop bridge → Configuration: loads settings (evidence: `ui/webview_app.py`)
- Desktop bridge → Voice input: records speech (evidence: `ui/webview_app.py`)
- Assistant dispatcher → Tool registry: invokes tools (evidence: `core/assistant.py`)
- Assistant dispatcher → Model router: routes prompts (evidence: `core/assistant.py`)
- Assistant dispatcher → Groq client: requests inference (evidence: `core/assistant.py`)
- Assistant dispatcher → Gemini client: uses alternate model (evidence: `core/assistant.py`)
- Assistant dispatcher → Approval guard: checks approvals (evidence: `README.md`)
- Assistant dispatcher → Speech synthesis: synthesizes speech (evidence: `core/assistant.py`)
- Tool registry → App launching: launches applications (evidence: `core/tools.py`)
- Tool registry → File search: resolves files (evidence: `core/tools.py`)
- Tool registry → Image editing: edits media (evidence: `core/tools.py`)
- Tool registry → Image generation: generates images (evidence: `core/tools.py`)
- Tool registry → Video synthesis: generates video (evidence: `core/tools.py`)
- Tool registry → Document generation: creates documents (evidence: `core/tools.py`)
- Tool registry → Groq client: tracks usage (evidence: `core/tools.py`)
- Gemini client → Groq client: shares usage tracker (evidence: `core/gemini_client.py`)
- Image generation → Pollinations service: requests image (evidence: `core/ai_image.py`)
- Video synthesis → Image generation: uses scene imagery (evidence: `core/ai_video.py`)
- Groq client → Groq Cloud: streams inference (evidence: `core/groq_client.py`)
- Voice input → Groq Cloud: transcribes audio (evidence: `README.md`)
- Desktop launcher → Local Ollama: checks availability (evidence: `app.py`)
