# Getting Started with Oshun

This guide will help you set up your development environment and get started
with the Oshun monorepo.

## Prerequisites

Before you begin, ensure you have the following installed:

- **Node.js 20+** - JavaScript runtime
- **pnpm 10+** - Package manager (specified via `packageManager` in root
  `package.json`)
- **Git** - Version control
- **Docker** - For running infrastructure services locally (PostgreSQL, Redis,
  MinIO, Mailpit)

## Installation

### 1. Clone the Repository

```bash
git clone git@github.com:GreyChimp/oshun.git
cd oshun
```

### 2. Install Dependencies

```bash
pnpm install
```

This will install all dependencies for all projects in the monorepo.

### 3. Start Infrastructure Services

Start the local development infrastructure using Docker Compose:

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

This starts:

| Service    | Port(s)    | Purpose                          |
| ---------- | ---------- | -------------------------------- |
| PostgreSQL | 5432       | Primary database (with pgvector) |
| Redis      | 6379       | Caching and queues               |
| MinIO      | 9000, 9001 | S3-compatible object storage     |
| Mailpit    | 1025, 8025 | Local email testing              |

Verify all services are healthy:

```bash
docker compose -f docker/docker-compose.dev.yml ps
```

Optional infrastructure profiles are also available:

```bash
# Search (Elasticsearch)
docker compose -f docker/docker-compose.dev.yml --profile search up -d

# Vector database (Qdrant)
docker compose -f docker/docker-compose.dev.yml --profile vectors up -d

# Streaming (Kafka)
docker compose -f docker/docker-compose.dev.yml --profile streaming up -d

# Graph database (Neo4j)
docker compose -f docker/docker-compose.dev.yml --profile graph up -d

# Everything
docker compose -f docker/docker-compose.dev.yml --profile all up -d
```

### 4. Set Up Environment Variables

The root `.env` file contains all necessary environment variables for local
development. Copy from the example if needed:

```bash
cp .env.example .env
```

Key variables include:

```bash
# Database URLs
DATABASE_URL=postgresql://oshun:oshun_dev@localhost:5432/oshun_dev

# Redis
REDIS_URL=redis://localhost:6379

# MinIO (S3-compatible storage)
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
```

### 5. Verify Installation

```bash
# Build all projects
pnpm build

# Run tests
pnpm test

# Check the dependency graph
pnpm graph
```

## Project Structure

### Understanding Domains

Oshun is organized into multiple domains, each with specific responsibilities:

**Application Domains** (have both apps and libraries):

| Domain    | Scope Tag         | Purpose                                  |
| --------- | ----------------- | ---------------------------------------- |
| Iris      | `scope:iris`      | Universal AI assistant platform          |
| Lilith    | `scope:lilith`    | Conversational AI and consciousness      |
| Yemaya    | `scope:yemaya`    | Creative production workflows            |
| Isis      | `scope:isis`      | AI generation and workflow orchestration |
| Sophia    | `scope:sophia`    | Knowledge management and research        |
| Hathor    | `scope:hathor`    | Worldbuilding and narrative design       |
| Bellona   | `scope:bellona`   | Game engines and build systems           |
| Tara      | `scope:tara`      | Meditation and mindfulness platform      |
| Veritas   | `scope:veritas`   | Fact-checking and news verification      |
| Psyche    | `scope:psyche`    | Mental health and behavioral services    |
| Nyx       | `scope:nyx`       | Astronomical education and visualization |
| Aja       | `scope:aja`       | Motion AI and animation                  |
| Aphrodite | `scope:aphrodite` | Live streaming and performance platform  |

**Library-Only Domains** (libraries without standalone apps):

| Domain  | Scope Tag       | Purpose                        |
| ------- | --------------- | ------------------------------ |
| Aje     | `scope:aje`     | Blockchain and crypto          |
| Themis  | `scope:themis`  | Governance and compliance      |
| Galatea | `scope:galatea` | Robotics and kinematics        |
| Shakti  | `scope:shakti`  | Energy and power systems       |
| Nous    | `scope:nous`    | Reasoning and intelligence     |
| Uzume   | `scope:uzume`   | Media and broadcast            |
| Demeter | `scope:demeter` | Agricultural and environmental |
| Euterpe | `scope:euterpe` | Music and audio                |
| Hestia  | `scope:hestia`  | Home and IoT                   |
| Arete   | `scope:arete`   | General purpose utilities      |
| Kuanyin | `scope:kuanyin` | Compassion and wellness        |

### Project Types

- **Apps** (`apps/`) - Deployable applications (14 domain directories)
- **Libraries** (`libs/`) - Reusable code shared between apps (29 directories)
- **Tools** (`tools/`) - Development and build tools
- **Infrastructure** (`infra/`) - Terraform and deployment configurations

### Naming Conventions

- Shared libraries: `@oshun/{lib-name}` (e.g., `@oshun/database`, `@oshun/auth`)
- Domain libraries: `@{domain}/{lib-name}` (e.g., `@iris/conversation-core`,
  `@lilith/sdk`)
- Applications: `@{domain}/{app-name}` (e.g., `@tara/api`, `@veritas/web`)

## Common Tasks

### Running a Development Server

```bash
# Run a specific app
pnpm nx dev @tara/api

# Run all apps (parallel)
pnpm dev
```

### Building Projects

```bash
# Build a specific project
pnpm nx build @oshun/database

# Build all projects
pnpm build

# Build only affected projects
pnpm nx affected --target=build
```

### Running Tests

```bash
# Test a specific project
pnpm nx test @oshun/database

# Test all projects
pnpm test

# Test with coverage
pnpm nx test @oshun/database --coverage
```

### Linting Code

```bash
# Lint a specific project
pnpm nx lint @tara/api

# Lint all projects
pnpm lint

# Fix auto-fixable issues
pnpm nx lint @tara/api --fix
```

### Type Checking

```bash
# Type check a specific project
pnpm nx typecheck @tara/api

# Type check all projects
pnpm typecheck
```

## Working with Nx

### Understanding the Dependency Graph

Nx tracks dependencies between projects automatically. View the graph:

```bash
pnpm graph
```

### Running Affected Commands

Only run commands on projects affected by your changes:

```bash
# Build affected projects
pnpm nx affected --target=build

# Test affected projects
pnpm nx affected --target=test

# Lint affected projects
pnpm nx affected --target=lint
```

### Caching

Nx caches build and test results. To clear the cache:

```bash
pnpm nx reset
```

### Creating New Projects

See the dedicated guides:

- [Adding a New Library](./adding-new-library.md)
- [Adding a New Service](./adding-new-service.md)

## API Development

### OpenAPI Specifications

API contracts are defined in OpenAPI format under `libs/openapi/specs/`.

### Protocol Buffers

For gRPC services, proto definitions are in `libs/proto/oshun/`.

## Database Development

### PostgreSQL Databases

The development environment creates multiple domain-isolated databases:

- `oshun_dev` - Main development database
- `yemaya` - Yemaya (Creative Studio)
- `lilith` - Lilith (Consciousness)
- `isis` - Isis (Generative Factory)
- `iris` - Iris (AI Assistant)
- `sophia` - Sophia (Research & Knowledge)
- `hathor` - Hathor (Worldbuilding)
- `bellona` - Bellona (Build & Engine)
- `tara` - Tara (Meditation)

### Prisma

Domains that use Prisma have schemas at:

```
libs/{domain}/database/prisma/schema.prisma
```

Running migrations:

```bash
cd libs/{domain}/database && npx prisma migrate dev --name my_migration
```

## Stopping Infrastructure

```bash
# Stop containers (keeps data)
docker compose -f docker/docker-compose.dev.yml down

# Stop and remove all data (fresh start)
docker compose -f docker/docker-compose.dev.yml down -v
```

## Troubleshooting

### Common Issues

**Dependencies not found**

```bash
pnpm install
```

**Build errors after pulling**

```bash
pnpm nx reset
pnpm install
pnpm build
```

**Port already in use**

```bash
# Find and kill the process
lsof -i :3000
kill -9 <PID>
```

**Port conflicts with Docker**

```bash
docker ps -a | grep -E "(postgres|redis|minio)"
```

**Database not initializing** - Remove volumes and restart:

```bash
docker compose -f docker/docker-compose.dev.yml down -v
docker compose -f docker/docker-compose.dev.yml up -d
```

**TypeScript errors in IDE** - Restart your TypeScript server or reload your
IDE.

### Getting Help

- Check the [FAQ](./faq.md)
- Review the [ADR documents](../adr/) for architectural decisions
- Explore domain-specific guides in `docs/domains/`