Oshun Monorepo Architecture

Overview#

Oshun is a large-scale Nx monorepo hosting 13 application domains, 12+ library-only domains, and a shared infrastructure layer. The monorepo pattern enables code sharing, consistent tooling, and atomic cross-domain changes.

Key Principles#

1. Domain Isolation - Each domain owns its apps, libraries, database schemas, and CI/CD pipelines
2. Shared Foundation - Common utilities (@oshun/*) prevent duplication across domains
3. Polyglot Support - TypeScript by default; Rust, C++, Python where performance or ecosystem demands it
4. Infrastructure as Code - Terraform for AWS, Kubernetes manifests for container orchestration

Technology Stack#

Repository Structure#

oshun/
├── apps/                       # Deployable applications
│   ├── iris/                   # AI assistant platform
│   ├── lilith/                 # Conversational AI
│   ├── yemaya/                 # Creative production
│   ├── isis/                   # Generative AI factory
│   ├── sophia/                 # Knowledge & research
│   ├── hathor/                 # Worldbuilding & narrative
│   ├── bellona/                # Game engines & build
│   ├── tara/                   # Meditation & mindfulness
│   ├── veritas/                # Fact-checking & news
│   ├── psyche/                 # Mental health services
│   ├── nyx/                    # Astronomical education
│   ├── aja/                    # Motion AI & animation
│   └── aphrodite/              # Live streaming & performance
│
├── libs/                       # Reusable libraries
│   ├── shared/                 # @oshun/* foundation (28 libs)
│   ├── contracts/              # Cross-domain API contracts
│   ├── proto/                  # Protocol Buffer definitions
│   ├── openapi/                # OpenAPI specifications
│   ├── meditation/             # Shared meditation libs (6)
│   ├── aje/                    # Blockchain & crypto (29 libs)
│   ├── themis/                 # Governance & compliance (32 libs)
│   ├── galatea/                # Robotics & kinematics (37 libs)
│   ├── shakti/                 # Fitness & wellness (27 libs)
│   ├── nous/                   # Reasoning & inference (1 lib)
│   ├── uzume/                  # Media & broadcast (22 libs)
│   ├── demeter/                # Agriculture & environment (14 libs)
│   ├── euterpe/                # Music & audio (7 libs)
│   ├── hestia/                 # Home & IoT (14 libs)
│   ├── arete/                  # Personal development (11 libs)
│   └── kuanyin/                # Compassion & wellness (10 libs)
│
├── infra/                      # Infrastructure
│   ├── terraform/              # AWS IaC (20 modules)
│   ├── k8s/                    # Kubernetes manifests
│   └── monitoring/             # Prometheus, Grafana configs
│
├── docker/                     # Development environment
│   └── docker-compose.dev.yml  # Local infrastructure
│
├── testing/                    # Test infrastructure
│   ├── vitest.config.base.ts   # Shared Vitest configuration
│   ├── vitest.workspace.ts     # Multi-project workspace
│   ├── e2e/                    # E2E test setup
│   ├── integration/            # Integration test setup
│   └── performance/            # Performance test setup
│
├── tools/                      # Development tools
│   ├── codegen/                # Code generation
│   ├── generators/             # Nx generators
│   └── model-sync/             # AI model synchronization
│
├── .github/workflows/          # CI/CD (31 workflows)
└── docs/                       # Documentation

Domain Architecture#

Application Domains#

Each application domain contains apps (deployable services) and domain-specific libraries. Domains own their database schemas and have independent CI/CD pipelines.

Library-Only Domains#

These domains provide shared libraries consumed by application domains but do not have standalone deployable applications.

Shared Foundation (@oshun/*)#

The libs/shared/ directory contains 28 libraries that provide common infrastructure for all domains:

Core Libraries#

Data & Storage#

Communication#

Security & Identity#

Observability#

AI & Compute#

Infrastructure#

Build System#

Nx Configuration#

The monorepo uses Nx for task orchestration. Each project has a project.json defining build, test, and lint targets.

Common executors:

Project tags follow the pattern: ["scope:<domain>", "layer:<layer>", "type:<type>"]

• Scope: scope:iris, scope:aje, scope:shared, etc.
• Layer: layer:domain, layer:shared, layer:app
• Type: type:lib, type:app

Dependency Management#

Dependencies are managed through pnpm's catalog: feature in pnpm-workspace.yaml. This ensures consistent versions across all projects. See Dependency Management for details.

Affected Commands#

Nx tracks the dependency graph between projects. Use affected commands to only build/test/lint projects impacted by your changes:

pnpm nx affected --target=build
pnpm nx affected --target=test
pnpm nx affected --target=lint

Data Architecture#

Database Isolation#

Each domain has its own PostgreSQL database within the same server instance. This provides logical isolation while keeping the development environment simple.

ORM Layer#

Domains that require database access use Prisma with schemas located at:

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

Each domain manages its own migrations independently.

Supporting Data Stores#

Deployment Architecture#

Primary Deployment: AWS ECS#

Most services deploy to AWS ECS (Elastic Container Service) with the following topology:

AWS Account
├── VPC (managed by Terraform)
│   ├── ALB (Application Load Balancer)
│   ├── ECS Cluster: oshun-staging
│   │   └── Services per domain
│   ├── ECS Cluster: oshun-production
│   │   └── Services per domain
│   ├── RDS (PostgreSQL)
│   ├── ElastiCache (Redis)
│   └── S3 (Object Storage)
├── ECR (Container Registry)
├── CloudWatch (Logs, Metrics, Alarms)
└── SNS/SQS (Notifications, Queues)

GPU Workloads: RunPod#

GPU-intensive services (Isis generation workers, AI inference) deploy to RunPod for cost-effective GPU access.

Kubernetes (Iris Domain)#

The Iris domain additionally has Kubernetes manifests for more advanced orchestration:

• HorizontalPodAutoscaler (HPA) for auto-scaling
• PodDisruptionBudgets (PDB) for availability
• StatefulSets for stateful services (memory)
• Kustomize overlays for environment management

Cross-Domain Communication#

Domains communicate through:

1. Event Bus (@oshun/event-bus) - Asynchronous events for loose coupling
2. HTTP Clients (@oshun/http-client) - Synchronous REST calls
3. Shared Contracts (libs/contracts/) - Type-safe API contracts
4. Protocol Buffers (libs/proto/) - gRPC service definitions

Event Flow Pattern#

Domain A → Event Bus → Domain B
   │                      │
   └── Event Publisher     └── Event Handler
       (@oshun/events)        (domain-specific)

Each domain has event-publisher and event-handlers libraries for domain-specific event integration.

Observability#

Development#

The observability Docker Compose profile provides:

• Prometheus (port 9090) - Metrics scraping and alerting
• Grafana (port 3100) - Dashboards and visualization
• Jaeger (port 16686) - Distributed tracing

Production#

Production observability uses:

• CloudWatch - AWS-native logs and metrics
• Prometheus + Grafana - Custom dashboards (Iris domain)
• OpenTelemetry - Distributed tracing via @oshun/tracing

Pre-built Grafana dashboards exist for the Iris domain:

• System overview, agent performance, memory usage
• AI provider metrics, SLO tracking, conversation analytics

See Monitoring for details.

Security#

Authentication#

• JWT-based authentication via @oshun/auth
• Per-domain auth configuration
• Rate limiting via @oshun/rate-limit

Secrets Management#

• Development: Environment variables in .env
• Production: AWS Secrets Manager, SSM Parameter Store
• Terraform manages secret rotation and access policies

CI/CD Security#

• GitHub CodeQL scanning (codeql.yml)
• Domain-specific security scanning (e.g., iris-security.yml)
• Dependency vulnerability scanning via npm audit

Further Reading#

• Getting Started - Development environment setup
• CI/CD Pipelines - Continuous integration and deployment
• Testing Strategy - Test infrastructure and practices
• Dependency Management - pnpm catalog usage
• Monitoring - Observability stack
• Adding a New Library - How to create libraries
• Adding a New Service - How to create services
• Cross-Domain Integration - Inter-domain communication