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#
- Overview
- Current Implementation Baseline
- High-Level Architecture
- Core Components
- Service Architecture
- Data Architecture
- Communication Patterns
- Security Architecture
- Deployment Architecture
- Integration 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#
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#
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.
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.
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#
- Privacy-First: On-device processing where possible, end-to-end encryption
- Multi-Model: Intelligent routing across multiple AI providers
- Hierarchical Memory: Four-tier memory system for true personalization
- Agentic: Autonomous task execution with appropriate guardrails
- Observable: Comprehensive logging, tracing, and metrics
- 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#
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