Eve library

Iris Developer Guide

Guide

Revision 1

On this page

Local development, workflow, testing, debugging, and contribution guide for the Iris Universal Intelligent Assistant Platform.

This guide is grounded in the current monorepo layout, Nx targets, Docker Compose files, Iris API implementation, Kubernetes manifests, and SDK package structure.

Table Of Contents#

  1. Local Development Setup
  2. Project Structure
  3. TypeScript Development Workflow
  4. Testing Procedures
  5. Debugging
  6. Code Standards
  7. Contribution Guidelines
  8. Common Tasks
  9. Troubleshooting

Local Development Setup#

Prerequisites#

Tool Required Recommended Purpose
Node.js >=20 22.x TypeScript runtime, Nx, API service.
pnpm >=9 10.25.0 from packageManager Workspace package manager.
Git >=2.40 Current stable Source control.
Docker >=24 Current stable Local infrastructure and container builds.
Docker Compose >=2.20 Current stable Local Postgres, Redis, Qdrant, observability.
Rust Optional Current stable Tauri desktop and native modules.
Java/Kotlin tooling Optional Current stable Android/Kotlin surfaces.

Recommended editor setup:

  • VS Code or a JetBrains IDE with TypeScript, ESLint, Prettier, and Nx support.
  • Docker extension or another local container monitor.
  • A REST client such as Bruno, Insomnia, or curl/httpie.
  • A database client for Postgres inspection.

Quick Start#

bash
pnpm install

# Local shared infrastructure
docker compose -f docker/docker-compose.dev.yml up -d

# Iris-specific infrastructure and service dependencies when needed
docker compose -f docker/docker-compose.iris.yml up -d

# Build and test the current API dependencies
pnpm nx build @iris/core --skip-nx-cache
pnpm nx test @iris/api --runInBand --skip-nx-cache

# Start the API in watch mode
pnpm nx serve @iris/api

The API listens on http://localhost:3000 by default. REST routes are mounted under /api/v1, GraphQL is mounted at /graphql, docs are mounted under /docs, and health is available at /health.

Environment#

For local API work, start with the app example env and add provider keys only when the code path needs them:

bash
cp apps/iris/api/.env.example apps/iris/api/.env

Common variables:

Variable Purpose
IRIS_DATABASE_URL or DATABASE_URL Postgres connection string.
REDIS_URL Redis connection string.
IRIS_QDRANT_URL or QDRANT_URL Qdrant vector database URL.
ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_AI_API_KEY Model/provider access.
LOG_LEVEL, LOG_FORMAT Local logging behavior.
IRIS_TRACING_ENABLED, OTEL_EXPORTER_OTLP_ENDPOINT Local tracing export.
IRIS_CONVERSATION_STATE_FILE, IRIS_MEMORY_STATE_FILE, IRIS_AGENT_STATE_FILE, IRIS_KNOWLEDGE_STATE_FILE Durable JSON state files for local API services.

The API services include durable JSON state stores for local development and tests. Production deployments use the configured backing services described in the architecture and Kubernetes docs.

Local Infrastructure#

Useful Compose files:

File Purpose
docker/docker-compose.dev.yml Shared development stack.
docker/docker-compose.iris.yml Iris-specific runtime dependencies.
docker/docker-compose.test.yml Test infrastructure.
docker/iris/* Iris service Dockerfiles and runtime wrapper.

Database initialization lives under docker/init-scripts, including docker/init-scripts/iris-init.sql.

Project Structure#

Iris is split across applications, domain libraries, platform utilities, infrastructure, and documentation.

text
apps/iris/
  api/                 Hono REST, GraphQL Yoga, docs, middleware, route services
  dashboard/           Dashboard/data service package
  desktop/             Tauri desktop application
  developer-portal/    Developer portal features and tests
  marketplace/         Agent/plugin marketplace features
  mobile/              Mobile application package

libs/iris/
  core/                Logging, tracing, context, errors, config foundation
  config/              Configuration utilities
  contracts/           Shared API/domain contracts where present
  types/               Shared TypeScript types
  conversation-*       Conversation engine, state, context, RAG, providers
  memory/*             Memory subsystems and migrations
  agents/*             Agents, tools, computer-use, and orchestration packages
  knowledge/*          Knowledge and RAG subsystems
  sdk/typescript/      Implemented TypeScript SDK
  platform/*           SDK docs/codegen/testing/versioning and platform utilities
  model-routing/       Model selection and routing
  failover/            Circuit breakers and fallback behavior
  ensemble/            Multi-model aggregation
  mcp/, a2a/           Protocol integrations

infra/k8s/iris/        Kustomize base and overlays for six Iris services
infra/monitoring/iris/ Prometheus, Grafana, recording rules, and alerts
docker/iris/           Service Dockerfiles and runtime wrapper
docs/domains/iris/     User, developer, API, SDK, architecture, privacy docs

There are six registered Iris applications under apps/iris and well over 38 Iris library packages under libs/iris, with hundreds of registered nested subprojects for specialized subsystems. Use Nx project names instead of paths when running builds/tests.

Discover projects:

bash
pnpm nx show projects | rg '^@iris/'
pnpm nx show project @iris/api
pnpm nx show project @iris/sdk

TypeScript Development Workflow#

Build#

bash
pnpm nx build @iris/core --skip-nx-cache
pnpm nx build @iris/api --skip-nx-cache
pnpm nx build @iris/sdk --skip-nx-cache

Test#

bash
pnpm nx test @iris/core --runInBand --skip-nx-cache
pnpm nx test @iris/api --runInBand --skip-nx-cache
pnpm nx test @iris/sdk --runInBand --skip-nx-cache

Lint#

bash
pnpm nx lint @iris/core --skip-nx-cache
pnpm nx lint @iris/api --skip-nx-cache
pnpm nx lint @iris/sdk --skip-nx-cache

Typecheck#

Run explicit typecheck targets when present:

bash
pnpm nx typecheck @iris/core --skip-nx-cache
pnpm nx typecheck @iris/sdk --skip-nx-cache

For projects without a typecheck target, the build target is the type safety gate.

Affected Iris Commands#

The root scripts wrap affected Iris project discovery:

bash
pnpm iris:affected
pnpm iris:affected:build
pnpm iris:affected:test
pnpm iris:affected:lint
pnpm iris:affected:typecheck
pnpm iris:affected:integration

Kubernetes And Container Validation#

bash
npx --yes kustomize build infra/k8s/iris
npx --yes kustomize build infra/k8s/iris/overlays/staging
npx --yes kustomize build infra/k8s/iris/overlays/production

docker build -f docker/iris/Dockerfile.api .
docker build -f docker/iris/Dockerfile.conversation .
docker build -f docker/iris/Dockerfile.memory .
docker build -f docker/iris/Dockerfile.agent .
docker build -f docker/iris/Dockerfile.voice .
docker build -f docker/iris/Dockerfile.worker .

Testing Procedures#

Unit Tests#

Use focused project tests while iterating:

bash
pnpm nx test @iris/api --runInBand --skip-nx-cache

Add or update tests next to the changed module. API route/service tests belong under apps/iris/api/src/**/*.test.ts; core tests belong under libs/iris/core/src/**/*.test.ts; SDK tests belong under libs/iris/sdk/typescript/src/**/*.spec.ts.

Integration And Contract Tests#

Run integration/contract tests when changing APIs, shared contracts, persistence, assistant behavior, media/model pipelines, or release gates:

bash
pnpm test:integration:flows
pnpm test:integration:contracts
pnpm openapi:validate
pnpm codegen:schema:check
pnpm codegen:proto:check

Only run broad workspace commands after checking host resources:

bash
free -h
nproc
ps -eo pid,ppid,cmd,%mem,%cpu --sort=-%mem | head -40

Use conservative Nx parallelism for broad sweeps:

bash
pnpm nx run-many --target=test --projects=@iris/api,@iris/core,@iris/sdk --parallel=2 --nxBail

UI Tests#

For UI-changing work, add or update Playwright coverage when the flow is automatable. Run the relevant app server first, then run the specific Playwright spec or affected e2e target. Capture screenshots for visual signoff on material UI changes.

Documentation Checks#

bash
pnpm prettier --check docs/domains/iris/**/*.md TODOS/phase-54.md
git diff --check

The repo-wide pnpm domains:check currently reports pre-existing source coverage registry gaps unrelated to Iris doc edits. Treat its output as a known workspace-level blocker until the registry is repaired.

Debugging#

API#

bash
LOG_LEVEL=debug pnpm nx serve @iris/api
curl http://localhost:3000/health
curl http://localhost:3000/health/ready

Debug route behavior by inspecting:

  • apps/iris/api/src/index.ts for mount points and middleware order.
  • apps/iris/api/src/routes/*.ts for REST route validation.
  • apps/iris/api/src/graphql/schema.ts for GraphQL schema.
  • apps/iris/api/src/services/*.ts for durable state and domain behavior.

VS Code#

Use a Node attach/launch configuration similar to:

json
{
  "type": "node",
  "request": "launch",
  "name": "Iris API",
  "runtimeExecutable": "pnpm",
  "runtimeArgs": ["nx", "serve", "@iris/api"],
  "console": "integratedTerminal",
  "skipFiles": ["<node_internals>/**"]
}

Database And Redis#

bash
docker compose -f docker/docker-compose.dev.yml ps
docker compose -f docker/docker-compose.dev.yml logs postgres
docker compose -f docker/docker-compose.dev.yml logs redis

docker exec -it oshun-dev-postgres psql -U oshun -d iris
docker exec -it oshun-dev-redis redis-cli

Container names can vary by Compose project name; use docker ps when the commands above do not match your local names.

Tracing And Logging#

bash
IRIS_TRACING_ENABLED=true \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces \
LOG_LEVEL=debug \
LOG_FORMAT=json \
pnpm nx serve @iris/api

Use request IDs and traceparent headers to correlate API logs, traces, and client reports.

Code Standards#

  • Keep changes scoped to the requested behavior and adjacent tests.
  • Prefer existing Iris packages, route patterns, service classes, and shared core utilities over new abstractions.
  • Use Zod for request validation in API routes.
  • Use typed errors and middleware error handling instead of ad hoc response shapes.
  • Use structured logging from @iris/core/logging; do not log secrets, credentials, tokens, or raw sensitive memory content.
  • Use tracing helpers from @iris/core/tracing for request and service spans.
  • Keep TypeScript strict and explicit at package boundaries.
  • Use rg for search and Nx project targets for verification.
  • Keep docs implementation-aligned: document active surfaces separately from planned contracts.

Contribution Guidelines#

  1. Start from the current branch tip and inspect existing implementations before editing.
  2. Make the smallest coherent change that completes the task.
  3. Add or update tests for behavior changes.
  4. Run focused verification first, then broader affected checks when needed.
  5. Format Markdown, YAML, JSON, and TypeScript with the repo Prettier config.
  6. Do not commit generated artifacts unless the project target expects them.
  7. Use clear, task-scoped commit messages.
  8. Keep the worktree clean after each committed task.

For phase work, update TODOS/phase-54.md only for the task being completed and do not move into a later phase.

Common Tasks#

Add A REST Endpoint#

  1. Add the route and Zod schema in apps/iris/api/src/routes/<area>.ts.
  2. Add service behavior in apps/iris/api/src/services/<area>.service.ts.
  3. Add route/service tests.
  4. Update docs/domains/iris/api/README.md when the public API changes.
  5. Run API test, lint, and build targets.

Add A GraphQL Field#

  1. Update apps/iris/api/src/graphql/schema.ts.
  2. Update resolver/data source wiring.
  3. Add or update GraphQL tests.
  4. Update API documentation.

Add A Provider Or Model Option#

  1. Add config and secret handling.
  2. Add provider adapter or routing logic.
  3. Add failover/circuit-breaker behavior when applicable.
  4. Update API/SDK docs for model selection behavior.
  5. Run model-routing/provider tests.

Add Memory Behavior#

  1. Update the correct memory service or library package.
  2. Preserve tier semantics: core, working, archival, episodic, semantic.
  3. Add persistence and retrieval tests.
  4. Verify redaction and privacy controls for sensitive content.

Add A Kubernetes Service Change#

  1. Update infra/k8s/iris/base.
  2. Update staging/production overlays only when environment behavior differs.
  3. Render Kustomize for base and affected overlays.
  4. Update monitoring resources if the service, labels, or ports changed.

Troubleshooting#

| Symptom | Likely cause | Fix | | ----------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------- | | pnpm install fails on peer dependencies | Workspace/catalog mismatch or stale store | Run pnpm install from repo root; clear only pnpm cache if necessary. | | Nx cannot find a project | Wrong project name or nested package | Run pnpm nx show projects | rg iris and use the Nx project name. | | API starts but routes 404 | Wrong mount prefix | REST uses /api/v1; GraphQL uses /graphql; health uses /health. | | API readiness fails | Missing env var or dependency | Check /health/ready, Compose logs, and required IRIS_DATABASE_URL, REDIS_URL, IRIS_QDRANT_URL. | | Tests hang | Open handles from streams/timers | Ensure streams are closed, abort controllers are triggered, and services shut down. | | Kustomize render fails | Invalid patch path or label selector | Render infra/k8s/iris first, then overlays; inspect generated YAML. | | Lint passes with warnings | Existing warnings in touched package | Do not expand warnings; fix warnings only when in scope. | | pnpm domains:check fails | Known registry gaps in DOMAINS/README.md and phase ownership metadata | Record as a workspace blocker unless your task is to repair the registry. |

Last updated: 2026-04-28