# Iris Domain Architecture

> **Canonical source:** the canonical architecture document for this domain is
> [`deep-dive/architecture.md`](./deep-dive/architecture.md), rendered in the
> docs center. This file is its operational companion (service topology, APIs,
> schemas, runtime detail) — reconciled by linking, not duplicated (§2, §13).

> **Iris** - The Universal Intelligent Assistant Platform

This document describes the technical architecture of the Iris domain, providing
a comprehensive view of system components, service interactions, data flows, and
security architecture.

---

## Table of Contents

1. [Overview](#overview)
2. [Current Implementation Baseline](#current-implementation-baseline)
3. [High-Level Architecture](#high-level-architecture)
4. [Core Components](#core-components)
5. [Service Architecture](#service-architecture)
6. [Data Architecture](#data-architecture)
7. [Communication Patterns](#communication-patterns)
8. [Security Architecture](#security-architecture)
9. [Deployment Architecture](#deployment-architecture)
10. [Integration Architecture](#integration-architecture)
11. [Observability Architecture](#observability-architecture)

---

## Overview

Iris is the Universal Intelligent Assistant Platform for the Oshun ecosystem. It
provides state-of-the-art AI assistance through multimodal interaction (text,
voice, vision), deep personalization, agentic capabilities, and seamless
integration with all Oshun services.

## Current Implementation Baseline

This baseline reflects the deployable Iris platform in this repository:
`apps/iris/api`, the split service containers in `docker/iris`, the Kubernetes
manifests in `infra/k8s/iris`, and the monitoring stack in
`infra/monitoring/iris`.

### System Boundary Diagram

```text
                         External clients
        desktop | web | mobile | developer portal | XR | wearable
                                  |
                                  v
                       +----------------------+
                       | ingress / API edge   |
                       | TLS, WAF, rate limit |
                       +----------+-----------+
                                  |
                                  v
+------------------------------------------------------------------------+
| namespace: iris                                                        |
|                                                                        |
|  +-----------+     +-------------------+     +---------------+         |
|  | iris-api  +---->| iris-conversation |---->| model router  |         |
|  | REST      |     | dialogue/RAG      |     | providers     |         |
|  | GraphQL   |     +---------+---------+     +-------+-------+         |
|  | OpenAPI   |               |                       |                 |
|  +-----+-----+               v                       v                 |
|        |              +-------------+        Anthropic/OpenAI/Google    |
|        |              | iris-memory |        local providers            |
|        |              | memories    |                                  |
|        |              +------+------+                                  |
|        |                     |                                         |
|        |              +------+-----+                                   |
|        +------------->| iris-agent |                                   |
|        |              | tools/tasks|                                   |
|        |              +------+-----+                                   |
|        |                     |                                         |
|        +------------->+-------------+       +-------------+            |
|                       | iris-voice  |       | iris-worker |            |
|                       | STT/TTS     |       | async jobs  |            |
|                       +-------------+       +-------------+            |
+------------------------------------------------------------------------+
          |                    |                      |
          v                    v                      v
+----------------+   +----------------+   +-----------------------------+
| PostgreSQL     |   | Redis          |   | Qdrant                      |
| source records |   | sessions, jobs |   | semantic vectors            |
| pgvector       |   | rate/cache     |   | memory and knowledge search |
+----------------+   +----------------+   +-----------------------------+
          |
          v
+-----------------------------------------------------------------------+
| observability: Prometheus ServiceMonitors, Grafana dashboards,         |
| recording rules, alerting rules, Jaeger OTLP traces, Loki,             |
| Elasticsearch, and CloudWatch-compatible log shipping                  |
+-----------------------------------------------------------------------+
```

### Deployable Services

| Service             | Kubernetes workload                         | Container                             | Primary responsibility                                                                                               | Required backing services                                               |
| ------------------- | ------------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `iris-api`          | `infra/k8s/iris/base/services/api`          | `docker/iris/Dockerfile.api`          | Public REST, GraphQL, OpenAPI docs, request IDs, error handling, tracing middleware, and fan-out to domain services. | PostgreSQL, Redis, Qdrant, AI provider secrets, downstream service URLs |
| `iris-conversation` | `infra/k8s/iris/base/services/conversation` | `docker/iris/Dockerfile.conversation` | Dialogue processing, context assembly, memory lookup coordination, agent handoff, and model orchestration.           | PostgreSQL, Redis, memory service, agent service, AI providers          |
| `iris-memory`       | `infra/k8s/iris/base/services/memory`       | `docker/iris/Dockerfile.memory`       | Working, core, archival, episodic, and semantic memory APIs.                                                         | PostgreSQL, Redis, Qdrant, embedding provider                           |
| `iris-agent`        | `infra/k8s/iris/base/services/agent`        | `docker/iris/Dockerfile.agent`        | Agent definitions, task planning, task execution state, tool registration, and tool invocation limits.               | PostgreSQL, Redis, memory service, AI providers                         |
| `iris-voice`        | `infra/k8s/iris/base/services/voice`        | `docker/iris/Dockerfile.voice`        | Speech-to-text, text-to-speech, voice caching, and voice-provider mediation.                                         | Redis, voice provider secrets                                           |
| `iris-worker`       | `infra/k8s/iris/base/services/worker`       | `docker/iris/Dockerfile.worker`       | Async memory consolidation, analytics aggregation, cleanup, and background jobs.                                     | PostgreSQL, Redis, Qdrant, AI providers                                 |

The API service is the current feature-complete process for REST and GraphQL.
The split service containers expose health, readiness, and metadata endpoints
through `docker/iris/runtime/service-runner.mjs`, and the Kubernetes service
URLs establish the production topology for independent scaling and rollout.

### Service Interactions

```text
Conversation request:

client
  -> iris-api /api/v1/conversations or /graphql
  -> request-id, rate-limit, tracing, structured logging middleware
  -> conversation service data source
  -> iris-conversation service URL when deployed as split services
  -> iris-memory for working/contextual/semantic recall
  -> iris-agent when the turn needs tools or delegated tasks
  -> model router and provider adapter
  -> token stream or final response
  -> PostgreSQL conversation/message records
  -> Redis active context cache
  -> traces, metrics, and redacted logs

Memory write/read:

conversation turn or explicit memory API
  -> iris-api memory route or GraphQL memory resolver
  -> iris-memory
  -> classify memory tier and sensitivity
  -> write canonical record to PostgreSQL
  -> cache hot working/session state in Redis
  -> embed semantic content and upsert into Qdrant
  -> emit audit, metric, log, and trace records

Agent task:

client or conversation orchestration
  -> iris-api agent route or GraphQL agent resolver
  -> iris-agent
  -> validate permissions, quotas, and max tool calls
  -> enqueue or execute task with Redis-backed coordination
  -> call memory service for context
  -> execute approved tool or provider call
  -> persist task, step, and tool execution state in PostgreSQL
  -> worker handles deferred consolidation and cleanup
```

### Data Flows And Schemas

| Store                              | Owner                                    | Key schemas or keys                                                                                                                                                                                                                                                                              | Purpose                                                                                                                                       |
| ---------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| PostgreSQL `iris` database         | API, conversation, memory, agent, worker | `users`, `user_profiles`, `user_subscriptions`, `user_quota`, `agents`, `tools`, `conversations`, `messages`, memory tables, task/tool execution tables, analytics events, and pgvector embedding tables from `docker/init-scripts/iris-init.sql` and `libs/iris/database/prisma/schema.prisma`. | Source of record for identity-linked state, conversations, messages, agents, memory records, tool execution history, quotas, and analytics.   |
| Redis                              | API, conversation, memory, voice, worker | `session:{id}`, `context:{conversation_id}`, `working:{user_id}`, `user:{id}:prefs`, `model:{hash}`, `embedding:{hash}`, `provider:{name}:status`, `ratelimit:{scope}`, worker queues, voice cache keys.                                                                                         | Low-latency session state, context windows, working memory, rate limits, queue coordination, provider health, and cacheable provider outputs. |
| Qdrant                             | Memory, worker, API knowledge flows      | Memory vectors, knowledge chunk vectors, embedding metadata, tenant/user filters, collection-level payload indexes.                                                                                                                                                                              | Semantic retrieval for memory recall, RAG context assembly, and knowledge search.                                                             |
| Object storage and provider stores | Knowledge and multimodal extensions      | Uploaded source documents, extracted media, voice artifacts, generated assets.                                                                                                                                                                                                                   | Large binary and document payloads referenced by PostgreSQL metadata.                                                                         |

PostgreSQL remains the authority for user-visible records. Redis data is
rebuildable from PostgreSQL or provider state. Qdrant stores derived vector
indexes and must be re-indexable from canonical memory and knowledge records.

### Security Architecture Summary

Iris uses a 5-layer security model:

| Layer             | Boundary                  | Controls                                                                                                                                             | Implementation references                                                        |
| ----------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| 1. Edge security  | Internet to ingress       | TLS termination, WAF, IP throttles, ingress policy, request size limits.                                                                             | Production ingress manifests and edge gateway configuration.                     |
| 2. Authentication | API entry                 | API keys, JWT/OAuth/session integration, request ID propagation, unauthenticated health isolation.                                                   | `apps/iris/api/src/index.ts`, route middleware, and secret-backed API env.       |
| 3. Authorization  | User/resource access      | Role and resource checks, tenant/user scoping, quotas, feature flags, tool permission gates.                                                         | API services, agent tool limits, `IRIS_AGENT_MAX_TOOL_CALLS`, quota schema.      |
| 4. Data security  | Persistence and transport | TLS in transit, encrypted secrets, field redaction, sensitive-field logging filters, memory privacy controls, least-privilege service accounts.      | `libs/iris/core/src/logging`, `infra/k8s/iris/base/rbac.yaml`, secret templates. |
| 5. AI safety      | Model/tool execution      | Input classification, output policy filters, prompt/tool boundaries, sandboxed execution, audit logs, local-model routing for high-sensitivity data. | Agent service, memory safety modules, provider routing, audit/event schemas.     |

### Deployment Architecture Summary

The production Kubernetes overlay deploys all six Iris services, shared
configuration, secrets, service accounts, HPAs, VPAs, pod disruption budgets,
production ingress, and image overrides. Development and staging overlays use
the same service graph with environment-specific replica counts, log levels, and
resource constraints.

```text
infra/k8s/iris
  base/
    namespaces: iris, iris-data
    services: api, conversation, memory, agent, voice, worker
    config: iris-common-config, redis config, qdrant config
    security: RBAC, service accounts, secret templates
    scaling: HPA per service, VPA recommendations, priority classes
  overlays/
    development: local-friendly resources and debug logging
    staging: release-candidate sizing and smoke validation
    production: ingress, PDBs, HA replicas, production image tags
```

### Integration Architecture Summary

Iris integrates across three planes:

| Plane             | Interfaces                                                                                                                                                   | Notes                                                                                        |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| Product clients   | REST under `/api/v1/*`, GraphQL at `/graphql`, OpenAPI/docs under `/docs`, health under `/health`.                                                           | Used by the web, desktop, mobile, developer portal, XR, wearable, and SDK surfaces.          |
| Oshun domains     | Memory bridge, assistant shell integration, analytics, auth, domain adapters, and cross-domain packages under `libs/oshun/*` and `libs/iris/integrations/*`. | Iris is the assistant/orchestration layer for domain-specific products.                      |
| External services | Anthropic, OpenAI, Google, local model providers, Qdrant, Redis, PostgreSQL, speech providers, search providers, and observability backends.                 | Provider credentials are injected through Kubernetes secrets and environment-specific CI/CD. |

### Observability Architecture Summary

Every Iris service receives common logging and tracing env through the base
Kustomize patches. Monitoring discovers all six services with Prometheus
`ServiceMonitor` resources, records SLO-oriented aggregates, and loads Grafana
dashboards for API, conversation, memory, agent, voice, and worker operations.

```text
service process
  -> structured JSON logger with redaction
  -> HTTP log transports for Loki, Elasticsearch bulk, and CloudWatch-compatible ingestion
  -> OpenTelemetry spans with W3C tracecontext propagation
  -> OTLP HTTP export to Jaeger at port 4318
  -> Prometheus scrape via per-service ServiceMonitor
  -> recording rules and alerting rules
  -> Grafana service dashboards
```

### Design Principles

1. **Privacy-First**: On-device processing where possible, end-to-end encryption
2. **Multi-Model**: Intelligent routing across multiple AI providers
3. **Hierarchical Memory**: Four-tier memory system for true personalization
4. **Agentic**: Autonomous task execution with appropriate guardrails
5. **Observable**: Comprehensive logging, tracing, and metrics
6. **Resilient**: Graceful degradation, failover, and circuit breaking

### Technology Stack

| Layer          | Technologies                                                |
| -------------- | ----------------------------------------------------------- |
| Language       | TypeScript (orchestration), Rust (performance-critical)     |
| Runtime        | Node.js 22+, Bun, WebAssembly                               |
| Database       | PostgreSQL + pgvector, Redis, Qdrant                        |
| Message Queue  | Kafka, Redis Streams                                        |
| API            | REST (Hono), GraphQL, WebSocket, gRPC                       |
| AI Providers   | Anthropic Claude, OpenAI GPT, Google Gemini, Local (Ollama) |
| Observability  | OpenTelemetry, Prometheus, Grafana, Jaeger                  |
| Infrastructure | Kubernetes, Docker, Terraform                               |

---

## High-Level Architecture

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              CLIENT LAYER                                    │
├─────────────┬─────────────┬─────────────┬─────────────┬─────────────────────┤
│   Desktop   │   Mobile    │     Web     │   Browser   │      XR/AR          │
│   (Tauri)   │ (RN/Native) │   (React)   │ (Extension) │  (WebXR/Native)     │
└──────┬──────┴──────┬──────┴──────┬──────┴──────┬──────┴──────────┬──────────┘
       │             │             │             │                 │
       └─────────────┴──────┬──────┴─────────────┴─────────────────┘
                            │
                    ┌───────▼───────┐
                    │   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 Execution    │ │            │
│ │  │ Optimization            │ │  │  │  Permission Control     │ │            │
│ │  └─────────────────────────┘ │  │  └─────────────────────────┘ │            │
│ └──────────────────────────────┘  └──────────────────────────────┘            │
│                                                                               │
└───────────────────────────────────────────────────────────────────────────────┘
                            │
┌───────────────────────────┼───────────────────────────────────────────────────┐
│                     AI PROVIDER LAYER                                         │
│                           │                                                   │
│  ┌─────────────┬──────────┼──────────┬─────────────┬─────────────┐            │
│  │             │          │          │             │             │            │
│  ▼             ▼          ▼          ▼             ▼             ▼            │
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────────┐ ┌────────────┐     │
│ │Anthropic│ │ OpenAI │ │ Google │ │ Cohere │ │  Mistral   │ │   Local    │     │
│ │ Claude │ │  GPT   │ │ Gemini │ │        │ │            │ │  (Ollama)  │     │
│ └────────┘ └────────┘ └────────┘ └────────┘ └────────────┘ └────────────┘     │
│                                                                               │
└───────────────────────────────────────────────────────────────────────────────┘
                            │
┌───────────────────────────┼───────────────────────────────────────────────────┐
│                      DATA LAYER                                               │
│                           │                                                   │
│  ┌─────────────┬──────────┼──────────┬─────────────┬─────────────┐            │
│  │             │          │          │             │             │            │
│  ▼             ▼          ▼          ▼             ▼             ▼            │
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────────┐ ┌────────────┐     │
│ │PostgreSQL│ │ Redis  │ │ Qdrant │ │Elastic │ │   Kafka    │ │   MinIO    │     │
│ │+pgvector│ │ Cache  │ │ Vectors│ │ Search │ │  Streams   │ │  Storage   │     │
│ └────────┘ └────────┘ └────────┘ └────────┘ └────────────┘ └────────────┘     │
│                                                                               │
└───────────────────────────────────────────────────────────────────────────────┘
```

---

## Core Components

### Library Structure

```
libs/iris/
├── core/                         # Foundation library
│   ├── src/
│   │   ├── types.ts              # Branded types, Result types
│   │   ├── errors/               # Error hierarchy
│   │   ├── context/              # Request context management
│   │   ├── config/               # Configuration schemas
│   │   ├── tracing/              # OpenTelemetry integration
│   │   └── logging/              # Structured logging (Pino)
│   └── package.json
│
├── conversation/                 # Conversation engine
│   ├── core/                     # Core conversation types
│   ├── context/                  # Context management
│   ├── intent/                   # Intent recognition
│   ├── state/                    # Dialogue state machine
│   ├── response/                 # Response generation
│   ├── rag/                      # RAG pipeline
│   ├── style/                    # Style adaptation
│   ├── format/                   # Output formatting
│   ├── citations/                # Source attribution
│   ├── uncertainty/              # Confidence scoring
│   ├── orchestration/            # Multi-model orchestration
│   ├── providers-openai/         # OpenAI integration
│   ├── providers-anthropic/      # Anthropic integration
│   ├── providers-google/         # Google integration
│   └── providers-local/          # Local model integration
│
├── model-routing/                # Intelligent model routing
│   └── src/
│       ├── router.ts             # Task-based routing
│       ├── cost-optimizer.ts     # Cost optimization
│       └── latency-tracker.ts    # Latency monitoring
│
├── failover/                     # Failover & circuit breaking
│   └── src/
│       ├── circuit-breaker.ts    # Circuit breaker pattern
│       ├── retry.ts              # Retry strategies
│       └── fallback.ts           # Fallback chains
│
├── ensemble/                     # Multi-model ensemble
│   └── src/
│       ├── voting.ts             # Ensemble voting
│       └── aggregation.ts        # Response aggregation
│
├── mcp/                          # Model Context Protocol
│   └── src/
│       ├── server.ts             # MCP server implementation
│       └── client.ts             # MCP client
│
├── a2a/                          # Agent-to-Agent protocol
│   └── src/
│       ├── protocol.ts           # A2A protocol implementation
│       └── registry.ts           # Agent registry
│
├── reasoning-thinking/           # Extended reasoning
│   └── src/
│       ├── chain-of-thought.ts   # CoT reasoning
│       ├── self-consistency.ts   # Self-consistency checking
│       └── metacognition.ts      # Metacognitive monitoring
│
├── code/                         # Code intelligence
│   ├── codebase/                 # Codebase understanding
│   └── analysis/                 # Static analysis
│
├── analytics/                    # Analytics & insights
│   └── src/
│       ├── metrics.ts            # Metric collection
│       └── insights.ts           # User insights
│
├── config/                       # Configuration utilities
├── testing/                      # Test utilities
└── types/                        # Shared type definitions
```

### Component Responsibilities

| Component              | Responsibility                                      |
| ---------------------- | --------------------------------------------------- |
| `@iris/core`           | Foundation: types, errors, context, config, logging |
| `@iris/conversation-*` | Dialogue management, intent, response generation    |
| `@iris/model-routing`  | Route requests to optimal AI provider               |
| `@iris/failover`       | Circuit breaking, retry logic, failover chains      |
| `@iris/ensemble`       | Multi-model voting and consensus                    |
| `@iris/mcp`            | Model Context Protocol server/client                |
| `@iris/a2a`            | Agent-to-Agent communication protocol               |
| `@iris/reasoning`      | Extended thinking and reasoning capabilities        |
| `@iris/code`           | Code understanding and generation                   |
| `@iris/analytics`      | Usage metrics and personal insights                 |

---

## Service Architecture

### Conversation Service

The Conversation Service is the primary entry point for user interactions.

```
┌─────────────────────────────────────────────────────────────────────┐
│                     CONVERSATION SERVICE                            │
│                                                                     │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐  │
│  │   REST API      │    │  WebSocket API  │    │   gRPC API      │  │
│  │   /v1/chat      │    │  Real-time      │    │   Streaming     │  │
│  └────────┬────────┘    └────────┬────────┘    └────────┬────────┘  │
│           │                      │                      │           │
│           └──────────────────────┼──────────────────────┘           │
│                                  │                                  │
│                     ┌────────────▼────────────┐                     │
│                     │    Request Handler      │                     │
│                     │  - Authentication       │                     │
│                     │  - Rate Limiting        │                     │
│                     │  - Context Extraction   │                     │
│                     └────────────┬────────────┘                     │
│                                  │                                  │
│  ┌───────────────────────────────┼───────────────────────────────┐  │
│  │                    DIALOGUE PIPELINE                          │  │
│  │                               │                               │  │
│  │  ┌─────────────┐  ┌──────────▼──────────┐  ┌─────────────┐   │  │
│  │  │   Intent    │◄─┤   State Machine     ├─►│   Context   │   │  │
│  │  │  Recognizer │  │   (Dialogue State)  │  │   Manager   │   │  │
│  │  └─────────────┘  └──────────┬──────────┘  └─────────────┘   │  │
│  │                              │                               │  │
│  │                   ┌──────────▼──────────┐                    │  │
│  │                   │  Response Generator │                    │  │
│  │                   │  - RAG Pipeline     │                    │  │
│  │                   │  - Style Adapter    │                    │  │
│  │                   │  - Citation Engine  │                    │  │
│  │                   └──────────┬──────────┘                    │  │
│  │                              │                               │  │
│  └──────────────────────────────┼───────────────────────────────┘  │
│                                 │                                  │
│                    ┌────────────▼────────────┐                     │
│                    │    Model Orchestrator   │                     │
│                    │  - Provider Selection   │                     │
│                    │  - Failover Handling    │                     │
│                    │  - Response Streaming   │                     │
│                    └────────────┬────────────┘                     │
│                                 │                                  │
└─────────────────────────────────┼──────────────────────────────────┘
                                  │
                    ┌─────────────▼─────────────┐
                    │       AI Providers        │
                    │  Anthropic │ OpenAI │ ... │
                    └───────────────────────────┘
```

### Memory Service

The Memory Service implements hierarchical memory for personalization.

```
┌─────────────────────────────────────────────────────────────────────┐
│                       MEMORY SERVICE                                │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                    MEMORY TIERS                              │   │
│  │                                                              │   │
│  │  ┌──────────────────┐  ┌──────────────────┐                  │   │
│  │  │  SHORT-TERM (STM) │  │   WORKING MEMORY  │                 │   │
│  │  │  - Current turn   │  │  - Active task    │                 │   │
│  │  │  - Recent context │  │  - File refs      │                 │   │
│  │  │  - Redis cache    │  │  - Temp state     │                 │   │
│  │  │  TTL: 30 minutes  │  │  TTL: Session     │                 │   │
│  │  └──────────────────┘  └──────────────────┘                  │   │
│  │                                                              │   │
│  │  ┌──────────────────┐  ┌──────────────────┐                  │   │
│  │  │   LONG-TERM (LTM) │  │  EPISODIC MEMORY  │                 │   │
│  │  │  - Preferences   │  │  - Past sessions  │                 │   │
│  │  │  - Learned prefs │  │  - Key moments    │                 │   │
│  │  │  - PostgreSQL    │  │  - Milestones     │                 │   │
│  │  │  TTL: Permanent  │  │  TTL: 90 days     │                 │   │
│  │  └──────────────────┘  └──────────────────┘                  │   │
│  │                                                              │   │
│  │  ┌──────────────────────────────────────────┐                │   │
│  │  │           SEMANTIC MEMORY                 │                │   │
│  │  │  - User knowledge graph                  │                │   │
│  │  │  - Entity relationships                  │                │   │
│  │  │  - Domain expertise model                │                │   │
│  │  │  - Qdrant vector store                   │                │   │
│  │  │  TTL: Permanent (with decay)             │                │   │
│  │  └──────────────────────────────────────────┘                │   │
│  │                                                              │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                  MEMORY OPERATIONS                           │   │
│  │                                                              │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │   │
│  │  │   STORE     │  │  RETRIEVE   │  │   CONSOLIDATE       │  │   │
│  │  │  - Write    │  │  - Search   │  │  - STM → LTM        │  │   │
│  │  │  - Index    │  │  - Rank     │  │  - Summarize        │  │   │
│  │  │  - Embed    │  │  - Filter   │  │  - Importance score │  │   │
│  │  └─────────────┘  └─────────────┘  └─────────────────────┘  │   │
│  │                                                              │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

### Agent Service

The Agent Service handles agentic task execution and tool use.

```
┌─────────────────────────────────────────────────────────────────────┐
│                        AGENT SERVICE                                │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                    TASK ORCHESTRATOR                         │   │
│  │                                                              │   │
│  │  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐     │   │
│  │  │ Task Parser  │──►│ Plan Generator│──►│ Task Queue   │     │   │
│  │  │ (Decompose)  │   │ (Strategy)    │   │ (Priority)   │     │   │
│  │  └──────────────┘   └──────────────┘   └──────────────┘     │   │
│  │                                                              │   │
│  └──────────────────────────────┬──────────────────────────────┘   │
│                                 │                                  │
│  ┌──────────────────────────────▼──────────────────────────────┐   │
│  │                    TOOL EXECUTION ENGINE                     │   │
│  │                                                              │   │
│  │  ┌─────────────────────────────────────────────────────┐    │   │
│  │  │                   TOOL REGISTRY                      │    │   │
│  │  │                                                      │    │   │
│  │  │  ┌────────────┐  ┌────────────┐  ┌────────────┐     │    │   │
│  │  │  │  File Ops  │  │  Web Ops   │  │  Code Exec │     │    │   │
│  │  │  │  - Read    │  │  - Browse  │  │  - Run     │     │    │   │
│  │  │  │  - Write   │  │  - Search  │  │  - Debug   │     │    │   │
│  │  │  │  - Search  │  │  - Extract │  │  - Test    │     │    │   │
│  │  │  └────────────┘  └────────────┘  └────────────┘     │    │   │
│  │  │                                                      │    │   │
│  │  │  ┌────────────┐  ┌────────────┐  ┌────────────┐     │    │   │
│  │  │  │  API Ops   │  │  DB Ops    │  │  GUI Ops   │     │    │   │
│  │  │  │  - REST    │  │  - Query   │  │  - Click   │     │    │   │
│  │  │  │  - GraphQL │  │  - Mutate  │  │  - Type    │     │    │   │
│  │  │  │  - gRPC    │  │  - Schema  │  │  - Screenshot    │   │   │
│  │  │  └────────────┘  └────────────┘  └────────────┘     │    │   │
│  │  │                                                      │    │   │
│  │  └─────────────────────────────────────────────────────┘    │   │
│  │                                                              │   │
│  │  ┌─────────────────────────────────────────────────────┐    │   │
│  │  │                   SANDBOX RUNTIME                    │    │   │
│  │  │  - Isolated execution environment                    │    │   │
│  │  │  - Resource limits (CPU, memory, time)              │    │   │
│  │  │  - Permission enforcement                            │    │   │
│  │  │  - Audit logging                                     │    │   │
│  │  └─────────────────────────────────────────────────────┘    │   │
│  │                                                              │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                    MULTI-AGENT SYSTEM                        │   │
│  │                                                              │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │   │
│  │  │  Research   │  │   Code      │  │   Data              │  │   │
│  │  │   Agent     │  │   Agent     │  │   Agent             │  │   │
│  │  └─────────────┘  └─────────────┘  └─────────────────────┘  │   │
│  │                                                              │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │   │
│  │  │  Creative   │  │ Operations  │  │   Supervisor        │  │   │
│  │  │   Agent     │  │   Agent     │  │   Agent             │  │   │
│  │  └─────────────┘  └─────────────┘  └─────────────────────┘  │   │
│  │                                                              │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

---

## Data Architecture

### Database Schema Overview

```
┌─────────────────────────────────────────────────────────────────────┐
│                      PostgreSQL (iris database)                     │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                    CORE TABLES                               │   │
│  │                                                              │   │
│  │  users              conversations        messages            │   │
│  │  ├─ id (uuid)       ├─ id (uuid)         ├─ id (uuid)       │   │
│  │  ├─ external_id     ├─ user_id           ├─ conversation_id │   │
│  │  ├─ preferences     ├─ title             ├─ role            │   │
│  │  ├─ created_at      ├─ context           ├─ content         │   │
│  │  └─ updated_at      ├─ created_at        ├─ metadata        │   │
│  │                     └─ updated_at        ├─ tokens          │   │
│  │                                          └─ created_at      │   │
│  │                                                              │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                    MEMORY TABLES                             │   │
│  │                                                              │   │
│  │  long_term_memory     episodic_memory    semantic_memory    │   │
│  │  ├─ id                ├─ id              ├─ id              │   │
│  │  ├─ user_id           ├─ user_id         ├─ user_id         │   │
│  │  ├─ key               ├─ event_type      ├─ entity          │   │
│  │  ├─ value             ├─ summary         ├─ embedding       │   │
│  │  ├─ confidence        ├─ importance      ├─ relationships   │   │
│  │  ├─ source            ├─ session_id      ├─ metadata        │   │
│  │  └─ updated_at        └─ timestamp       └─ updated_at      │   │
│  │                                                              │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                    AGENT TABLES                              │   │
│  │                                                              │   │
│  │  agent_tasks          tool_executions    agent_sessions     │   │
│  │  ├─ id                ├─ id              ├─ id              │   │
│  │  ├─ session_id        ├─ task_id         ├─ conversation_id │   │
│  │  ├─ parent_id         ├─ tool_name       ├─ agent_type      │   │
│  │  ├─ status            ├─ input           ├─ status          │   │
│  │  ├─ result            ├─ output          ├─ context         │   │
│  │  └─ timestamps        ├─ duration_ms     └─ timestamps      │   │
│  │                       └─ error                              │   │
│  │                                                              │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                    VECTOR EXTENSION (pgvector)               │   │
│  │                                                              │   │
│  │  message_embeddings     document_embeddings                  │   │
│  │  ├─ id                  ├─ id                                │   │
│  │  ├─ message_id          ├─ document_id                       │   │
│  │  ├─ embedding (1536)    ├─ chunk_index                       │   │
│  │  └─ model               ├─ embedding (1536)                  │   │
│  │                         └─ metadata                          │   │
│  │                                                              │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

### Caching Strategy

```
┌─────────────────────────────────────────────────────────────────────┐
│                         Redis Cache Layers                          │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  L1: Session Cache (TTL: 30 min)                             │   │
│  │  ├─ session:{session_id} → Session state                    │   │
│  │  ├─ context:{conversation_id} → Active context              │   │
│  │  └─ working:{user_id} → Working memory                      │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  L2: User Cache (TTL: 1 hour)                                │   │
│  │  ├─ user:{user_id}:prefs → User preferences                 │   │
│  │  ├─ user:{user_id}:history → Recent history                 │   │
│  │  └─ user:{user_id}:features → Feature flags                 │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  L3: Model Cache (TTL: 5 min)                                │   │
│  │  ├─ model:{hash} → Cached responses                         │   │
│  │  ├─ embedding:{hash} → Cached embeddings                    │   │
│  │  └─ provider:{name}:status → Provider health                │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  L4: Rate Limiting                                           │   │
│  │  ├─ ratelimit:{user_id}:api → API rate limits               │   │
│  │  ├─ ratelimit:{user_id}:tokens → Token limits               │   │
│  │  └─ ratelimit:{ip}:global → IP-based limits                 │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

---

## Communication Patterns

### Synchronous Communication

```
┌──────────────────────────────────────────────────────────────────┐
│                    REQUEST/RESPONSE FLOW                         │
│                                                                  │
│   Client        Gateway      Service        Provider            │
│     │              │            │              │                 │
│     │──── POST ───►│            │              │                 │
│     │              │─── Auth ──►│              │                 │
│     │              │◄── OK ────│              │                 │
│     │              │─── Req ───►│              │                 │
│     │              │            │─── API ─────►│                 │
│     │              │            │◄── Resp ────│                 │
│     │              │◄── Resp ──│              │                 │
│     │◄─── JSON ───│            │              │                 │
│     │              │            │              │                 │
└──────────────────────────────────────────────────────────────────┘
```

### Streaming Communication

```
┌──────────────────────────────────────────────────────────────────┐
│                    STREAMING FLOW (SSE/WebSocket)                │
│                                                                  │
│   Client        Gateway      Service        Provider            │
│     │              │            │              │                 │
│     │══ WebSocket ═►│            │              │                 │
│     │              │═══ Conn ══►│              │                 │
│     │              │            │═══ Stream ══►│                 │
│     │              │            │◄── Token ───│                 │
│     │              │◄── Token ──│              │                 │
│     │◄─── Token ───│            │              │                 │
│     │              │            │◄── Token ───│                 │
│     │              │◄── Token ──│              │                 │
│     │◄─── Token ───│            │              │                 │
│     │              │            │◄── [DONE] ──│                 │
│     │              │◄── [DONE] ─│              │                 │
│     │◄─── [DONE] ──│            │              │                 │
│     │              │            │              │                 │
└──────────────────────────────────────────────────────────────────┘
```

### Event-Driven Communication

```
┌──────────────────────────────────────────────────────────────────┐
│                    EVENT STREAMING (Kafka)                       │
│                                                                  │
│                      ┌─────────────────┐                         │
│                      │   Kafka Topics  │                         │
│                      └─────────────────┘                         │
│                              │                                   │
│    ┌─────────────────────────┼─────────────────────────┐         │
│    │                         │                         │         │
│    ▼                         ▼                         ▼         │
│ ┌──────────────┐     ┌──────────────┐     ┌──────────────┐       │
│ │ iris.events  │     │ iris.metrics │     │ iris.audit   │       │
│ │ - message    │     │ - usage      │     │ - access     │       │
│ │ - completion │     │ - latency    │     │ - changes    │       │
│ │ - error      │     │ - tokens     │     │ - tool_use   │       │
│ └──────────────┘     └──────────────┘     └──────────────┘       │
│        │                    │                    │               │
│        ▼                    ▼                    ▼               │
│   ┌─────────┐         ┌─────────┐         ┌─────────┐           │
│   │Analytics│         │Monitoring│         │ Audit   │           │
│   │ Service │         │ Service │         │ Service │           │
│   └─────────┘         └─────────┘         └─────────┘           │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
```

---

## Security Architecture

### Authentication & Authorization

```
┌─────────────────────────────────────────────────────────────────────┐
│                    SECURITY LAYERS                                  │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  LAYER 1: EDGE SECURITY                                      │   │
│  │  ├─ TLS 1.3 termination                                     │   │
│  │  ├─ DDoS protection                                          │   │
│  │  ├─ Rate limiting (per IP)                                   │   │
│  │  └─ WAF rules                                                │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                              │                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  LAYER 2: AUTHENTICATION                                     │   │
│  │  ├─ JWT validation (RS256)                                   │   │
│  │  ├─ API key authentication                                   │   │
│  │  ├─ OAuth 2.0 / OIDC                                        │   │
│  │  └─ Session management                                       │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                              │                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  LAYER 3: AUTHORIZATION                                      │   │
│  │  ├─ RBAC (Role-Based Access Control)                        │   │
│  │  ├─ Resource-level permissions                               │   │
│  │  ├─ Feature flags                                            │   │
│  │  └─ Usage quotas                                             │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                              │                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  LAYER 4: DATA SECURITY                                      │   │
│  │  ├─ Encryption at rest (AES-256)                            │   │
│  │  ├─ Encryption in transit (TLS)                             │   │
│  │  ├─ Field-level encryption (sensitive data)                 │   │
│  │  └─ Key management (Vault)                                   │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                              │                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  LAYER 5: AI SAFETY                                          │   │
│  │  ├─ Input sanitization                                       │   │
│  │  ├─ Output filtering                                         │   │
│  │  ├─ Tool execution sandboxing                               │   │
│  │  └─ Content policy enforcement                              │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

### Sensitive Data Handling

```
┌─────────────────────────────────────────────────────────────────────┐
│                  SENSITIVE DATA FLOW                                │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  INPUT HANDLING                                              │   │
│  │                                                              │   │
│  │  User Input ──► Sanitize ──► Classify ──► Route             │   │
│  │                     │            │                           │   │
│  │                     ▼            ▼                           │   │
│  │              [Strip PII]  [Sensitivity Level]                │   │
│  │                                                              │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  PROCESSING                                                  │   │
│  │                                                              │   │
│  │  ┌─────────────────┐  ┌─────────────────┐                   │   │
│  │  │ LOW SENSITIVITY │  │ HIGH SENSITIVITY │                   │   │
│  │  │ - Cloud models  │  │ - Local models   │                   │   │
│  │  │ - Standard logs │  │ - Encrypted logs │                   │   │
│  │  │ - Regular cache │  │ - No caching     │                   │   │
│  │  └─────────────────┘  └─────────────────┘                   │   │
│  │                                                              │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  LOGGING                                                     │   │
│  │                                                              │   │
│  │  Redacted Fields:                                            │   │
│  │  - password, secret, token, apiKey, api_key, apikey         │   │
│  │  - authorization, auth, credential, credentials              │   │
│  │  - privateKey, private_key, ssn, socialSecurityNumber       │   │
│  │  - creditCard, credit_card, cardNumber, card_number         │   │
│  │  - cvv, pin                                                  │   │
│  │                                                              │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

---

## Deployment Architecture

### Kubernetes Deployment

```text
                         production ingress
                    host: iris.oshun.dev / TLS
                                  |
                                  v
+-------------------------------------------------------------------+
| namespace: iris                                                   |
|                                                                   |
|  +-------------------+     +--------------------------+           |
|  | iris-api          |     | shared config/secrets    |           |
|  | replicas: 3       |<----+ iris-common-config       |           |
|  | HPA: 3-20         |     | iris-secrets             |           |
|  | probes: live/ready|     | iris-ai-secrets          |           |
|  +----+---------+----+     +--------------------------+           |
|       |         |                                                   |
|       |         +--------------------+                              |
|       |                              |                              |
|       v                              v                              |
| +-------------------+       +-------------------+                  |
| | iris-conversation |       | iris-agent        |                  |
| | replicas: 2       |       | replicas: 2       |                  |
| | HPA: 2-10         |       | HPA: 2-10         |                  |
| +---------+---------+       +---------+---------+                  |
|           |                           |                            |
|           v                           v                            |
| +-------------------+       +-------------------+                  |
| | iris-memory       |       | iris-worker       |                  |
| | replicas: 2       |       | replicas: 2       |                  |
| | HPA: 2-8          |       | HPA: service      |                  |
| | PVC: cache        |       | jobs/cleanup      |                  |
| +---------+---------+       +-------------------+                  |
|           |                                                       |
|           v                                                       |
| +-------------------+                                             |
| | iris-voice        |                                             |
| | replicas: 2       |                                             |
| | STT/TTS cache     |                                             |
| +-------------------+                                             |
|                                                                   |
| RBAC: iris-service for API/domain services, iris-worker for jobs   |
| Resilience: HPAs, VPAs, priority classes, production PDBs          |
+-------------------------------------------------------------------+
          |                         |                         |
          v                         v                         v
+-------------------+     +-------------------+     +-------------------+
| namespace:        |     | namespace:        |     | observability     |
| iris-data         |     | iris-data         |     | Prometheus,       |
| PostgreSQL, Redis |     | Qdrant            |     | Grafana, Jaeger   |
+-------------------+     +-------------------+     +-------------------+
```

### Environment Configuration

| Environment | Overlay                               | Service graph                                                                                                   | Operational profile                                                                                                |
| ----------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Development | `infra/k8s/iris/overlays/development` | All six services with local-friendly image tags and debug logging.                                              | Small replicas, fast feedback, rendered with the same base patches as staging and production.                      |
| Staging     | `infra/k8s/iris/overlays/staging`     | All six services with release-candidate image tags and production-like integrations.                            | Smoke-tested deployment path, full monitoring, representative secrets, and validation before production promotion. |
| Production  | `infra/k8s/iris/overlays/production`  | All six services with production image tags, ingress, HPAs, VPAs, PDBs, service accounts, and priority classes. | High availability, canary validation, rollback workflow, hardened secret and resource configuration.               |

### Container And Rollout Model

The container build pipeline publishes one image per service: `iris-api`,
`iris-conversation`, `iris-memory`, `iris-agent`, `iris-voice`, and
`iris-worker`. Kubernetes images are set through environment overlays, while the
production deployment workflow validates ECR image availability before mutating
manifests. The production rollout updates all six deployments, checks rollout
status, validates health endpoints, and rolls all affected deployments back if
smoke checks fail.

---

## Integration Architecture

### Cross-Domain Integration

```
┌─────────────────────────────────────────────────────────────────────┐
│                OSHUN ECOSYSTEM INTEGRATION                          │
│                                                                     │
│                         ┌─────────────┐                             │
│                         │    IRIS     │                             │
│                         │  (Central)  │                             │
│                         └──────┬──────┘                             │
│                                │                                    │
│    ┌───────────────────────────┼───────────────────────────┐        │
│    │                           │                           │        │
│    ▼                           ▼                           ▼        │
│ ┌──────────────┐       ┌──────────────┐       ┌──────────────┐      │
│ │    MAYA      │       │   YEMAYA     │       │   HATHOR     │      │
│ │  (Metaverse) │       │  (Creative)  │       │ (Worldbuild) │      │
│ │              │       │              │       │              │      │
│ │ - In-world   │       │ - Creative   │       │ - Lore       │      │
│ │   companion  │       │   assistant  │       │   consultant │      │
│ │ - Spatial    │       │ - Content    │       │ - World      │      │
│ │   awareness  │       │   generation │       │   generator  │      │
│ └──────────────┘       └──────────────┘       └──────────────┘      │
│                                                                     │
│    ┌───────────────────────────┼───────────────────────────┐        │
│    │                           │                           │        │
│    ▼                           ▼                           ▼        │
│ ┌──────────────┐       ┌──────────────┐       ┌──────────────┐      │
│ │    NYX       │       │   VERITAS    │       │   PSYCHE     │      │
│ │  (Astronomy) │       │   (News AI)  │       │ (Companion)  │      │
│ │              │       │              │       │              │      │
│ │ - Celestial  │       │ - News       │       │ - Emotional  │      │
│ │   guide      │       │   research   │       │   support    │      │
│ │ - Night sky  │       │ - Fact       │       │ - Personal   │      │
│ │   assistant  │       │   checking   │       │   companion  │      │
│ └──────────────┘       └──────────────┘       └──────────────┘      │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

### External API Integration

```
┌─────────────────────────────────────────────────────────────────────┐
│                  EXTERNAL INTEGRATIONS                              │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  AI PROVIDERS                                                │   │
│  │                                                              │   │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────────────┐     │   │
│  │  │ Anthropic  │  │   OpenAI   │  │  Google AI         │     │   │
│  │  │ - Claude   │  │   - GPT-5  │  │  - Gemini          │     │   │
│  │  │ - Vision   │  │   - DALL-E │  │  - PaLM            │     │   │
│  │  └────────────┘  └────────────┘  └────────────────────┘     │   │
│  │                                                              │   │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────────────┐     │   │
│  │  │  Cohere    │  │  Mistral   │  │  Local (Ollama)    │     │   │
│  │  │ - Embed    │  │  - Models  │  │  - Llama           │     │   │
│  │  │ - Rerank   │  │            │  │  - Mixtral         │     │   │
│  │  └────────────┘  └────────────┘  └────────────────────┘     │   │
│  │                                                              │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  SPEECH & VOICE                                              │   │
│  │                                                              │   │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────────────┐     │   │
│  │  │ ElevenLabs │  │  Whisper   │  │  Azure Speech      │     │   │
│  │  │ - TTS      │  │   - STT    │  │  - STT/TTS         │     │   │
│  │  │ - Cloning  │  │   - Trans  │  │  - Translation     │     │   │
│  │  └────────────┘  └────────────┘  └────────────────────┘     │   │
│  │                                                              │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  SEARCH & KNOWLEDGE                                          │   │
│  │                                                              │   │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────────────┐     │   │
│  │  │ Tavily     │  │ Serper     │  │  Wolfram Alpha     │     │   │
│  │  │ - Search   │  │  - Search  │  │  - Computation     │     │   │
│  │  │ - Extract  │  │  - News    │  │  - Facts           │     │   │
│  │  └────────────┘  └────────────┘  └────────────────────┘     │   │
│  │                                                              │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

---

## Observability Architecture

Iris observability is defined as deployable Kubernetes resources under
`infra/monitoring/iris` and runtime SDK configuration under `libs/iris/core`.
All six services participate in the same signal model.

| Signal  | Runtime implementation                                                                                                     | Cluster implementation                                                                                                                                    | Primary consumers                                    |
| ------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| Metrics | Service `/metrics` endpoints and service-level counters/histograms.                                                        | `ServiceMonitor` objects for `iris-api`, `iris-conversation`, `iris-memory`, `iris-agent`, `iris-voice`, and `iris-worker`; recording and alerting rules. | Prometheus, Alertmanager, Grafana                    |
| Traces  | `initializeTracingFromEnv`, API tracing middleware, W3C `traceparent`/`tracestate`, Iris request IDs, graceful shutdown.   | `OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger.observability.svc.cluster.local:4318/v1/traces` injected into every deployment.                                | Jaeger and OTLP-compatible backends                  |
| Logs    | Structured JSON logger, sensitive-field redaction, child loggers, flush/shutdown hooks, env-driven aggregation transports. | `LOG_FORMAT=json`, Loki URL, Elasticsearch bulk URL/index prefix, CloudWatch-compatible group, and retention days injected through `iris-common-config`.  | Loki, Elasticsearch, CloudWatch-compatible ingestion |

### Metrics Collection

```
┌─────────────────────────────────────────────────────────────────────┐
│                    METRICS PIPELINE                                 │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  SERVICE METRICS (Prometheus)                                │   │
│  │                                                              │   │
│  │  RED Metrics (Request, Error, Duration):                     │   │
│  │  - iris_api_requests_total                                  │   │
│  │  - iris_conversation_requests_total                         │   │
│  │  - iris_memory_operations_total                             │   │
│  │  - iris_agent_task_duration_seconds                         │   │
│  │  - iris_voice_request_duration_seconds                      │   │
│  │  - iris_worker_job_duration_seconds                         │   │
│  │                                                              │   │
│  │  USE Metrics (Utilization, Saturation, Errors):             │   │
│  │  - iris_cpu_utilization                                     │   │
│  │  - iris_memory_utilization                                  │   │
│  │  - iris_connection_pool_usage                               │   │
│  │                                                              │   │
│  │  Business Metrics:                                           │   │
│  │  - iris_tokens_consumed_total{provider, model}              │   │
│  │  - iris_conversation_turns_total                            │   │
│  │  - iris_active_sessions                                     │   │
│  │  - iris_tool_executions_total{tool, status}                 │   │
│  │  - iris_voice_tokens_total{provider, operation}             │   │
│  │  - iris_worker_jobs_total{queue, status}                    │   │
│  │                                                              │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  SLI/SLO TRACKING                                            │   │
│  │                                                              │   │
│  │  Availability SLO: 99.9%                                    │   │
│  │  - iris:availability = successful / total                   │   │
│  │                                                              │   │
│  │  Latency SLO: p95 < 3s                                      │   │
│  │  - iris:latency:p95                                         │   │
│  │                                                              │   │
│  │  Error Budget:                                               │   │
│  │  - iris:error_budget_remaining                              │   │
│  │  - iris:error_budget_burn_rate                              │   │
│  │                                                              │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

### Distributed Tracing

```
┌─────────────────────────────────────────────────────────────────────┐
│                    TRACING ARCHITECTURE                             │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  TRACE FLOW (OpenTelemetry)                                  │   │
│  │                                                              │   │
│  │  ┌──────────────────────────────────────────────────────┐   │   │
│  │  │  Request Span                                        │   │   │
│  │  │  ├── Authentication Span                             │   │   │
│  │  │  ├── Rate Limiting Span                              │   │   │
│  │  │  ├── Conversation Processing Span                    │   │   │
│  │  │  │   ├── Intent Recognition Span                     │   │   │
│  │  │  │   ├── Context Retrieval Span                      │   │   │
│  │  │  │   │   ├── Memory Query Span                       │   │   │
│  │  │  │   │   └── RAG Retrieval Span                      │   │   │
│  │  │  │   ├── Model Routing Span                          │   │   │
│  │  │  │   └── AI Provider Span                            │   │   │
│  │  │  │       ├── Request Span                            │   │   │
│  │  │  │       └── Streaming Span                          │   │   │
│  │  │  └── Response Formatting Span                        │   │   │
│  │  └──────────────────────────────────────────────────────┘   │   │
│  │                                                              │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  SPAN ATTRIBUTES                                             │   │
│  │                                                              │   │
│  │  Common:                                                     │   │
│  │  - iris.request_id, iris.session_id, iris.conversation_id   │   │
│  │  - iris.user_id, iris.agent_id, iris.operation              │   │
│  │                                                              │   │
│  │  AI Provider:                                                │   │
│  │  - ai.provider, ai.model, ai.request_type                   │   │
│  │  - ai.tokens_input, ai.tokens_output, ai.streaming          │   │
│  │  - ai.temperature, ai.max_tokens                            │   │
│  │                                                              │   │
│  │  Tool Execution:                                             │   │
│  │  - iris.tool_name, iris.tool_type, iris.tool_success        │   │
│  │                                                              │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

### Logging Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                    LOGGING PIPELINE                                 │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  STRUCTURED LOGGING                                          │   │
│  │                                                              │   │
│  │  Log Entry Structure:                                        │   │
│  │  {                                                           │   │
│  │    "level": "info",                                          │   │
│  │    "timestamp": "2026-02-02T19:00:00.000Z",                  │   │
│  │    "service": "iris-conversation",                           │   │
│  │    "version": "1.0.0",                                       │   │
│  │    "message": "Conversation completed",                      │   │
│  │    "requestId": "req-abc123",                                │   │
│  │    "traceId": "trace-xyz789",                                │   │
│  │    "spanId": "span-def456",                                  │   │
│  │    "userId": "user-123",                                     │   │
│  │    "conversationId": "conv-789",                             │   │
│  │    "context": {                                              │   │
│  │      "model": "claude-3-opus",                               │   │
│  │      "tokens": 1500,                                         │   │
│  │      "duration_ms": 2340                                     │   │
│  │    }                                                         │   │
│  │  }                                                           │   │
│  │                                                              │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  LOG AGGREGATION                                             │   │
│  │                                                              │   │
│  │  ┌─────────────┐       ┌─────────────┐                     │   │
│  │  │   Stdout    │──────►│ Kubernetes  │                     │   │
│  │  │   JSON      │       │ log stream  │                     │   │
│  │  └──────┬──────┘       └─────────────┘                     │   │
│  │         │                                                   │   │
│  │         ├────────► Loki push API                            │   │
│  │         ├────────► Elasticsearch bulk API                   │   │
│  │         └────────► CloudWatch-compatible log events         │   │
│  │                                                              │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

---

## Appendix

### Configuration Reference

#### Environment Variables

| Variable            | Description                    | Default       |
| ------------------- | ------------------------------ | ------------- |
| `IRIS_ENV`          | Environment (dev/staging/prod) | `development` |
| `IRIS_LOG_LEVEL`    | Logging level                  | `info`        |
| `IRIS_SERVICE_NAME` | Service identifier             | `iris`        |
| `ANTHROPIC_API_KEY` | Anthropic API key              | -             |
| `OPENAI_API_KEY`    | OpenAI API key                 | -             |
| `GOOGLE_AI_API_KEY` | Google AI API key              | -             |
| `DATABASE_URL`      | PostgreSQL connection string   | -             |
| `REDIS_URL`         | Redis connection string        | -             |
| `QDRANT_URL`        | Qdrant vector DB URL           | -             |
| `JAEGER_ENDPOINT`   | Jaeger tracing endpoint        | -             |
| `KAFKA_BROKERS`     | Kafka broker addresses         | -             |

### API Endpoints

| Endpoint                          | Method | Description               |
| --------------------------------- | ------ | ------------------------- |
| `/v1/chat/completions`            | POST   | Create chat completion    |
| `/v1/conversations`               | GET    | List conversations        |
| `/v1/conversations/{id}`          | GET    | Get conversation          |
| `/v1/conversations/{id}/messages` | GET    | Get conversation messages |
| `/v1/memory/query`                | POST   | Query memory              |
| `/v1/agents/tasks`                | POST   | Create agent task         |
| `/v1/agents/tasks/{id}`           | GET    | Get task status           |
| `/health`                         | GET    | Health check              |
| `/metrics`                        | GET    | Prometheus metrics        |

### Glossary

| Term    | Definition                                     |
| ------- | ---------------------------------------------- |
| **STM** | Short-Term Memory - current session context    |
| **LTM** | Long-Term Memory - persistent user preferences |
| **RAG** | Retrieval-Augmented Generation                 |
| **MCP** | Model Context Protocol                         |
| **A2A** | Agent-to-Agent protocol                        |
| **SLI** | Service Level Indicator                        |
| **SLO** | Service Level Objective                        |
| **HPA** | Horizontal Pod Autoscaler                      |

---

_Last updated: 2026-02-02_

_Version: 1.0.0_
