Eve library

Iris Domain Architecture

Guide

Revision 1

On this page

Canonical source: the canonical architecture document for this domain is 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
  2. Current Implementation Baseline
  3. High-Level Architecture
  4. Core Components
  5. Service Architecture
  6. Data Architecture
  7. Communication Patterns
  8. Security Architecture
  9. Deployment Architecture
  10. Integration Architecture
  11. 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#

text
┌─────────────────────────────────────────────────────────────────────────────┐
│                              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#

text
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.

text
┌─────────────────────────────────────────────────────────────────────┐
│                     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.

text
┌─────────────────────────────────────────────────────────────────────┐
│                       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.

text
┌─────────────────────────────────────────────────────────────────────┐
│                        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#

text
┌─────────────────────────────────────────────────────────────────────┐
│                      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#

text
┌─────────────────────────────────────────────────────────────────────┐
│                         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#

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

Streaming Communication#

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

Event-Driven Communication#

text
┌──────────────────────────────────────────────────────────────────┐
│                    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#

text
┌─────────────────────────────────────────────────────────────────────┐
│                    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#

text
┌─────────────────────────────────────────────────────────────────────┐
│                  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#

text
┌─────────────────────────────────────────────────────────────────────┐
│                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#

text
┌─────────────────────────────────────────────────────────────────────┐
│                  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#

text
┌─────────────────────────────────────────────────────────────────────┐
│                    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#

text
┌─────────────────────────────────────────────────────────────────────┐
│                    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#

text
┌─────────────────────────────────────────────────────────────────────┐
│                    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