How irisx-ai/iris-ai works
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: main/index.ts Main Entry · IRISRoot.tsx Root UI · preload/index.ts Bridge API · services Client Services
Components 18
Renderer
User-facing Electron UI and local presentation state.
- App Shell · Top-level renderer composition and app entry.
src/renderer/src/App.tsx - Root UI · Renderer root wiring for the Electron UI.
src/renderer/src/IRISRoot.tsx - Core Views · Dashboard, notes, gallery, phone, and settings screens.
src/renderer/src/views - UI Components · Shared panels, titlebar, and interactive widgets.
src/renderer/src/components - Client Services · 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 · Safe exposed API surface for renderer-to-main calls.
src/preload/index.ts - Bridge Types · Type definitions for the exposed preload contract.
src/preload/index.d.ts
Main Process
Privileged execution and desktop integration.
- Main Entry · Application bootstrap and privileged process wiring.
src/main/index.ts - System Core · Low-level system access and desktop integration helpers.
src/main/lib/system.ts - Automation Core · Privileged command execution, OS control, and routing to domain actions.
- State Core · Persistent memory, notes, and local context management.
- Workflow Orchestrator · Task sequencing, tool routing, and higher-level execution control.
- External Services · Cloud AI, search, and API integrations used by execution flows.
- Mobile Control · Android device control and mobile automation paths.
- Security Boundary · Locking, secure key handling, and trust-boundary enforcement.
Build & Packaging
Vite/Electron build and desktop distribution config.
- Build Config · Repository build and packaging configuration.
electron.vite.config.ts - Packaging · Desktop distribution and platform packaging setup.
electron-builder.yml
Testing Sandbox
Separate validation and plugin/runtime experiments.
- Testing Suite · Separate core, plugin, and end-to-end validation environment.
testing
Connections 21
- 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.