Disciplines · Reference

Frequently Asked Questions

Oshun is a monorepo containing AI-powered creative tools organized into multiple domains.

8sections3 minread
Markdown source
On this page

General#

What is Oshun?#

Oshun is a monorepo containing AI-powered creative tools organized into multiple domains. The 13 application domains include: Iris (AI assistant), Lilith (consciousness), Yemaya (creative studio), Isis (generation), Sophia (knowledge), Hathor (worldbuilding), Bellona (engines), Tara (meditation), Veritas (fact-checking), Psyche (mental health), Nyx (astronomy), Aja (motion AI), and Aphrodite (live streaming). Additional library-only domains provide cross-cutting capabilities like governance (Themis), blockchain (Aje), robotics (Galatea), and more.

Why a monorepo?#

  • Shared code: Easy to share libraries and utilities
  • Atomic changes: Changes across multiple packages in one PR
  • Consistent tooling: Same build, test, and lint setup everywhere
  • Dependency management: Single lockfile, consistent versions

What is Nx?#

Nx is a build system that provides:

  • Smart caching for faster builds
  • Affected commands to only build/test what changed
  • Dependency graph visualization
  • Code generators

Development#

How do I run a specific service?#

bash
pnpm nx dev @domain/service-name

How do I run all services?#

bash
pnpm dev

How do I add a new dependency?#

bash
# Add to a specific project
cd apps/domain/my-app
pnpm add package-name

# Add to root (dev dependency for all)
pnpm add -D -w package-name

For shared dependencies, prefer using the catalog: reference in pnpm-workspace.yaml to maintain consistent versions across the monorepo.

How do I use a shared library?#

Import directly using the TypeScript path mapping — no need to add workspace dependencies manually for @oshun/* packages:

typescript
import { something } from '@oshun/database';

For domain libraries, use the domain prefix:

typescript
import { something } from '@iris/conversation-core';

Why is my build failing?#

Common causes:

  1. Missing dependencies: Run pnpm install
  2. Stale cache: Run pnpm nx reset
  3. TypeScript errors: Run pnpm nx typecheck @project/name
  4. Circular dependencies: Check with pnpm graph

How do I clear the Nx cache?#

bash
pnpm nx reset

How do I see what's affected by my changes?#

bash
pnpm nx affected --graph

How do I update dependencies?#

bash
# Update all dependencies
pnpm update

# Update a specific dependency
pnpm update package-name

# Update to latest (including major versions)
pnpm update --latest

Architecture#

How do domains communicate?#

  • REST APIs: For external/public communication
  • Events: For async communication via Redis Streams and BullMQ queues
  • gRPC: For internal high-performance calls

Can I import from another domain?#

Only through the domain's public client library or shared contracts:

typescript
// WRONG - direct import from another domain's internals
import { something } from '@isis/generation-api/src/internal';

// CORRECT - through domain client
import { IsisClient } from '@isis/client';

// CORRECT - through shared contracts
import { AssetReference } from '@oshun/contracts-types';

How are module boundaries enforced?#

Nx module boundaries via project tags in project.json:

json
{
  "tags": ["scope:iris", "type:lib", "layer:domain"]
}

Domain libraries can only depend on their own domain and shared libraries.

Where should I put shared code?#

  • Domain-specific: libs/{domain}/
  • Cross-domain utilities: libs/shared/
  • Contracts/types: libs/contracts/

Testing#

How do I run tests?#

bash
# All tests
pnpm test

# Specific project
pnpm nx test @project/name

# With coverage
pnpm nx test @project/name --coverage

# Watch mode
pnpm nx test @project/name --watch

How do I run integration tests?#

bash
pnpm nx e2e @project/name-e2e

How do I debug tests?#

Add --inspect flag:

bash
node --inspect ./node_modules/.bin/vitest run

Database#

How do I create a migration?#

bash
cd libs/{domain}/database
npx prisma migrate dev --name migration_name

How do I apply migrations?#

bash
npx prisma migrate deploy

How do I reset the database?#

bash
npx prisma migrate reset

How do I view the database?#

bash
npx prisma studio

Docker#

How do I start infrastructure?#

bash
docker compose -f docker/docker-compose.dev.yml up -d

How do I check logs?#

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

How do I start optional services?#

bash
# Elasticsearch, Qdrant, Kafka, Neo4j, or all
docker compose -f docker/docker-compose.dev.yml --profile search up -d
docker compose -f docker/docker-compose.dev.yml --profile all up -d

How do I reset infrastructure?#

bash
# Stop and remove all data
docker compose -f docker/docker-compose.dev.yml down -v
# Start fresh
docker compose -f docker/docker-compose.dev.yml up -d

Deployment#

How is deployment handled?#

Each domain has its own deployment pipeline defined in .github/workflows/. Pushes to main trigger CI. Domain-specific deployment workflows handle staging and production deployments. See docs/infrastructure/deployment.md for details.

How do I rollback?#

See the Rollback Procedures for detailed instructions covering ECS deployments, database migrations, and other rollback scenarios.

Troubleshooting#

"Module not found" error#

  1. Check the import path is correct
  2. Run pnpm install
  3. Check path mappings in tsconfig.base.json
  4. Restart your IDE

"Port already in use"#

bash
# Find the process
lsof -i :3000

# Kill it
kill -9 <PID>

TypeScript errors in IDE but build passes#

  1. Restart TypeScript server (in VS Code: Cmd+Shift+P > "TypeScript: Restart TS Server")
  2. Reload window
  3. Check you have the right TypeScript version

Nx commands are slow#

  1. Use pnpm nx affected instead of running everything
  2. Check your disk space
  3. Run pnpm nx reset to clear stale cache

Can't find a command#

List all available targets:

bash
pnpm nx show project @project/name