Disciplines · Reference

Getting Started with Oshun

Before you begin, ensure you have the following installed:

9sections3 minread
Markdown source
On this page

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:

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:

text
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
  • Review the ADR documents for architectural decisions
  • Explore domain-specific guides in docs/domains/