Iris - Universal Intelligent Assistant Platform
Iris is the AI conversation backbone of the Oshun ecosystem — a platform that lets any product in the monorepo add intelligent, context-aware, multi-turn AI assistance without re-implementing model access, memory, or agent orchestration from scratch. It abstracts six AI providers (Anthropic, OpenAI, Google, Cohere, Mistral, and local Ollama), runs a four-tier memory system that persists user context across sessions, and hosts autonomous agents that can browse the web, execute code, and hand work off to one another.
From an engineering perspective, Iris is simultaneously a runtime service and a
library ecosystem. The library side (libs/iris/**, 258 packages across 45
cluster directories) provides typed contracts, conversation-engine primitives,
memory tiers, agent scaffolding, and provider adapters. The service side
(apps/iris/api) exposes those capabilities over REST, GraphQL, SSE, and
WebSocket. Other Oshun domains — Psyche, Sophia, Maya, Yemaya, Hathor, and Nyx —
depend on Iris for their own AI features rather than owning separate AI stacks.
This document describes the technical architecture: system components, service
topology, data flows, library organization, design patterns, and integration
architecture. Sections that describe planned but not-yet-built infrastructure
are explicitly labelled as such; for the verified in-code state, see
DOMAINS/iris/specifications.md.
1. Design Principles#
The following principles drive every architectural decision in Iris. They are listed in priority order: privacy and multi-model flexibility come first because they are the hardest constraints to add retroactively.
- Privacy-First — On-device processing where possible; end-to-end encryption by default
- Multi-Model — Intelligent routing across multiple AI providers; no vendor lock-in
- Hierarchical Memory — Five-tier memory system for true long-term personalization
- Agentic — Autonomous task execution with permission controls and sandboxing
- Observable — Comprehensive logging, distributed tracing, and metrics from day one
- Resilient — Graceful degradation, automatic failover, circuit breaking
- Accessible — WCAG-compliant interfaces with full keyboard and voice navigation
- Modular — a large active package tree under
libs/iris/**with clear boundaries; any subsystem can be replaced
2. Technology Stack#
The table below shows the technology chosen at each architectural layer. The
most important non-obvious choices: Hono (not Express) for the REST layer
because of its edge-runtime portability; Tauri (not Electron) for the desktop
app because of its Rust-native performance and smaller binary; and the shared
@oshun/event-bus (Redis pub/sub, not Kafka) for event transport to avoid
infrastructure dependencies not yet warranted at this stage of development.
| Layer | Technologies |
|---|---|
| Language | TypeScript (orchestration), Rust (performance-critical) |
| Runtime | Node.js 22+, Bun, WebAssembly |
| API Framework | Hono (REST), native WebSocket, gRPC via protobuf |
| Database | PostgreSQL (Prisma client; libs/iris/database) |
| Object Storage | MinIO (S3-compatible) — planned for file/document storage |
| Event Transport | Shared @oshun/event-bus — Redis pub/sub (ioredis), not Kafka |
| AI Providers | Anthropic Claude, OpenAI GPT, Google Gemini, Local (Ollama) |
| Search | Elasticsearch (optional, for full-text) |
| Observability | OpenTelemetry, Prometheus, Grafana, Jaeger |
| Build | Nx with esbuild/swc |
| Infrastructure | Kubernetes, Docker, Terraform |
| Desktop | Tauri (Rust shell + TypeScript UI) |
| Mobile | React Native |
| XR | WebXR API |
3. High-Level System Diagram#
The diagram below shows the target-state four-layer topology: clients talk through a gateway to a service layer, which delegates provider selection to an orchestration layer, which calls AI providers and stores results in a data layer. Read the implementation status note immediately below the diagram before drawing any conclusions about what is running today.
┌─────────────────────────────────────────────────────────────────────────────┐
│ CLIENT LAYER │
├─────────────┬─────────────┬─────────────┬─────────────┬─────────────────────┤
│ Desktop │ Mobile │ Web │ Browser │ XR/Wearable │
│ (Tauri) │ (RN/Native) │ (React) │ (Extension) │ (WebXR/Watch) │
└──────┬──────┴──────┬──────┴──────┬──────┴──────┬──────┴──────────┬──────────┘
│ │ │ │ │
└─────────────┴──────┬──────┴─────────────┴─────────────────┘
│
┌───────▼───────┐
│ API Gateway │
│ (Kong / Nginx) │
└───────┬───────┘
│
┌───────────────────────────┼───────────────────────────────────────────────────┐
│ SERVICE LAYER │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Conversation │◄►│ Memory │◄►│ Agent │ │
│ │ Service │ │ Service │ │ Service │ │
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │ │
│ ┌────────┴──────┬─────────────┴──────┬─────────────┴────────────┐ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ ┌─────────────────────┐ │
│ │Knowledge │ │ Code │ │ Multimodal │ │ Analytics │ │
│ │ Service │ │ Service │ │ Service │ │ Service │ │
│ └──────────┘ └──────────┘ └──────────────────┘ └─────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────────────┘
│
┌───────────────────────────┼───────────────────────────────────────────────────┐
│ ORCHESTRATION LAYER │
│ │
│ ┌──────────────────────────────┐ ┌──────────────────────────────┐ │
│ │ Model Router │ │ Tool Executor │ │
│ │ Cost / Quality / Latency │ │ Sandboxed / Permissioned │ │
│ └──────────────────────────────┘ └──────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────────────┘
│
┌───────────────────────────┼───────────────────────────────────────────────────┐
│ AI PROVIDER LAYER │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐ │
│ │Anthropic│ │ OpenAI │ │ Google │ │ Cohere │ │ Mistral │ │ Local │ │
│ │ Claude │ │ GPT │ │ Gemini │ │ │ │ │ │ (Ollama) │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └──────────┘ └──────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────────────┘
│
┌───────────────────────────┼───────────────────────────────────────────────────┐
│ DATA LAYER │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │
│ │PostgreSQL│ │ Redis │ │ Qdrant │ │Elastic │ │ @oshun/ │ │ MinIO │ │
│ │ (Prisma) │ │ pub/sub │ │ Vectors │ │ Search │ │event-bus │ │Storage │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────────────┘
Implementation status of this diagram: the diagram above is the target-state topology. As built today, the only runnable service is
@iris/api(a single Hono process), which stores domain state in-memory with JSON-file durability and touches PostgreSQL/Redis only for/health/readyprobes. The shared event bus (@oshun/event-bus,libs/shared/event-bus) is Redis pub/sub, not Kafka.libs/iris/databaseis a Prisma schema with three models (ConsentRecord,ContinuityState,MemoryScope). Qdrant, Elasticsearch, and MinIO are not yet wired into iris code. SeeDOMAINS/iris/specifications.md§11–§12 for the verified state.
4. Library Organization#
Iris has a large package tree under libs/iris/** — 258 package.json files
across 45 top-level cluster directories — organized into functional clusters.
The size reflects the breadth of the platform: each major feature area (memory,
agents, knowledge, multimodal, accessibility, etc.) is its own named cluster of
packages rather than a single monolithic library.
Two structural facts are important to keep in mind when navigating the tree: (1) the
conversation-*packages exist both as sibling top-level directories (e.g.libs/iris/conversation-core) and as children oflibs/iris/conversation/(e.g.libs/iris/conversation/branching); (2) several packagenamefields do not match their path (@iris/knowledgeis atknowledge/core,@iris/voiceis atmultimodal/voice/recognition,@iris/privacyis atmemory/privacy). The exact package inventory and counts are inDOMAINS/iris/specifications.md§14.
libs/iris/
├── core/ # Foundation: types, errors, context, config, logging
│
├── conversation/ # Conversation engine
│ ├── conversation-core/ # Core conversation types and state machine
│ ├── conversation-context/ # Context window management
│ ├── conversation-intent/ # Intent recognition
│ ├── conversation-state/ # Dialogue state machine
│ ├── conversation-response/ # Response generation
│ ├── conversation-rag/ # RAG pipeline integration
│ ├── conversation-style/ # Style and tone adaptation
│ ├── conversation-format/ # Output formatting (markdown, LaTeX)
│ ├── conversation-citations/ # Source attribution engine
│ ├── conversation-uncertainty/ # Confidence scoring
│ ├── conversation-orchestration/ # Multi-model orchestration
│ ├── conversation-providers-anthropic/ # Anthropic integration
│ ├── conversation-providers-openai/ # OpenAI integration
│ ├── conversation-providers-google/ # Google integration
│ └── conversation-providers-local/ # Local model integration
│
├── model-routing/ # Intelligent provider routing
├── failover/ # Circuit breaking, retry, fallback chains
├── ensemble/ # Multi-model voting and aggregation
│
├── memory/ # Hierarchical memory system (22 packages)
│ ├── core/ # @iris/memory-core
│ ├── short-term/ # @iris/memory-short-term
│ ├── long-term/ # @iris/memory-long-term
│ ├── episodic/ # @iris/memory-episodic
│ ├── semantic/ # @iris/memory-semantic
│ ├── consolidation/ # STM→LTM consolidation
│ ├── transitions/ # Tier transitions
│ ├── retrieval/ # Semantic memory retrieval
│ ├── persistence/ # @iris/memory-persistence
│ ├── personalization/ # @iris/personalization sub-tree
│ └── privacy/ # @iris/privacy (memory privacy)
│
├── knowledge/ # Knowledge base system (~23 packages)
│ ├── core/ # @iris/knowledge (core manager)
│ ├── chunking/ # Document chunking strategies
│ ├── embeddings/ # Knowledge embedding pipeline
│ ├── retrieval/ # Hybrid retrieval
│ ├── graph/ graphrag/ # Entity extraction and linking
│ ├── rag/ # RAG pipelines (agentic, multimodal, evaluation)
│ ├── factcheck/ # Fact verification against KB
│ ├── grounding/ # Response grounding
│ └── realtime/ # Real-time knowledge updates
│
├── agents/ # Agent system
│ ├── @iris/agents # Built-in agent catalog (root package)
│ ├── core/ # @iris/agents-core
│ ├── archetypes/ # @iris/archetypes — agent templates
│ ├── personalities/ # @iris/agent-personalities
│ ├── marketplace/ # @iris/agent-marketplace
│ ├── specialization/ # @iris/agent-specialization
│ ├── workflows/ # @iris/workflows
│ ├── multi-agent/ # @iris/multi-agent
│ ├── tools/ # Tool implementations (file, web, code, API, DB)
│ ├── computer-use/ # Computer use (browser, desktop, screen)
│ └── proactive/ # Proactive suggestions and automation
│
├── mcp/ # Model Context Protocol server/client
├── a2a/ # Agent-to-Agent communication protocol
│
├── reasoning-thinking/ # Extended reasoning capabilities
│ # Chain-of-thought, self-consistency, metacognition
│
├── emotional/ # Emotional intelligence
│ └── emotional-recognition/ # Emotion detection from text/voice
│
├── code/ # Code intelligence
│ # Generation, review, explanation, debugging, IDE, codebase analysis
│
├── multimodal/ # Multimodal capabilities
│ ├── voice/ # Voice input/output
│ ├── vision/ # Image analysis, OCR
│ ├── iot/ # IoT integration
│ └── bci/ # Brain-computer interface
│
├── personalization/ # User personalization
├── privacy/ # Privacy controls and anonymization
├── presence/ # Cross-device presence and sync
│
├── analytics/ # Analytics and insights
│ # Realtime, cohort, funnel, A/B testing
│
├── accessibility/ # Accessibility libraries
│ # Visual, motor, hearing, cognitive, i18n, braille, voice-ui
│
├── integrations/ # Cross-Oshun-domain bridges (not SaaS connectors)
│ # hathor, maya, nyx, psyche, sophia, yemaya — one package per sister domain
│
├── database/ # Prisma schema (3 models: consent, continuity, memory-scope)
├── config/ # Configuration utilities
├── sdk/ # TypeScript SDK for external consumers (sdk/typescript)
├── testing/ # Test utilities
└── types/ # Shared type definitions
Component Responsibilities#
The table below maps each component group to its primary responsibility. Note
that several entries (@iris/memory-*, @iris/knowledge-*, @iris/agents-*)
represent entire clusters of packages, not single libraries.
| Component | Responsibility |
|---|---|
@iris/core |
Foundation: types, errors, request context, logging |
@iris/conversation-* |
Dialogue management, intent, response generation |
@iris/model-routing |
Route requests to optimal AI provider |
@iris/failover |
Circuit breaking, retry logic, fallback chains |
@iris/ensemble |
Multi-model voting and consensus |
@iris/memory-* |
Four-tier memory hierarchy |
@iris/knowledge-* |
Knowledge base ingestion, retrieval, RAG |
@iris/agents-* |
Agent orchestration, tools, computer use |
@iris/mcp |
Model Context Protocol server and client |
@iris/a2a |
Agent-to-Agent communication protocol |
@iris/reasoning-* |
Extended thinking and metacognitive capabilities |
@iris/analytics-* |
Usage metrics, personal insights, A/B testing |
@iris/accessibility-* |
WCAG compliance, screen readers, motor/hearing aids |
@iris/integrations-* |
Cross-domain integration bridges |
5. Service Architecture#
The target-state design splits Iris into cooperating services behind a gateway.
As built, there is a single runnable service — @iris/api — a Hono process
that hosts the conversation, memory, agent, and knowledge route groups together
(see DOMAINS/iris/specifications.md §11). The table below describes the
planned decomposition; the rows labelled Conversation, Memory, Agent, and
Knowledge currently correspond to route groups inside @iris/api, not separate
deployables.
| Service (planned) | Description |
|---|---|
| API Gateway | Auth, rate limiting, routing (planned) |
| Conversation API | Primary REST + GraphQL + SSE endpoint for chat — implemented as @iris/api |
| Memory Service | Memory consolidation, retrieval, persistence — route group in @iris/api |
| Agent Service | Agent task orchestration and tool execution — route group in @iris/api |
| Knowledge Service | Document ingestion, chunking, indexing, retrieval — route group in @iris/api |
| Model Router | Provider selection, failover, circuit breaking (planned) |
| Analytics Service | Metrics collection, insights, dashboards (planned) |
| Admin API | Organization management, billing, configuration (planned) |
| Notification Service | Push, email, in-app notification delivery (planned) |
6. Conversation Pipeline#
A user message passes through several stages before the AI's response begins streaming back. Understanding this pipeline is essential for debugging latency issues or tracing where context is lost.
- Request Handler receives the raw HTTP request and applies authentication, rate limiting, and context enrichment (request ID, trace span).
- Intent Recognizer, Context Manager, and Memory Retrieval execute in parallel — classifying what the user wants, assembling the context window from recent messages, and injecting relevant memories from the four-tier store.
- Dialogue State Machine consults the assembled context and transitions to
the
processing→generatingstate, routing to the Response Generator. - Response Generator is itself a pipeline: it runs RAG retrieval to ground answers in knowledge-base content, applies a Style Adapter for tone and verbosity, and attaches a Citation Engine that links claims back to source documents.
- Model Orchestrator selects the best AI provider, handles failover if a provider is unavailable, and streams tokens back as SSE, WebSocket frames, or gRPC stream chunks.
User Message
|
v
┌───────────────┐
│ Request Handler│
│ Auth + Rate │
│ Limit + Context│
└───────┬───────┘
|
┌──────────────┼──────────────┐
v v v
┌──────────┐ ┌──────────────┐ ┌──────────────┐
│ Intent │ │ Context │ │ Memory │
│Recognizer│ │ Manager │ │ Retrieval │
└──────────┘ └──────────────┘ └──────────────┘
| | |
└──────────────┼──────────────┘
|
v
┌────────────────┐
│ Dialogue State │
│ Machine │
└────────┬───────┘
|
v
┌─────────────────────┐
│ Response Generator │
│ ┌───────────────┐ │
│ │ RAG Pipeline │ │ <--- knowledge retrieval
│ └───────────────┘ │
│ ┌───────────────┐ │
│ │ Style Adapter │ │ <--- tone, format, verbosity
│ └───────────────┘ │
│ ┌───────────────┐ │
│ │Citation Engine│ │ <--- source attribution
│ └───────────────┘ │
└──────────┬──────────┘
|
v
┌──────────────────────┐
│ Model Orchestrator │
│ Provider Selection │
│ Failover Handling │
│ Token Streaming │
└──────────┬───────────┘
|
v
AI Providers
(Claude / GPT / Gemini / ...)
|
v
Streaming Response
(SSE / WebSocket / gRPC)
7. Memory Service Architecture#
The memory system solves a fundamental LLM limitation: a model has no memory of previous conversations by default. Iris's five-tier architecture (working, short-term, long-term/archival, episodic, and semantic) mirrors human memory at different timescales — from the current session to the user's entire history with the platform.
The diagram below shows how a new memory signal flows from fast, ephemeral storage into permanent storage. The key decision point is the Importance Scorer: only memories that cross a recency/frequency/explicit-tag threshold are promoted; the rest are discarded to prevent unbounded growth.
NEW MEMORY SIGNAL
|
┌────────────┴────────────┐
| |
v v
┌─────────────────────┐ ┌────────────────────┐
│ SHORT-TERM (Redis) │ │ WORKING (Redis) │
│ TTL: 30 minutes │ │ TTL: Session │
└──────────┬──────────┘ └────────────────────┘
|
| (consolidation job, every 15min)
v
┌────────────────┐
│ Importance │
│ Scorer │
│ - recency │
│ - explicit tag │
│ - access freq │
└────────┬───────┘
|
┌─────────┴──────────┐
| |
score >= threshold score < threshold
| |
v v
┌───────────┐ Discard
│ LONG-TERM │
│(PostgreSQL │
│ + Qdrant) │
│ Permanent │
└───────────┘
SEMANTIC MEMORY (Qdrant)
- User knowledge graph
- Entity relationships
- Domain expertise model
- Vector similarity retrieval
EPISODIC MEMORY (PostgreSQL)
- Conversation summaries
- Key moments
- Milestones
- TTL: 90 days default
8. Agent Service Architecture#
The agent system transforms Iris from a conversational interface into an autonomous task executor. When a user submits a goal — "research competitors and write a summary report" — the agent pipeline decomposes it, plans a sequence of tool calls, executes them in a sandboxed environment, and optionally delegates sub-tasks to specialist agents.
The sandbox is the critical safety boundary. All tool invocations — file reads, web requests, code execution, GUI interactions — run inside an isolated runtime with CPU, memory, and disk limits enforced before any action touches the outside world.
Task Submission (user or system)
|
v
┌─────────────────┐
│ Task Parser │
│ Decompose goal │
└────────┬────────┘
|
v
┌─────────────────┐
│ Plan Generator │
│ Strategy+Steps │
└────────┬────────┘
|
v
┌─────────────────┐
│ Task Queue │ <--- priority-ordered
└────────┬────────┘
|
v
┌──────────────────────────────────────────┐
│ TOOL EXECUTION ENGINE │
│ │
│ File Ops │ Web Ops │ Code Exec │
│ API Ops │ DB Ops │ GUI Ops │
│ │
│ ┌────────────────────────────────────┐ │
│ │ SANDBOX RUNTIME │ │
│ │ Isolated execution │ │
│ │ Resource limits (CPU/mem/disk) │ │
│ │ Permission enforcement │ │
│ │ Audit logging │ │
│ └────────────────────────────────────┘ │
└──────────────────────────────────────────┘
|
v
┌──────────────────────────────────────────┐
│ MULTI-AGENT SYSTEM │
│ │
│ Agent Registry (A2A) │
│ Task Delegation │
│ Result Aggregation (Supervisor) │
│ MCP Server/Client │
└──────────────────────────────────────────┘
9. Data Architecture#
Data Store Responsibilities#
Each data store in the Iris architecture serves a distinct purpose. PostgreSQL holds structured records and consented data. Redis provides low-latency session state and backs the cross-domain event bus. Qdrant handles vector similarity search for memory and knowledge retrieval. MinIO stores user-uploaded binary content. The table below documents the current and planned roles — only PostgreSQL and Redis are touched by live code today.
Target-state data-store roles (today only PostgreSQL/Redis are touched, and only
by @iris/api's health probes — see the §3 status note):
| Store | Primary Data | Access Pattern |
|---|---|---|
| PostgreSQL | Consent, continuity, memory-scope records (Prisma) | CRUD + complex queries |
| Redis | Session cache, model health; @oshun/event-bus transport |
Low-latency key-value + pub/sub |
| Qdrant | Memory vectors, knowledge chunk vectors (planned) | ANN similarity search |
| MinIO | Uploaded files, exported conversations (planned) | Binary object storage |
@oshun/event-bus |
Redis-backed cross-domain event stream | Pub/sub + durable replay |
| Elasticsearch | Full-text search across conversations (planned) | Text search queries |
Data Flow Summary#
The following diagram shows how a user-uploaded document moves from binary storage through chunking and embedding into the three stores that serve retrieval: PostgreSQL for metadata, Qdrant for vector search, and the event bus for notifying other services of the new content.
User Upload ──────────────────────────────────────────┐
|
v
┌──────────────────┐
│ MinIO Storage │
└────────┬─────────┘
|
v
┌──────────────────┐
│ Chunking Pipeline│
└────────┬─────────┘
|
v
┌──────────────────┐
│ Embedding Model │
└────────┬─────────┘
|
┌───────────────────────┼──────────────────────┐
| | |
v v v
┌──────────┐ ┌──────────┐ ┌──────────┐
│PostgreSQL│ │ Qdrant │ │ @oshun/ │
│ metadata │ │ vectors │ │event-bus │
└──────────┘ └──────────┘ └──────────┘
10. Communication Patterns#
Synchronous (Client-Facing)#
Different clients need different protocols. REST handles standard CRUD operations; SSE streams AI tokens to the client as they are generated; WebSocket supports bidirectional flows like live chat updates; and gRPC is reserved for high-throughput internal calls where protobuf framing pays off.
| Protocol | Use Case | Implementation |
|---|---|---|
| REST/HTTP | CRUD operations, management APIs | Hono framework |
| SSE | Response streaming (text tokens) | Native SSE |
| WebSocket | Bidirectional real-time (chat, events) | ws library |
| gRPC | High-throughput internal service calls | protobuf |
Asynchronous (Internal)#
Internally, Iris uses Redis for all asynchronous patterns. The shared
@oshun/event-bus library adds durable replay, consumer groups, and dead-letter
semantics on top of bare pub/sub, making it suitable for cross-domain event
delivery where message loss is unacceptable.
| Pattern | Technology | Use Case |
|---|---|---|
| Pub/Sub | Redis | Real-time session events |
| Cross-domain events | @oshun/event-bus |
Redis pub/sub with durable replay, consumer groups, dead-letter |
| Job Queue | Redis | Background tasks (consolidation, indexing) |
11. Security Architecture#
Authentication Layers#
Iris supports three authentication mechanisms, ranging from long-lived API keys for programmatic access to short-lived JWTs for interactive sessions. Enterprise deployments add OAuth 2.0 to integrate with existing identity providers without requiring separate Iris credentials.
- API Key — HMAC-signed keys with scope, expiry, and per-key rate limits
- JWT Session — Short-lived JWTs for web/mobile sessions, rotated via refresh tokens
- OAuth 2.0 — Integration with external identity providers (Google, GitHub, enterprise SSO)
Data Protection#
- At-rest encryption — AES-256-GCM for conversation content; per-user key derivation
- In-transit encryption — TLS 1.3 for all external traffic; mTLS for internal service mesh
- End-to-end encryption — Optional client-side encryption; server holds no plaintext
- Secret detection — Regex and ML-based scanning of inputs for API keys, credentials
Permission Model#
The permission hierarchy flows downward from organization to API key scope. Every API call carries an API key that declares which scopes it is authorized for; the service layer enforces those scopes before executing any operation.
Organization
└── Teams
└── Users
└── API Keys
└── Scopes
├── conversations:read
├── conversations:write
├── memory:read
├── memory:write
├── knowledge:read
├── knowledge:write
├── agents:run
└── admin:*
12. Observability Architecture#
Telemetry Stack#
Observability is structured in three layers: distributed traces capture the full request path across services; metrics track aggregate performance over time; and structured logs provide per-request detail. Grafana dashboards compose metrics and trace data into operational views.
| Layer | Tool | Data Collected |
|---|---|---|
| Tracing | Jaeger | Distributed traces across all service calls |
| Metrics | Prometheus | Request rates, latencies, token counts, memory usage |
| Logs | Pino → Loki | Structured JSON logs with trace correlation |
| Dashboards | Grafana | Real-time operational dashboards |
Key Metrics#
The metrics below are the primary signals for Iris operational health. Each metric is labelled with its type (counter, histogram, gauge) and its cardinality dimensions, which determine how it can be sliced in dashboards and alerts.
iris_conversation_requests_total (counter, by agent, model, status)
iris_message_latency_ms (histogram, by model, provider)
iris_token_consumption_total (counter, by user, model)
iris_memory_consolidation_duration_ms (histogram)
iris_knowledge_retrieval_score (histogram, by collection)
iris_model_provider_error_rate (gauge, by provider)
iris_agent_task_duration_ms (histogram, by agent)
iris_cache_hit_ratio (gauge, by cache type)
13. Deployment Architecture#
Kubernetes Service Topology#
The target deployment is a Kubernetes cluster where each Iris service runs as an autoscaling deployment behind a Kong ingress. Stateful components (PostgreSQL, Redis, Qdrant) run as StatefulSets with their own storage volumes. The memory consolidator is a recurring CronJob rather than a long-running service, since it only needs to run every 15 minutes.
Ingress (Kong)
|
├── iris-conversation-api (HPA: 2-20 replicas)
├── iris-memory-service (HPA: 2-10 replicas)
├── iris-agent-service (HPA: 2-10 replicas)
├── iris-knowledge-service (HPA: 2-10 replicas)
├── iris-analytics-service (HPA: 2-5 replicas)
└── iris-admin-api (2 replicas, fixed)
StatefulSets:
├── postgres-primary + read-replicas
├── redis-cluster
└── qdrant-cluster
Jobs:
└── iris-memory-consolidator (CronJob, every 15min)
Client Applications#
Client applications are distributed through their respective platform channels. The Tauri desktop app is distributed through package managers rather than a web store, which avoids app store review delays for enterprise customers.
| App | Deployment Target | Distribution Channel |
|---|---|---|
| Web | CDN (Cloudflare) | Browser |
| Desktop | Tauri binary | Homebrew, Winget, Snap, direct |
| Mobile | React Native | App Store, Google Play |
| Wearable | Watch SDK | watchOS App, Wear OS |
| XR | WebXR (web-based) | Browser / Meta Store |
14. Domain Dependencies#
Libraries Iris Depends On#
Iris has a deliberately narrow set of shared-library dependencies. The most
important one is @oshun/event-bus, which provides the Redis-backed
cross-domain event transport. Note that @oshun/auth and @oshun/events are
not imported by any libs/iris code today — the API currently uses a
placeholder user ID, and the event bus is named @oshun/event-bus, not
@oshun/events.
| Library / Domain | Purpose |
|---|---|
@oshun/database |
Shared Postgres/Redis client factories (@iris/api health probes) |
@oshun/event-bus |
Shared Redis-backed cross-domain event bus (target-state) |
@nous/* |
Local LLM inference / model serving for on-device & privacy mode (planned integration) |
Domains That Depend on Iris#
The following Oshun domains consume Iris via dedicated bridge libraries under
libs/iris/integrations/. The boundary exists because Iris owns the AI
conversation stack — model routing, memory, agents, knowledge retrieval — while
the consuming domains own their own domain logic and user experiences. Rather
than each domain maintaining its own AI integration code, they depend on Iris's
typed bridge packages, which encapsulate the Iris API contract and evolve
together with the Iris platform.
| Domain | Integration Library | How Iris Is Used |
|---|---|---|
| Psyche | @iris/integrations-psyche |
Conversation AI for digital human personas |
| Sophia | @iris/integrations-sophia |
Research Q&A against academic knowledge bases |
| Maya | @iris/integrations-maya |
AI assistance for game/world creation |
| Yemaya | @iris/integrations-yemaya |
Creative writing and artistic AI tools |
| Hathor | @iris/integrations-hathor |
Lore and narrative AI assistance |
| Nyx | @iris/integrations-nyx |
Astronomical event queries |