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#
- Local Development Setup
- Project Structure
- TypeScript Development Workflow
- Testing Procedures
- Debugging
- Code Standards
- Contribution Guidelines
- Common Tasks
- 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#
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:
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.
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:
pnpm nx show projects | rg '^@iris/'
pnpm nx show project @iris/api
pnpm nx show project @iris/sdk
TypeScript Development Workflow#
Build#
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#
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#
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:
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:
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#
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:
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:
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:
free -h
nproc
ps -eo pid,ppid,cmd,%mem,%cpu --sort=-%mem | head -40
Use conservative Nx parallelism for broad sweeps:
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#
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#
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.tsfor mount points and middleware order.apps/iris/api/src/routes/*.tsfor REST route validation.apps/iris/api/src/graphql/schema.tsfor GraphQL schema.apps/iris/api/src/services/*.tsfor durable state and domain behavior.
VS Code#
Use a Node attach/launch configuration similar to:
{
"type": "node",
"request": "launch",
"name": "Iris API",
"runtimeExecutable": "pnpm",
"runtimeArgs": ["nx", "serve", "@iris/api"],
"console": "integratedTerminal",
"skipFiles": ["<node_internals>/**"]
}
Database And Redis#
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#
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/tracingfor request and service spans. - Keep TypeScript strict and explicit at package boundaries.
- Use
rgfor search and Nx project targets for verification. - Keep docs implementation-aligned: document active surfaces separately from planned contracts.
Contribution Guidelines#
- Start from the current branch tip and inspect existing implementations before editing.
- Make the smallest coherent change that completes the task.
- Add or update tests for behavior changes.
- Run focused verification first, then broader affected checks when needed.
- Format Markdown, YAML, JSON, and TypeScript with the repo Prettier config.
- Do not commit generated artifacts unless the project target expects them.
- Use clear, task-scoped commit messages.
- 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#
- Add the route and Zod schema in
apps/iris/api/src/routes/<area>.ts. - Add service behavior in
apps/iris/api/src/services/<area>.service.ts. - Add route/service tests.
- Update
docs/domains/iris/api/README.mdwhen the public API changes. - Run API test, lint, and build targets.
Add A GraphQL Field#
- Update
apps/iris/api/src/graphql/schema.ts. - Update resolver/data source wiring.
- Add or update GraphQL tests.
- Update API documentation.
Add A Provider Or Model Option#
- Add config and secret handling.
- Add provider adapter or routing logic.
- Add failover/circuit-breaker behavior when applicable.
- Update API/SDK docs for model selection behavior.
- Run model-routing/provider tests.
Add Memory Behavior#
- Update the correct memory service or library package.
- Preserve tier semantics: core, working, archival, episodic, semantic.
- Add persistence and retrieval tests.
- Verify redaction and privacy controls for sensitive content.
Add A Kubernetes Service Change#
- Update
infra/k8s/iris/base. - Update staging/production overlays only when environment behavior differs.
- Render Kustomize for base and affected overlays.
- 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