# irisx-ai/iris-ai architecture

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

- Interactive diagram: https://gitdiagram.com/irisx-ai/iris-ai
- Repository: https://github.com/irisx-ai/iris-ai

## Overview

1. **Project type and runtime shape**
   - IRIS is an Electron desktop application built with TypeScript, React 19, and Vite (`electron.vite.config.ts`, `src/main`, `src/preload`, `src/renderer`).
   - The app is split into the standard Electron three-process model: **main process** for system access, **preload** for the safe bridge, and **renderer** for the UI.

2. **Top-level architecture**
   - The repository is organized around a desktop shell plus a large command-execution backend.
   - The public codebase clearly includes the UI and integration surfaces, while the main orchestration logic lives under `src/main`, with many domain-specific modules for automation, memory, web, mobile, and security.

3. **Renderer subsystem: user-facing shell**
   - `src/renderer/src` contains the visible app: dashboard, notes, gallery, phone, settings, workflow editor, overlays, widgets, and auth screens.
   - This side is responsible for presentation, local UI state, and initiating actions through typed API wrappers in `src/renderer/src/functions`, `src/renderer/src/tools`, and `src/renderer/src/services`.

4. **Preload and IPC boundary**
   - `src/preload/index.ts` and `src/preload/index.d.ts` define the restricted bridge from renderer to main.
   - The app’s core data/action flow is: renderer requests an operation → preload exposes a safe API surface → main process executes the privileged work and returns results over IPC.

5. **Main process as execution hub**
   - `src/main/index.ts` is the entry point for privileged desktop behavior.
   - The main process is divided into narrow domains: `logic`, `manager`, `handlers`, `services`, `workflow`, `mobile`, `security`, `web`, and `utils`, which together act as the app’s execution kernel.

6. **System automation and OS control**
   - Desktop and OS-level actions are handled in `src/main/logic` and `src/main/manager`, including app launching, terminal control, file read/write/search, window control, ghost/phantom typing, live location, gallery handling, and notes/memory management.
   - These are the subsystems that connect UI intent to actual machine actions, so they are a key boundary in any architecture diagram.

7. **Agent/workflow layer**
   - `src/main/workflow/workflow-manager.ts` and `src/main/services` suggest an orchestration layer that sequences tool use and higher-level tasks.
   - The README describes this as agentic execution; in the repo structure, that maps to workflow coordination, tool routing, and task execution rather than a single monolithic controller.

8. **AI and external service integration**
   - The app integrates with cloud AI and search providers such as Gemini, Groq, Tavily, Google APIs, and likely Hugging Face through modules in `src/main/services`, `src/main/web`, and renderer tool APIs.
   - These integrations are part of the command interpretation/research pipeline and are not just UI features; they feed intent recognition, search, code generation, and multimodal tasks.

9. **Feature-specific subsystems**
   - The codebase has dedicated areas for distinct capability clusters: `apps` for Spotify/WhatsApp control, `mobile` for ADB-driven Android control, `gen` for image generation, `auto` for website/widget automation, and `security` for lock/vault behavior.
   - This separation implies a plugin-like domain model where each capability owns its own manager/handler rather than sharing one generic executor.

10. **Memory, notes, and local state**
   - Persistent state lives in `src/main/manager/permanent-memory.ts`, `notes-manager.ts`, `iris-memory.ts`, and related files.
   - The architecture likely separates transient command execution from durable user context, with the renderer consuming these services through specialized APIs and views.

11. **Security and trust boundaries**
   - Electron context isolation, IPC-based access, and preload-mediated calls are the primary technical safety boundary.
   - The repo and README also emphasize code protection, integrity checks, and secure key handling; from an architecture perspective, that means privileged logic is intentionally isolated from the renderer and packaged differently from the UI.

12. **Build, packaging, and deployment**
   - The app is packaged with Electron Builder (`electron-builder.yml`) and driven by Vite-based build configuration.
   - The presence of `build/` assets, icons, entitlements, and platform-specific packaging scripts indicates a desktop-distribution pipeline rather than a server deployment model.

13. **Testing and validation**
   - `testing/` is a separate sandbox with unit, e2e, plugin, and architecture artifacts, plus Docker/Jenkins/webpack support.
   - This suggests the repo includes a parallel validation environment for core engine behavior, auth plugins, and platform-specific checks, distinct from the shipped desktop app.

14. **How to draw the diagram**
   - The clearest architecture diagram is: **Renderer UI and widgets** on one side, **Preload IPC bridge** in the middle, and **Main-process execution/orchestration** on the other side, with arrows from main to external services and OS integrations.
   - Add separate boxes for **file/system automation**, **workflow/agent orchestration**, **memory/notes**, **mobile control**, and **security**, all feeding into or out of the main process.

Main entry points: [`src/main/index.ts`](https://github.com/irisx-ai/iris-ai/blob/main/src/main/index.ts) (Main Entry), [`src/renderer/src/IRISRoot.tsx`](https://github.com/irisx-ai/iris-ai/blob/main/src/renderer/src/IRISRoot.tsx) (Root UI), [`src/preload/index.ts`](https://github.com/irisx-ai/iris-ai/blob/main/src/preload/index.ts) (Bridge API), [`src/renderer/src/services`](https://github.com/irisx-ai/iris-ai/tree/main/src/renderer/src/services) (Client Services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_renderer["Renderer"]
  node_renderer_app["App Shell<br/>react shell<br/>[App.tsx]"]
  node_renderer_root["Root UI<br/>react root<br/>[IRISRoot.tsx]"]
  node_renderer_views["Core Views<br/>ui views"]
  node_renderer_components["UI Components"]
  node_renderer_services["Client Services<br/>renderer api"]
end

subgraph group_bridge["IPC Bridge"]
  node_preload_api["Bridge API<br/>ipc bridge<br/>[index.ts]"]
  node_preload_types["Bridge Types<br/>[index.d.ts]"]
end

subgraph group_main["Main Process"]
  node_main_entry["Main Entry<br/>electron main<br/>[index.ts]"]
  node_main_system["System Core<br/>os integration<br/>[system.ts]"]
  node_main_logic["Automation Core<br/>execution logic"]
  node_main_state[("State Core<br/>memory/notes")]
  node_main_workflow["Workflow Orchestrator<br/>agent workflows"]
  node_main_integrations["External Services<br/>ai/search"]
  node_main_mobile["Mobile Control<br/>adb/mobile"]
  node_main_security["Security Boundary<br/>vault/security"]
end

subgraph group_build["Build & Packaging"]
  node_build_config["Build Config<br/>vite/electron"]
  node_build_packaging["Packaging<br/>electron-builder"]
end

subgraph group_testing["Testing Sandbox"]
  node_testing_suite["Testing Suite<br/>validation sandbox"]
end

node_renderer_app -->|"wraps"| node_renderer_root
node_renderer_root -->|"renders"| node_renderer_views
node_renderer_root -->|"uses"| node_renderer_components
node_renderer_views -->|"requests"| node_renderer_services
node_renderer_components -->|"binds"| node_renderer_services
node_renderer_services -->|"calls"| node_preload_api
node_preload_api -->|"contracts"| node_preload_types
node_preload_api -->|"forwards"| node_main_entry
node_main_entry -->|"initializes"| node_main_system
node_main_entry -->|"routes"| node_main_logic
node_main_entry -->|"coordinates"| node_main_state
node_main_entry -->|"orchestrates"| node_main_workflow
node_main_entry -->|"integrates"| node_main_integrations
node_main_entry -->|"controls"| node_main_mobile
node_main_entry -->|"secures"| node_main_security
node_main_workflow -->|"uses"| node_main_integrations
node_main_workflow -->|"dispatches"| node_main_logic
node_main_state -->|"supports"| node_main_logic
node_main_security -->|"protects"| node_main_state
node_build_config -->|"feeds"| node_build_packaging
node_testing_suite -.->|"validates"| node_main_workflow

click node_renderer_app "https://github.com/irisx-ai/iris-ai/blob/main/src/renderer/src/App.tsx"
click node_renderer_root "https://github.com/irisx-ai/iris-ai/blob/main/src/renderer/src/IRISRoot.tsx"
click node_renderer_views "https://github.com/irisx-ai/iris-ai/tree/main/src/renderer/src/views"
click node_renderer_components "https://github.com/irisx-ai/iris-ai/tree/main/src/renderer/src/components"
click node_renderer_services "https://github.com/irisx-ai/iris-ai/tree/main/src/renderer/src/services"
click node_preload_api "https://github.com/irisx-ai/iris-ai/blob/main/src/preload/index.ts"
click node_preload_types "https://github.com/irisx-ai/iris-ai/blob/main/src/preload/index.d.ts"
click node_main_entry "https://github.com/irisx-ai/iris-ai/blob/main/src/main/index.ts"
click node_main_system "https://github.com/irisx-ai/iris-ai/blob/main/src/main/lib/system.ts"
click node_build_config "https://github.com/irisx-ai/iris-ai/blob/main/electron.vite.config.ts"
click node_build_packaging "https://github.com/irisx-ai/iris-ai/blob/main/electron-builder.yml"
click node_testing_suite "https://github.com/irisx-ai/iris-ai/tree/main/testing"

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_renderer_app,node_renderer_root,node_renderer_views,node_renderer_components,node_renderer_services toneBlue
class node_preload_api,node_preload_types toneAmber
class node_main_entry,node_main_system,node_main_logic,node_main_state,node_main_workflow,node_main_integrations,node_main_mobile,node_main_security toneMint
class node_build_config,node_build_packaging toneRose
class node_testing_suite toneIndigo
```

## Components

### Renderer

User-facing Electron UI and local presentation state.

- [App Shell](https://github.com/irisx-ai/iris-ai/blob/main/src/renderer/src/App.tsx): react shell · Top-level renderer composition and app entry. · `src/renderer/src/App.tsx`
- [Root UI](https://github.com/irisx-ai/iris-ai/blob/main/src/renderer/src/IRISRoot.tsx): react root · Renderer root wiring for the Electron UI. · `src/renderer/src/IRISRoot.tsx`
- [Core Views](https://github.com/irisx-ai/iris-ai/tree/main/src/renderer/src/views): ui views · Dashboard, notes, gallery, phone, and settings screens. · `src/renderer/src/views`
- [UI Components](https://github.com/irisx-ai/iris-ai/tree/main/src/renderer/src/components): ui components · Shared panels, titlebar, and interactive widgets. · `src/renderer/src/components`
- [Client Services](https://github.com/irisx-ai/iris-ai/tree/main/src/renderer/src/services): renderer api · Typed client-side wrappers for system info and action entry points. · `src/renderer/src/services`

### IPC Bridge

Restricted preload layer between renderer and privileged main process.

- [Bridge API](https://github.com/irisx-ai/iris-ai/blob/main/src/preload/index.ts): ipc bridge · Safe exposed API surface for renderer-to-main calls. · `src/preload/index.ts`
- [Bridge Types](https://github.com/irisx-ai/iris-ai/blob/main/src/preload/index.d.ts): bridge types · Type definitions for the exposed preload contract. · `src/preload/index.d.ts`

### Main Process

Privileged execution and desktop integration.

- [Main Entry](https://github.com/irisx-ai/iris-ai/blob/main/src/main/index.ts): electron main · Application bootstrap and privileged process wiring. · `src/main/index.ts`
- [System Core](https://github.com/irisx-ai/iris-ai/blob/main/src/main/lib/system.ts): os integration · Low-level system access and desktop integration helpers. · `src/main/lib/system.ts`
- **Automation Core**: execution logic · Privileged command execution, OS control, and routing to domain actions.
- **State Core**: memory/notes · Persistent memory, notes, and local context management.
- **Workflow Orchestrator**: agent workflows · Task sequencing, tool routing, and higher-level execution control.
- **External Services**: ai/search · Cloud AI, search, and API integrations used by execution flows.
- **Mobile Control**: adb/mobile · Android device control and mobile automation paths.
- **Security Boundary**: vault/security · Locking, secure key handling, and trust-boundary enforcement.

### Build & Packaging

Vite/Electron build and desktop distribution config.

- [Build Config](https://github.com/irisx-ai/iris-ai/blob/main/electron.vite.config.ts): vite/electron · Repository build and packaging configuration. · `electron.vite.config.ts`
- [Packaging](https://github.com/irisx-ai/iris-ai/blob/main/electron-builder.yml): electron-builder · Desktop distribution and platform packaging setup. · `electron-builder.yml`

### Testing Sandbox

Separate validation and plugin/runtime experiments.

- [Testing Suite](https://github.com/irisx-ai/iris-ai/tree/main/testing): validation sandbox · Separate core, plugin, and end-to-end validation environment. · `testing`

## Connections

- App Shell → Root UI: wraps · The app shell composes the root UI container.
- Root UI → Core Views: renders · Root composition selects and displays the main screens.
- Root UI → UI Components: uses · Root UI is assembled from shared interface components.
- Core Views → Client Services: requests · Views initiate typed actions through client wrappers.
- UI Components → Client Services: binds · Interactive widgets trigger app operations through services.
- Client Services → Bridge API: calls · Renderer-side service calls cross the IPC boundary.
- Bridge API → Bridge Types: contracts · The bridge implementation follows the typed contract.
- Bridge API → Main Entry: forwards · Safe renderer requests are forwarded to the privileged process.
- Main Entry → System Core: initializes · Main bootstrap configures desktop and system access.
- Main Entry → Automation Core: routes · Incoming IPC and app events are dispatched to execution logic.
- Main Entry → State Core: coordinates · The main process manages persistent memory and notes.
- Main Entry → Workflow Orchestrator: orchestrates · Main entry delegates agentic task execution.
- Main Entry → External Services: integrates · Main process connects external AI and API providers.
- Main Entry → Mobile Control: controls · Mobile device operations are handled in a dedicated domain.
- Main Entry → Security Boundary: secures · Security-sensitive operations remain in privileged code.
- Workflow Orchestrator → External Services: uses · Workflow orchestration consumes AI and search services.
- Workflow Orchestrator → Automation Core: dispatches · Workflows invoke concrete OS and tool actions.
- State Core → Automation Core: supports · Persistent context and notes back execution decisions.
- Security Boundary → State Core: protects · Vault and lock behavior guard persisted user state.
- Build Config → Packaging: feeds · Vite build output is packaged for desktop distribution.
- Testing Suite → Workflow Orchestrator: validates · Sandbox covers engine, plugin, and orchestration behavior.