-
Notifications
You must be signed in to change notification settings - Fork 49
Architecture Overview
ORGII is a Tauri v2 desktop application — a thin native shell wrapping a React frontend, with a multi-crate Rust backend handling all agent process management, file I/O, and native integrations.
┌─────────────────────────────────────────────────────────────┐
│ ORGII Desktop App │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ React Frontend (TypeScript) │ │
│ │ │ │
│ │ scaffold/ modules/ features/ engines/ │ │
│ │ Jotai atoms · react-router · CodeMirror · xterm │ │
│ └────────────────────────┬─────────────────────────────┘ │
│ │ Tauri IPC (invoke / events) │
│ ┌────────────────────────▼─────────────────────────────┐ │
│ │ Rust Backend (Tauri v2) │ │
│ │ │ │
│ │ agent_sessions/ agent_core/ key_vault │ │
│ │ crates/… commands/ infrastructure/ │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ Native OS: file system · processes · macOS APIs │
└─────────────────────────────────────────────────────────────┘
The frontend is organized into several distinct layers, each with a clear ownership boundary.
Full application pages mounted by the router. The two primary modules are:
-
MainApp/— the left-side panel: agent config, integrations, key vault, settings, inbox, project ops. -
WorkStation/— the main workspace: code editor, terminal, diff viewer, chat, browser, database manager, canvas.
Self-contained feature components shared across modules:
| Feature | Purpose |
|---|---|
SessionCreator |
Multi-variant session launcher (ChatPanel, Kanban) |
CodeViewer |
Read-only and diff code viewers |
ChatPanel (engine) |
Full chat UI — history, input, threading |
SessionCore (engine) |
Session sync, ingestion, turns, rendering |
TerminalCore (engine) |
xterm.js terminal with addons |
GitWorkflow (engine) |
Git operations, diff viewing |
BrowserCore (engine) |
Embedded webview / browser use |
Persistent chrome that wraps every page:
-
NavigationSidebar— left navigation -
GlobalSpotlight— command palette / session switcher -
ModalSystem— global modal registry -
WizardSystem— multi-step setup wizards (Key Vault, Agent, MCP, Skill, …)
Three transport mechanisms, each with typed wrappers:
| Transport | Location | Used for |
|---|---|---|
| Tauri IPC | src/api/tauri/ |
All native operations — agent commands, session queries, repo, diff, GitHub |
| HTTP REST | src/api/http/ |
Auth, git REST, user profile |
| Realtime | src/api/realtime/ |
WebSocket (agent streaming), SSE (task execution), CodeEditor WS (LSP) |
Tauri IPC uses a Zod-validated RPC layer (src/api/tauri/rpc/) as the standard for all new commands. Request and response shapes are validated at the boundary.
Jotai atoms organized by domain. Atoms used by two or more modules live in src/store/. Module-local atoms live colocated in src/modules/{Module}/store/.
Key domains: session/, ui/, workstation/, git/, project/, settings/, tabs/, user/
React hooks used by two or more distinct modules. Module-specific hooks live colocated.
The core of the backend. Each CLI agent type has its own:
- Platform adapter — spawns the agent process, manages its stdin/stdout/stderr.
- Output parser — converts raw agent output into structured events (tool calls, messages, file edits).
Supported CLI agents: Cursor, Claude Code, Codex, Copilot, Gemini CLI, Kiro, OpenCode.
The Rust-native agent runtime. Powers the SDE Agent and OS Agent:
- Session types, prompt sections, exec modes
- Tool implementations (file ops, git, shell, browser, computer use)
- Event store and streaming
- Built-in prompts compiled via
include_str!
Encrypted local storage for API keys and provider accounts. Keys never leave the device.
Persistent event log for agent sessions. Enables session replay, resume, and the self-evolution test harness.
Native integrations for git operations, semantic/full-text code search, and database connectivity (SQLite via libSQL, plus adapters for Postgres, MySQL).
User types message → SessionCreator / ChatPanel
→ Jotai session atom updated
→ Tauri IPC invoke("agent_send_message", { sessionId, content, mode })
→ Rust agent_sessions handler
→ CLI process stdin / agent-core tool executor
→ Events streamed back via Tauri event system
→ Frontend event listeners update session atoms
→ React re-renders chat + WorkStation panels
| Decision | Rationale |
|---|---|
| Tauri over Electron | ~10× lower memory footprint; Rust safety; no Node.js in the native layer |
| Jotai over Redux | Fine-grained atomic subscriptions avoid over-rendering large session lists |
| Zod RPC boundary | Catches schema drift between TS and Rust at runtime; errors surface early in dev |
| Per-agent parsers | Isolates each CLI agent's quirks; new agents added without touching shared code |
| AGPL-3.0 | Ensures hosted derivatives remain open; an OSS core is planned in packages/orgii_core
|
- Frontend Architecture — component conventions, state patterns, i18n, logging
- Rust Backend — crate map, IPC conventions, resource lifecycle
- Sessions — session types, dispatch categories, exec modes