docs: add comprehensive Iris Apps architecture planning #1
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This introduces the complete architecture documentation for Iris Apps, a revolutionary system where apps are developed inside Iris, expose tools to AI agents, and can run standalone or be shared with others. Documents included: - Vision: Philosophy and goals for the system - Architecture: System components and their interactions - App Model: App structure, lifecycle, and configuration - SDK Design: APIs for server and React client - Security Model: Permissions, sandboxing, and audit logging - Resilience: Error handling and development experience - Protocol: Communication protocols between components - Implementation Roadmap: Phased approach with milestones Key innovations: - Self-hosted development (build apps inside Iris) - AI-native tools as first-class citizens - Graceful error handling during development - Three modes: development, installed, standalone - Robust permission and security model
- Make Server-Defined Rendering (SDR) the primary approach - Keep iframes as escape hatch for custom UI mode (3D, canvas, etc.) - Simplify single-file app model (app.json + server.ts) - Update security model with VS Code-like trust levels - Revise protocol for SDR component trees and actions - Update implementation roadmap for simpler SDR-based phases - Add React Native component registry for mobile support
Phase 1 implementation of the Iris Apps system: Backend (src/apps/): - types.ts: Core types, manifest schema, SDR message types - manager/: App discovery, loading, lifecycle management - runtime/: App execution, state management, hot reload SDK packages (packages/): - @iris/app-sdk: defineApp, defineTool, state primitives - @iris/ui: Component functions (Stack, Button, Input, etc.) Frontend (webui/src/components/apps/): - SDRRenderer: Renders component trees to React - AppHost: Manages WebSocket connection and error handling Demo app (examples/counter-app/): - Complete counter app showcasing SDR architecture - Tools exposed for AI agent integration - State management with history tracking This implements the foundation for the SDR-first architecture where apps are single-file TypeScript modules with state, tools, and ui(). TODOs remaining: - Wire up WebSocket handlers - Integrate with existing Iris routes - Add proper hot reload debouncing - Implement remaining specialized components
API Routes (src/server/routes/apps.ts): - GET /api/projects/:projectId/apps - List apps in project - GET /api/projects/:projectId/apps/:appId - Get app details - POST /api/projects/:projectId/apps/:appId/activate - Activate app - POST /api/projects/:projectId/apps/:appId/deactivate - Deactivate app - POST /api/projects/:projectId/apps/:appId/reload - Hot reload app - POST /api/projects/:projectId/apps/:appId/action - Execute action - GET /api/projects/:projectId/apps/:appId/ui - Get current UI tree WebSocket Protocol: - app.subscribe - Subscribe to app UI updates - app.unsubscribe - Unsubscribe from app updates - app.action - Execute an action (tool call) - app.activate - Activate an app - app.deactivate - Deactivate an app - app.reload - Trigger hot reload Events: app.ui.sync, app.ui.patch, app.state.update, app.error, etc. Hot Reload (src/apps/hot-reload.ts): - Debounced file watching (150ms default) - Configurable file extensions and ignore patterns - State preservation across reloads Wired into existing Hono app and WebSocket handler registry.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This introduces the complete architecture documentation for Iris Apps,
a revolutionary system where apps are developed inside Iris, expose
tools to AI agents, and can run standalone or be shared with others.
Documents included:
Key innovations: