# 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

| Layer           | Technologies                                     |
| --------------- | ------------------------------------------------ |
| Language        | TypeScript (primary), Rust, Python, C++          |
| Runtime         | Node.js 20+                                      |
| Package Manager | pnpm 10+ with `catalog:` version management      |
| Build System    | Nx 19+ with task caching and affected commands   |
| Testing         | Vitest (unit/integration), Playwright (E2E)      |
| Databases       | PostgreSQL 16 (pgvector), Redis 7, Qdrant, Neo4j |
| Object Storage  | MinIO (dev), S3 (production)                     |
| Deployment      | AWS ECS (primary), RunPod (GPU workloads)        |
| CI/CD           | GitHub Actions (31 workflows)                    |
| IaC             | Terraform (20 modules), Kustomize (K8s overlays) |
| Observability   | Prometheus, Grafana, Jaeger, CloudWatch          |

---

## 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.

| Domain    | Scope Tag         | Apps | Libs | Database Schema | Description                           |
| --------- | ----------------- | ---- | ---- | --------------- | ------------------------------------- |
| Iris      | `scope:iris`      | 5    | 26   | `iris`          | Universal AI assistant platform       |
| Lilith    | `scope:lilith`    | 4+   | 10+  | `lilith`        | Conversational AI and consciousness   |
| Yemaya    | `scope:yemaya`    | 3+   | 15+  | `yemaya`        | Creative production workflows         |
| Isis      | `scope:isis`      | 5    | 13   | `isis`          | Generative AI factory                 |
| Sophia    | `scope:sophia`    | 4    | 10   | `sophia`        | Knowledge management and research     |
| Hathor    | `scope:hathor`    | 3+   | 10+  | `hathor`        | Worldbuilding and narrative design    |
| Bellona   | `scope:bellona`   | 8    | 24   | `bellona`       | Game engines and build systems        |
| Tara      | `scope:tara`      | 3    | 10+  | `tara`          | Meditation and mindfulness            |
| Veritas   | `scope:veritas`   | 10+  | 63   | `veritas`       | Fact-checking and news verification   |
| Psyche    | `scope:psyche`    | 5+   | 98   | `psyche`        | Mental health and behavioral services |
| Nyx       | `scope:nyx`       | 3    | 10+  | `nyx`           | Astronomical education                |
| Aja       | `scope:aja`       | 3    | 37   | -               | Motion AI and animation               |
| Aphrodite | `scope:aphrodite` | 3+   | 67   | `aphrodite`     | Live streaming and performance        |

### Library-Only Domains

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

| Domain  | Scope Tag       | Libs | Description                        |
| ------- | --------------- | ---- | ---------------------------------- |
| Aje     | `scope:aje`     | 29   | Blockchain, DeFi, NFT, Web3        |
| Themis  | `scope:themis`  | 32   | Governance, compliance, legal      |
| Galatea | `scope:galatea` | 37   | Robotics, kinematics, choreography |
| Shakti  | `scope:shakti`  | 27   | Fitness, wellness, yoga            |
| Nous    | `scope:nous`    | 1    | Dynamic batching, LLM inference    |
| Uzume   | `scope:uzume`   | 22   | Media production, broadcasting     |
| Demeter | `scope:demeter` | 14   | Agriculture, environmental         |
| Euterpe | `scope:euterpe` | 7    | Music theory, audio production     |
| Hestia  | `scope:hestia`  | 14   | Smart home, cooking, recipes       |
| Arete   | `scope:arete`   | 11   | Personal development, habits       |
| Kuanyin | `scope:kuanyin` | 10   | Compassion, ethics, wellness       |

---

## Shared Foundation (`@oshun/*`)

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

### Core Libraries

| Library             | Purpose                            |
| ------------------- | ---------------------------------- |
| `@oshun/types`      | Shared TypeScript type definitions |
| `@oshun/errors`     | Standardized error handling        |
| `@oshun/config`     | Configuration management           |
| `@oshun/logger`     | Structured logging                 |
| `@oshun/validation` | Schema validation (Zod-based)      |

### Data & Storage

| Library           | Purpose                          |
| ----------------- | -------------------------------- |
| `@oshun/database` | PostgreSQL client and migrations |
| `@oshun/cache`    | Redis-backed caching abstraction |
| `@oshun/queue`    | Message queue abstraction        |
| `@oshun/storage`  | S3-compatible object storage     |

### Communication

| Library                 | Purpose                            |
| ----------------------- | ---------------------------------- |
| `@oshun/http-client`    | HTTP client for service-to-service |
| `@oshun/events`         | Event publishing and subscription  |
| `@oshun/event-bus`      | Event bus implementation           |
| `@oshun/websocket`      | WebSocket support                  |
| `@oshun/traefik-config` | API gateway utilities              |

### Security & Identity

| Library                  | Purpose                   |
| ------------------------ | ------------------------- |
| `@oshun/auth`            | Authentication middleware |
| `@oshun/auth-primitives` | Low-level auth primitives |
| `@oshun/security`        | Security utilities        |
| `@oshun/identity`        | Identity management       |
| `@oshun/rate-limit`      | Rate limiting             |

### Observability

| Library          | Purpose                             |
| ---------------- | ----------------------------------- |
| `@oshun/metrics` | Metrics collection (Prometheus)     |
| `@oshun/tracing` | Distributed tracing (OpenTelemetry) |
| `@oshun/health`  | Health check endpoints              |

### AI & Compute

| Library                 | Purpose                   |
| ----------------------- | ------------------------- |
| `@oshun/ai`             | AI provider integration   |
| `@oshun/ai-advanced`    | Advanced AI features      |
| `@oshun/gpu-dispatcher` | GPU task distribution     |
| `@oshun/runpod-client`  | RunPod GPU cluster client |

### Infrastructure

| Library                    | Purpose                  |
| -------------------------- | ------------------------ |
| `@oshun/infrastructure`    | Infrastructure utilities |
| `@oshun/service-discovery` | Service discovery        |
| `@oshun/migration`         | Database migration tools |

---

## 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:**

| Executor              | Purpose                          |
| --------------------- | -------------------------------- |
| `@nx/js:tsc`          | TypeScript compilation (default) |
| `@nx/esbuild:esbuild` | Fast ESM builds (Nous, Kuanyin)  |
| `@nx/vite:test`       | Vitest integration               |
| `@nx/eslint:lint`     | ESLint checking                  |

**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](./dependency-management.md) for details.

### Affected Commands

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

```bash
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.

| Database    | Domain  | Extensions          |
| ----------- | ------- | ------------------- |
| `oshun_dev` | Shared  | pgvector, uuid-ossp |
| `iris`      | Iris    | pgvector            |
| `lilith`    | Lilith  | pgvector            |
| `yemaya`    | Yemaya  | -                   |
| `isis`      | Isis    | -                   |
| `sophia`    | Sophia  | -                   |
| `hathor`    | Hathor  | -                   |
| `bellona`   | Bellona | -                   |
| `tara`      | Tara    | -                   |

### 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

| Store         | Purpose                   | Dev Port | Profile     |
| ------------- | ------------------------- | -------- | ----------- |
| Redis 7       | Caching, sessions, queues | 6379     | Core        |
| MinIO         | Object storage (S3)       | 9000     | Core        |
| Elasticsearch | Full-text search          | 9200     | `search`    |
| Qdrant        | Vector similarity search  | 6333     | `vectors`   |
| Kafka         | Event streaming           | 29092    | `streaming` |
| Neo4j         | Graph database            | 7474     | `graph`     |

---

## 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](./monitoring.md) 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](./getting-started.md) - Development environment setup
- [CI/CD Pipelines](./ci-cd.md) - Continuous integration and deployment
- [Testing Strategy](./testing.md) - Test infrastructure and practices
- [Dependency Management](./dependency-management.md) - pnpm catalog usage
- [Monitoring](./monitoring.md) - Observability stack
- [Adding a New Library](./adding-new-library.md) - How to create libraries
- [Adding a New Service](./adding-new-service.md) - How to create services
- [Cross-Domain Integration](./cross-domain-integration.md) - Inter-domain
  communication