# Iris Developer Guide

> 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](#local-development-setup)
2. [Project Structure](#project-structure)
3. [TypeScript Development Workflow](#typescript-development-workflow)
4. [Testing Procedures](#testing-procedures)
5. [Debugging](#debugging)
6. [Code Standards](#code-standards)
7. [Contribution Guidelines](#contribution-guidelines)
8. [Common Tasks](#common-tasks)
9. [Troubleshooting](#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_
