# Bellona Domain

> **Bellona** - Build and Bridge Platform

Bellona handles engine adapters, asset export, build systems, and runtime
integrations for game engines and creative tools. It bridges the Oshun ecosystem
with Unity, Unreal Engine, Godot, Blender, and Houdini via real-time WebSocket
connections, asset interchange pipelines, and content-addressable build caching.

---

## Architecture

### Apps (8)

| App              | Port | Purpose                                                                                                                     |
| ---------------- | ---- | --------------------------------------------------------------------------------------------------------------------------- |
| `build-api`      | 4005 | Build system API with Redis-backed caching (100MB memory, 10GB max), event bus integration, and build/export queue adapters |
| `build-worker`   | -    | Poll-based worker processing 4 job types: `asset-bake`, `validate`, `engine-project-generate`, `export-package`             |
| `render-api`     | -    | Redis-backed render cache with health checks, exports `RenderCacheService`, `OutputValidator`, `GpuRenderQueue`             |
| `cli`            | -    | Commander.js CLI with `build`, `export`, `sync`, `config`, `health`, `project`, `detect` commands                           |
| `bridge-unity`   | 9004 | WebSocket bridge for Unity with 14 engine-specific commands                                                                 |
| `bridge-unreal`  | 9003 | WebSocket bridge for Unreal Engine with 11 engine-specific commands                                                         |
| `bridge-godot`   | 9002 | WebSocket bridge for Godot with 9 engine-specific commands                                                                  |
| `bridge-blender` | 9001 | WebSocket bridge for Blender with 6 commands and cross-domain event publishing                                              |

### Libraries (24)

**Core:**

| Library                       | Key Exports                                                                                                                                   |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `@bellona/client`             | `BellonaClient` SDK (~519 lines) with build, export, and engine sync operations                                                               |
| `@bellona/database`           | Prisma schema (674 lines, 11 models) for builds, exports, sessions, and caching                                                               |
| `@bellona/bridge-core`        | `BridgeServer`/`BridgeClient` (~944 lines): WebSocket framework with typed events, command routing, message encoding, heartbeat, reconnection |
| `@bellona/adapters`           | `BaseBridge`, `CommandQueue`, `StateManager`, `ProcessLauncher`, `VersionManager` for engine adapter infrastructure                           |
| `@bellona/interchange`        | `InterchangeManager` (~990 lines) with `FormatRegistry` (GLTF/USD/FBX), `JobManager`, `AssetCache`, transform/validation pipelines            |
| `@bellona/interchange-models` | Interchange data schemas for cross-format asset representation                                                                                |
| `@bellona/integration`        | `HathorArtifactConsumer`, `LoreToEngineCompiler`, `IsisAssetConsumer`, `AssetConverter` for cross-domain integration                          |

**Engine Integrations:**

| Library            | Purpose                              |
| ------------------ | ------------------------------------ |
| `@bellona/godot`   | Godot 4.0-4.2 (GLTF, TRES, GDScript) |
| `@bellona/unreal`  | Unreal 5.0-5.3 (FBX, Blueprint)      |
| `@bellona/unity`   | Unity 2022-2023 (FBX, Prefab)        |
| `@bellona/blender` | Blender 3.6-4.0 (GLTF, FBX, Blend)   |
| `@bellona/houdini` | Houdini 19.5+ (HDA, USD) - Beta      |
| `@bellona/davinci` | DaVinci Resolve integration          |
| `@bellona/openusd` | OpenUSD/USD support                  |

**Specialized:**

| Library                       | Purpose                                                                                                                                                            |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `@bellona/metahuman`          | MetaHuman pipeline for digital humans                                                                                                                              |
| `@bellona/mocap`              | Motion capture data processing and retargeting                                                                                                                     |
| `@bellona/xr`                 | VR/AR/MR support (OpenXR integration)                                                                                                                              |
| `@bellona/virtual-production` | Real-time virtual production workflows                                                                                                                             |
| `@bellona/gameplay-systems`   | Runtime gameplay systems (physics, AI, networking)                                                                                                                 |
| `@bellona/audio`              | Audio processing and spatial audio                                                                                                                                 |
| `@bellona/video`              | Video processing and encoding                                                                                                                                      |
| `@bellona/sdk-cpp`            | C++ SDK for native engine integration                                                                                                                              |
| `@bellona/event-handlers`     | Cross-domain event subscriptions (~349 lines): subscribes to `hathor.world.published`, `isis.asset.generated`, `yemaya.build.requested`, `yemaya.export.requested` |
| `@bellona/event-publisher`    | Typed event publishing for session, build, and export events                                                                                                       |

### Technology Stack

| Layer       | Technologies                                                                          |
| ----------- | ------------------------------------------------------------------------------------- |
| Framework   | Hono                                                                                  |
| Database    | PostgreSQL with Prisma ORM (schema: `bellona`)                                        |
| Build Cache | Content-addressable caching via Redis (100MB memory, 10GB max)                        |
| Bridges     | WebSocket (ports 9001-9004)                                                           |
| Native SDK  | C++ via `@bellona/sdk-cpp`                                                            |
| Events      | `@oshun/event-bus` (Redis Streams, bellona source domain, 24h TTL, exponential retry) |
| Caching     | `@oshun/cache` (Redis-backed)                                                         |
| Logging     | `@oshun/logging` (Pino-based structured logging)                                      |
| Build       | `@nx/js:tsc`                                                                          |
| Testing     | Vitest                                                                                |

---

## Database Schema

11 models in `libs/bellona/database/prisma/schema.prisma` (674 lines):

| Model           | Table             | Purpose                                                |
| --------------- | ----------------- | ------------------------------------------------------ |
| `Build`         | `builds`          | Build job tracking with status and optimization levels |
| `BuildArtifact` | `build_artifacts` | Build output files and checksums                       |
| `BuildLog`      | `build_logs`      | Debug, info, warning, and error logs                   |
| `ExportJob`     | `export_jobs`     | Format conversion and artifact management              |
| `EngineProject` | `engine_projects` | Engine-specific project configurations                 |
| `BridgeSession` | `bridge_sessions` | Active WebSocket bridge session tracking               |
| `SyncConflict`  | `sync_conflicts`  | Engine sync conflict resolution records                |
| `BuildWorker`   | `build_workers`   | Worker registration and capability reporting           |
| `AssetCache`    | `asset_cache`     | Content-addressable build artifact caching             |
| `BuildTemplate` | `build_templates` | Reusable build configuration templates                 |
| `AuditLog`      | `audit_log`       | Operation audit trail                                  |

### Supported Platforms

`WINDOWS`, `MACOS`, `LINUX`, `IOS`, `ANDROID`, `WEBGL`, `PLAYSTATION`, `XBOX`,
`SWITCH`

### Export Formats

`ZIP`, `TAR_GZ`, `UNITYPACKAGE`, `UASSET`, `GODOT_PCK`

---

## API Endpoints

Base URL: `http://localhost:4005`

### Exports

| Method | Path                        | Description        |
| ------ | --------------------------- | ------------------ |
| POST   | `/v1/exports`               | Create export job  |
| GET    | `/v1/exports/:id`           | Get export status  |
| GET    | `/v1/exports/:id/artifacts` | List artifacts     |
| GET    | `/v1/exports/:id/download`  | Download artifacts |

### Builds

| Method | Path             | Description      |
| ------ | ---------------- | ---------------- |
| POST   | `/v1/builds`     | Create build     |
| GET    | `/v1/builds/:id` | Get build status |

### Engines

| Method | Path          | Description            |
| ------ | ------------- | ---------------------- |
| GET    | `/v1/engines` | List supported engines |

### Conversion

| Method | Path          | Description             |
| ------ | ------------- | ----------------------- |
| POST   | `/v1/convert` | Asset format conversion |

### WebSocket Bridges

| Port | Engine  | Commands                                                                                 |
| ---- | ------- | ---------------------------------------------------------------------------------------- |
| 9001 | Blender | 6 commands (import, export, render, scene sync, material sync, session management)       |
| 9002 | Godot   | 9 commands (scene import/export, node management, resource sync, project management)     |
| 9003 | Unreal  | 11 commands (level management, blueprint sync, material sync, build, packaging)          |
| 9004 | Unity   | 14 commands (prefab sync, scene management, asset import, material sync, build pipeline) |

---

## Engine Support Matrix

| Engine  | Versions  | Import Formats       | Bridge Port | Status |
| ------- | --------- | -------------------- | ----------- | ------ |
| Godot   | 4.0-4.2   | GLTF, TRES, GDScript | 9002        | Stable |
| Unreal  | 5.0-5.3   | FBX, Blueprint       | 9003        | Stable |
| Unity   | 2022-2023 | FBX, Prefab          | 9004        | Stable |
| Blender | 3.6-4.0   | GLTF, FBX, Blend     | 9001        | Stable |
| Houdini | 19.5+     | HDA, USD             | -           | Beta   |

---

## Cross-Domain Integration

### Events Consumed

| Source Event              | Handler                                            |
| ------------------------- | -------------------------------------------------- |
| `hathor.world.published`  | Triggers asset export for published worlds         |
| `isis.asset.generated`    | Imports AI-generated assets into engine projects   |
| `yemaya.build.requested`  | Initiates build jobs from creative studio requests |
| `yemaya.export.requested` | Starts export pipelines for studio output          |

### Events Published

- `bellona.session.started` / `bellona.session.ended` - Bridge session lifecycle
- `bellona.build.started` / `bellona.build.completed` / `bellona.build.failed` -
  Build pipeline events
- `bellona.export.completed` - Export artifact availability

---

## Environment Variables

```bash
BELLONA_DATABASE_URL=postgresql://oshun:oshun_dev@localhost:5432/bellona
REDIS_URL=redis://localhost:6379
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
```

---

## Development

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

# Run the build API
pnpm nx dev @bellona/build-api

# Run a specific bridge (e.g., Godot)
pnpm nx dev @bellona/bridge-godot

# Run tests
pnpm nx test @bellona/client
pnpm nx test @bellona/bridge-core
pnpm nx test @bellona/interchange

# Build all Bellona libraries
pnpm nx run-many --target=build --projects=tag:scope:bellona

# Run database migrations
pnpm nx run @bellona/database:prisma:migrate
pnpm nx run @bellona/database:prisma:generate
```

---

## CI/CD

Bellona uses the core CI pipeline (`ci.yml`) and the general ECS deployment
pipeline (`deploy-ecs.yml`). Database migrations run via `database.yml`.

## Related Documentation

- [Architecture](./architecture.md) - Detailed Bellona architecture
- [Monorepo Architecture](../../architecture.md) - Monorepo overview
- [Cross-Domain Integration](../../cross-domain-integration.md)
