# Iris — Systems Deep Dive

> The `apps/iris/` area: the Iris AI-assistant product surface — one Hono API
> service plus the client and developer-facing apps and shared libraries
> (desktop, mobile, web widget, dashboard, marketplace, developer portal, and
> the XR/wearable shared kits) that make up the assistant across platforms.

## What this area is

Iris is "an intelligent AI assistant platform providing conversational AI
capabilities with advanced memory, context management, and multi-provider model
support" (`apps/iris/README.md`). The `apps/iris/` tree is not a single app but
a fan of related projects: one back-end service (`@iris/api`) and a set of
front-end clients and embeddable/SDK surfaces that all talk to that service or
reuse the same `@iris/*` libraries. Nine of these directories carry a
`project.json` and are therefore tracked Nx projects; this page documents
exactly those nine.

The center of gravity is `@iris/api`, a Hono server exposing REST, GraphQL, and
a memory-deletion event consumer on port `3100`, backed by a MemGPT-inspired
tiered memory service (`apps/iris/api/src/services/memory.service.ts`). Around
it sit the user-facing clients: `iris/desktop` (a Tauri app with a Rust core),
`@iris/mobile` (React Native with full native Android/iOS shells), and
`@iris/widget` (a Preact chat widget any website can embed). Two of the projects
are "insight/operations" surfaces rather than chat clients: `@iris/dashboard`
(personal productivity insights) and `@iris/marketplace` (a plugin marketplace).
`@iris/developer-portal` is the largest by far — a domain-services library
behind the developer/enterprise portal. Finally, `@iris/wearable-shared` and
`@iris/xr-shared` are shared libraries that the platform-specific wearable
(watchOS/wearOS) and XR (Quest/visionOS/Android-XR) clients build on.

A subtlety worth stating plainly: the `apps/iris/` directory contains more
client folders than there are Nx projects. `wearable/watchos`,
`wearable/wearos`, `xr/quest`, `xr/visionos`, `xr/android-xr`, `web/pwa`, and
`web/extension` exist as source folders (some with their own READMEs) but have
**no `project.json`**, so they are not separate entities here. The XR and
wearable kits documented below are the _shared_ halves those native clients
depend on; the native clients themselves are out of scope for this catalog
because they are not tracked Nx projects.

## How it fits the wider system

The clients depend on the service. `@iris/api`'s `project.json` declares
`implicitDependencies` on `@iris/core`, `@iris/config`, `@iris/contracts`, and
`@iris/types` — the same `@iris/*` libraries listed under "Related Libraries" in
`apps/iris/README.md` — and its `index.ts` wires logging/tracing from
`@iris/core`. The mobile client's `ApiService` and the widget's `lib/api` call
the API's `/auth` and `/api/v1/*` routes (the auth routes comment in
`apps/iris/api/src/index.ts` names `apps/iris/mobile/src/services/ApiService.ts`
explicitly). The developer-portal services compose other Oshun libraries — for
example `api-key-dashboard-service.ts` builds on `@iris/privacy-access`'s
`ApiKeyManager`. Cross-cutting boundary types come from `@iris/contracts`
(documented separately in `systems/lib-contracts.md`). Within the area, the two
"shared" libraries (`@iris/wearable-shared`, `@iris/xr-shared`) are the
consumed-by side: the per-platform native clients are their downstream
consumers. Walk the "used by" edges on any node below to see who depends on it.

## Entity reference

### @iris/api

The Iris assistant's back-end service (`apps/iris/api/src`), built with
`@nx/js:tsc` and run with `tsx watch`. `src/index.ts` assembles a Hono app with
request-ID, tracing, secure-headers, CORS, logging, and timing middleware, then
mounts route groups for `/health`, `/auth`, and the `/api/v1/*` surfaces
(`conversations`, `memory`, `agents`, `knowledge`), a `/graphql` endpoint, and
`/docs`. It starts on port `3100`, initialises logging/tracing from
`@iris/core`, and on shutdown closes a `memory-deletion-consumer` — an
event-driven, fail-closed account-deletion fan-out that erases iris memory and
replies with a signed receipt only when `OSHUN_REDIS_URL` and an attestation key
are configured. The memory layer (`src/services/memory.service.ts`) is a real
MemGPT-inspired tiered model (core/working/archival/episodic) with typed
importance levels, and auth ships both JSON and Postgres stores
(`src/services/auth-store-json.ts`, `auth-store-postgres.ts`). This is a
substantially implemented service, not a scaffold.

### @iris/dashboard

A personal-insights library (`apps/iris/dashboard/src`), bundled with `tsup` and
consumed by other workspaces rather than run standalone. `src/index.ts`
re-exports types, services, hooks, and components for tracking productivity,
time savings, task history, and learning progress. The services carry real
domain logic: for example `services/time-savings-calculator.ts` is an
`eventemitter3`-based `TimeSavingsCalculator` with per-category benchmark
constants (e.g. `code_generation` averaging 1800s manual time with a
std-deviation and confidence), and the directory also holds
`task-history-service.ts`, `learning-progress-service.ts`,
`productivity-analyzer.ts`, and a `dashboard-data-service.ts` that composes
them. The hook layer (`hooks/use-dashboard.ts`) exposes a `createUseDashboard`
subscribe/load API.

### iris/desktop

The desktop client (`apps/iris/desktop`), a Tauri app — note its `project.json`
`name` is the unscoped `iris/desktop`, tagged `framework:tauri`. The frontend is
a Vite/React/TSX app under `src/` (`App.tsx`, `ChatView`, `Sidebar`,
`PreferencesModal`, platform hooks `useMacOS`/`useWindows`/`useLinux`), and the
native core is a real Rust crate under `src-tauri/src` (`lib.rs`, `commands.rs`,
`tray.rs`, `hotkeys.rs`, `screenshot.rs`, `widgets.rs`, `state.rs`). `lib.rs`
registers an `invoke_handler` with core commands (`greet`, `toggle_window`,
`send_message`, `capture_screenshot`, `get_conversation_history`,
`update_preferences`, …) plus `#[cfg(target_os = ...)]`-gated platform commands
(macOS AppleScript/Spotlight/Siri, Windows search/PowerToys/startup, Linux). It
also carries Playwright e2e including a WCAG-AA sign-off spec under `e2e/`.

### @iris/developer-portal

The developer/enterprise portal's domain-services library
(`apps/iris/developer-portal/src`), `tsup`-bundled. Its `index.ts` is a thin
two-line barrel over `types/` and `services/`, but `services/` is the bulk of
the project: ~55 service modules with a matching `.test.ts` per feature.
Examples span portal/billing (`api-key-dashboard-service.ts`, which wraps
`@iris/privacy-access`'s `ApiKeyManager`/`InMemoryApiKeyStore`;
`usage-billing-service.ts`, `webhook-management-service.ts`), enterprise
(SSO/audit/SLA/reporting), accessibility (screen-reader, braille, dyslexia
fonts, high-contrast), BCI (intent-detection, consent, privacy framework — the
intent-detection service alone is ~1000 LOC), and agent reasoning
(`agent-goal-reasoning-service.ts` ~1200 LOC, delegation chains, reward
modeling). The services are genuinely implemented (EventEmitter-based stateful
classes with factory functions), not placeholders.

### @iris/marketplace

The Iris plugin marketplace as a `tsup`-bundled library
(`apps/iris/marketplace/src`). `index.ts` documents and re-exports a
`MarketplaceAPI` facade (`createMarketplaceAPI`) plus five services under
`services/`: `PluginDiscoveryService`, `InstallationService`, `ReviewService`,
`RevenueService`, and `CurationService`, each with global-singleton helpers. The
revenue logic is real: `services/revenue-service.ts` is an `eventemitter3`
service with a configurable `platformFee` (default 30%), per-plugin
pricing-model resolution, payout thresholds/scheduling, and analytics that
bucket transactions by pricing model. The `components/` export is
prop-type/`ComponentSchemas` definitions (the UI contracts) rather than rendered
components, and `types/` holds the listing/review/installation/revenue domain
types.

### @iris/mobile

The Iris mobile client (`apps/iris/mobile`), a React Native app driven through
the `react-native` CLI (its `project.json` targets are `start`/`run-android`/
`run-ios`/`build-android`/`build-ios`, not an Nx bundler). The TS app under
`src/` is fully fleshed out: navigation (`AppNavigator`), a stack of screens
(chat, history, search, settings, auth sign-in/up/welcome), a Zustand-style
store (`store/appStore.ts`, `chatStore.ts`), services (`ApiService`,
`OfflineSyncService` with tests, `PushNotificationService`, `StorageService`,
`BackgroundService`), a native-module bridge (`native/IrisNativeModule.ts`), and
a theme provider. It also carries real native shells: an Android project with
Kotlin sources (home-screen widgets `QuickActionWidget`/`StatsWidget`/
`RecentConversationsWidget`, a `BackgroundSyncService`, Firebase messaging,
notification receivers, a native module/package) and the iOS scaffolding
(`IOS_XCODEPROJ.md` notes its setup). A WCAG a11y sign-off script is wired into
`pnpm test:a11y-signoff`.

### @iris/wearable-shared

A shared TypeScript library (`apps/iris/wearable/shared/src`) for the wearable
clients, `tsup`-built to ESM/CJS+dts; tagged `layer:domain`, `type:lib`. Its
`index.ts` re-exports `types`, `voice`, `haptics`, `health`, `sync`,
`complications`, and `notifications`. The content is a mix of platform-agnostic
interfaces meant to be implemented per-OS (e.g. `health.ts` defines an
`IHealthManager` interface and `HealthQueryOptions` for HealthKit/Health-Connect
backends) and concrete cross-platform logic (e.g. `complications.ts` ships real
watch-complication templates, `generateTimeline`, and a
`ComplicationRefreshManager` class). It is the shared half consumed by the
`wearable/watchos` and `wearable/wearos` client folders, which are not
themselves tracked Nx projects.

### @iris/widget

The embeddable chat widget (`apps/iris/web/widget/src`), a Preact app bundled
with Vite (build also emits `dist/types` via `tsc --emitDeclarationOnly`);
tagged `layer:ui`, `type:lib`. `src/widget.ts` defines the `IrisWidget` class
and a rich `IrisWidgetConfig` (API key/endpoint, position, light/dark/auto theme
and custom-theme overrides, branding, z-index/size, behavior flags, and feature
toggles for file upload, voice input, typing indicators, history, etc.). Its
`lib/` carries the supporting pieces: `api.ts` (an `APIClient` with `Message`/
`ConversationContext` types), `config.ts` (theme/branding computation and
CSS-variable generation), `state.ts` (a `StateManager`), and `security.ts`. A
`demo.html` exercises it standalone. This is the "drop Iris onto any website"
surface.

### @iris/xr-shared

A shared TypeScript library (`apps/iris/xr/shared/src`) for the XR clients,
`tsup`-built to ESM/CJS+dts; tagged `platform:xr`. `index.ts` re-exports
`types`, `spatial-ui`, `gesture-recognition`, `voice-spatial`,
`session-manager`, `anchor-manager`, and `assistant-presence` — each a
substantial module (600–980 LOC). The implementation is real, not
interface-only: `session-manager.ts` models cross-platform
`PlatformCapabilities` and XR session lifecycle; `gesture-recognition.ts`
provides a `GestureRecognizer` and `CustomGestureRecognizer` with a
`DEFAULT_GESTURE_CONFIG` and predefined `ASSISTANT_GESTURES`. Like its wearable
sibling, it is the shared foundation for the per-platform XR client folders
(`xr/quest`, `xr/visionos`, `xr/android-xr`), which are not tracked Nx projects
of their own.