# Frequently Asked Questions

## 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](./rollback-procedures.md) 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
```