# Bellona Domain — Architecture > Build Orchestration, Asset Interchange, and Engine Bridge Platform Bellona is the production pipeline layer of the Oshun ecosystem. It exists to solve a specific and unavoidable problem in game and creative production: the tools where content is created (Blender, Houdini, Maya) and the engines where it runs (Unity, Unreal, Godot) speak fundamentally different languages, use incompatible file formats, and have no native awareness of each other. Bellona provides the connective tissue — it translates assets between formats, compiles narrative content from Hathor into engine-native code, bakes AI-generated content from Isis into platform-ready textures and meshes, and keeps live editor sessions synchronized with the Oshun platform in real time. The domain is organized around three primary concerns. The **engine bridges** are persistent WebSocket connections to live editor sessions — they let Oshun issue commands to Unity, Unreal, Godot, and Blender without leaving the platform. The **build and export pipeline** is an async, Redis-backed job system that compiles, packages, and caches artifacts for every supported platform. The **integration layer** is the translation boundary between Oshun domain models (Hathor lore, Isis assets) and engine-native representations. Users of Bellona include other Oshun domains (Yemaya submits build requests, Hathor publishes worlds, Isis publishes generated assets), external tool operators (engine editors connect via the bridges), CI/CD pipelines (via the CLI and TypeScript SDK), and browser-based operators (via the Control Room remote-control UI). --- ## 1. System Overview ### Core Responsibilities - **Build Orchestration** — Job queuing, worker dispatch, content-addressable artifact caching, and cross-domain event handling for build requests - **Engine Bridges** — Real-time bidirectional WebSocket connections to Unity, Unreal, Godot, and Blender editor instances - **Asset Interchange** — Universal 3D format conversion pipeline across GLTF/GLB, USD, FBX, OBJ, ABC, PLY, STL, and Blend formats - **Export Pipeline** — Engine-native packaging into ZIP, TAR_GZ, UNITYPACKAGE, UASSET, and GODOT_PCK formats - **Cross-Domain Integration** — Consuming Hathor world publications and Isis generated assets to produce engine-ready artifacts - **Specialized Systems** — Virtual production, XR (visionOS, Meta Quest, WebXR), motion capture, MetaHuman pipeline, OpenUSD pipeline, gameplay runtime systems, and a C++ native SDK - **DCC Agents** — Blender-native and Unity Editor agent runtimes (`@bellona/blender-agent`, `@bellona/unity-agent`) plus Maya / 3ds Max bridge contracts - **Remote Control** — Browser-first remote operation of engine hosts, desktop applications, and headless browsers (`remote-protocol`, `mcp-gateway`, `control-room`, `remote-gateway`, `remote-host`). This is the Phase 180 Remote Creative Control Plane (`TODOS/phase-180.md`): the planned envelope adds cloud gateway deployment, WebRTC live streaming, device trust and approval gates, macOS host packaging plus Windows/Linux hosts, multi-host fleets, an adapter SDK with conformance suite, and eventual deprecation of the standalone `bridge-blender` / `bridge-unreal` apps --- ## 2. Service Architecture ### 2.1 Application Topology The following diagram shows how the 12 Bellona applications relate to each other and to shared infrastructure. The build path runs vertically through `build-api` → `build-worker`; the bridge path runs horizontally as four independent processes. ``` +------------------+ | bellona-cli | | (Commander.js) | +--------+---------+ | +----------------+----------------+ | | +--------v---------+ +---------v--------+ | build-api | | render-api | | (module, no | | (module, no | | HTTP port) | | HTTP port) | | Event Bus: Redis | | RenderCacheService| | Build cache | | GpuRenderQueue | | Job queue mgmt | | OutputValidator | +--------+---------+ +------------------+ | +--------v---------+ | build-worker | | (queue poll) | | | | asset-bake | | validate | | engine-proj-gen | | export-package | +------------------+ +----------+ +-----------+ +----------+ +------------+ |bridge- | |bridge- | |bridge- | |bridge- | |unity | |unreal | |godot | |blender | |ws://9004 | |ws://9003 | |ws://9002 | |ws://9001 | |/unity | |/unreal | |/godot | |/blender | +----------+ +-----------+ +----------+ +------------+ ``` ### 2.2 Application Details #### build-api (domain port 4005) Central build orchestration **module**. It manages build and export job submission, status tracking, and content-addressable artifact caching. It is a Node.js module with an `initialize()` / `shutdown()` lifecycle — it does not bind an HTTP port itself; `4005` is the documented domain port assignment. - **Event handling:** Subscribes to `hathor.world.published`, `isis.asset.generated`, `yemaya.build.requested`, and `yemaya.export.requested` via `@oshun/event-bus` (Redis-backed) - **Cache:** Redis-backed content-addressable build cache with an in-memory tier (100 MB default, 10 GB max), compression, deduplication, and PubSub invalidation - **Queue adapters:** Redis-backed job queues when `REDIS_URL` is set (`bellona:queue:*` keys); in-memory `Map` fallback otherwise - **Dependencies:** `@oshun/logging`, `@oshun/event-bus`, `@oshun/cache`, `@oshun/metrics`, `@bellona/event-handlers` #### build-worker Background job processor that polls a build queue and dispatches to specialized worker functions. Runs as an independent process or cluster. - **Job types:** `asset-bake`, `validate`, `engine-project-generate`, `export-package` - **Concurrency:** Configurable poll interval and concurrency level - **Lifecycle:** Graceful shutdown with configurable drain timeout - **Events published:** `bellona.build.started`, `bellona.build.progress`, `bellona.build.completed`, `bellona.export.started`, `bellona.export.ready`, `bellona.asset.synced` - **Dependencies:** `@bellona/event-publisher` #### render-api (Internal) GPU render job management service. Not exposed externally; operates as an internal module. - **Components:** `RenderCacheService` (Redis PubSub + metrics), `OutputValidator` (render quality checks), `GpuRenderQueue` (device allocation and queued job management) - **Dependencies:** `@oshun/logging` #### cli Commander-based CLI tool (program name `bellona`) for game development workflow automation. Reads configuration from environment variables and CLI profiles. - **Commands:** `build` (top-level alias `b`), `export` (top-level alias `e`), `sync`, `config`, `health`, `project`, `detect` - **Features:** Auto-detect engine projects in a directory, profile management, JSON output mode, API key authentication - **Dependencies:** `commander`, `chalk`, `dotenv` #### bridge-unity (WebSocket Port 9004) WebSocket bridge providing 14 commands for Unity Engine integration. - **Endpoint:** `ws://localhost:9004/unity` - **Capabilities:** Scene management, GameObject CRUD, component management, animation playback and parameter control, physics (force application, raycasting), and `SendMessage` IPC - **Dependencies:** `@bellona/bridge-core`, `@bellona/unity` #### bridge-unreal (WebSocket Port 9003) WebSocket bridge providing 11 commands for Unreal Engine integration. - **Endpoint:** `ws://localhost:9003/unreal` - **Capabilities:** World and level management, actor spawn/destroy/property, Blueprint function calls, material parameter control, Sequencer timeline control, console command execution, screenshot capture - **Dependencies:** `@bellona/bridge-core`, `@bellona/unreal` #### bridge-godot (WebSocket Port 9002) WebSocket bridge providing 9 commands for Godot Engine integration. - **Endpoint:** `ws://localhost:9002/godot` - **Capabilities:** Scene tree access, node creation/properties/methods, resource loading, signal emission, GDScript execution, project settings - **Dependencies:** `@bellona/bridge-core`, `@bellona/godot` #### bridge-blender (WebSocket Port 9001) WebSocket bridge for Blender integration with session tracking and cross-domain event publishing. - **Endpoint:** `ws://localhost:9001/blender` - **Capabilities:** Scene info, object creation, asset import/export, animation frame control, render trigger - **Events published:** `bellona.session.started` and `bellona.session.ended` (with session duration, command count, and disconnect reason) - **Dependencies:** `@bellona/bridge-core`, `@bellona/blender`, `@bellona/event-publisher` --- ## 3. Library Architecture ### 3.1 Layer Overview There are **34 libraries** under `libs/bellona/`, organized into five logical layers. Each layer builds on the one below it: the Core Infrastructure layer is used by everything else, the Engine Adapter layer provides engine-specific implementations, and so on upward. ``` Core Infrastructure layer: @bellona/bridge-core — WebSocket bridge protocol foundation @bellona/adapters — BaseBridge, CommandQueue, StateManager, ProcessLauncher @bellona/client — TypeScript SDK @bellona/database — Prisma schema and generated client (11 models) @bellona/interchange — Universal 3D format conversion pipeline @bellona/interchange-models — Schemas for interchange data structures @bellona/integration — Cross-domain consumers and compilers @bellona/asset-export — CGI-scene asset export readiness/conversion planning Engine Adapter layer: @bellona/unity — Unity adapter @bellona/unreal — Unreal adapter (+ BellonaUnrealEditor plugin) @bellona/godot — Godot adapter @bellona/blender — Blender adapter @bellona/houdini — Houdini integration @bellona/maya — Maya bridge runtime and workflow contracts @bellona/3dsmax — 3ds Max bridge runtime and workflow contracts @bellona/davinci — DaVinci Resolve integration @bellona/openusd — OpenUSD pipeline (MaterialX) DCC Agent layer: @bellona/blender-agent — Blender-native agent runtime (RPC bridge, macros) @bellona/unity-agent — Unity Editor MCP server package and wrapper @bellona/cross-dcc-consistency — Cross-DCC workflow consistency contracts @bellona/editor-productization — Editor release/onboarding/diagnostics contracts Specialized Systems layer: @bellona/gameplay-systems — Input, save/load, inventory, combat, AI @bellona/metahuman — MetaHuman pipeline (identity, mesh, LODs, face rig) @bellona/mocap — Motion capture streaming, retargeting, frame-snap @bellona/virtual-production — Camera tracking, LED wall, ICVFX, genlock @bellona/xr — XR: visionOS, Meta Quest, WebXR @bellona/audio — Audio processing for game engines @bellona/video — Video processing for game engines @bellona/sdk-cpp — C++ native SDK for engine plugin integration Remote Control layer: @bellona/remote-protocol — Canonical remote-control protocol contracts @bellona/mcp-gateway — Remote-control MCP gateway server and stdio transport Event System layer: @bellona/event-publisher — Type-safe event publishing (8 event methods) @bellona/event-handlers — Cross-domain event subscriptions and metrics ``` ### 3.2 Library Descriptions #### `@bellona/bridge-core` — WebSocket Foundation Typed WebSocket server and client framework underlying all four engine bridges. Provides command routing, message encoding/decoding, heartbeat management, automatic reconnection, and the request/response correlation pattern. #### `@bellona/adapters` — Engine Adapter Infrastructure Base abstractions for all engine adapters: `BaseBridge` (lifecycle and connection management), `CommandQueue` (ordered async command dispatch), `CommandExecutor` (typed execution with timeout), `StateManager` (engine state synchronization), `ProcessLauncher` (engine process management), `VersionManager` (version discovery and validation), and a middleware system for command pre/post processing. #### `@bellona/client` — TypeScript SDK `BellonaClient` providing type-safe access to all Bellona services. Key methods: `triggerBuild`, `exportForUnity`, `exportForUnreal`, `exportForGodot`, `syncAssets`, `bidirectionalSync`, `resolveConflict`. #### `@bellona/database` — Data Access Layer Prisma client for the 11-model, 14-enum PostgreSQL schema in the `bellona` database. Schema at `libs/bellona/database/prisma/schema.prisma` (673 lines), with the generated client output to `src/generated/client`. #### `@bellona/interchange` — Format Conversion Universal 3D asset interchange supporting GLTF/GLB, USD (USDA/USDC/USDZ), FBX, OBJ, ABC (Alembic), PLY, STL, DAE, and Blend formats. Includes: transform pipelines, input/output validation, batch conversion, and an LRU asset cache. #### `@bellona/interchange-models` — Data Contracts Zod schemas and TypeScript types for all interchange pipeline data structures. Serves as the contract layer for the format conversion pipeline. #### `@bellona/integration` — Cross-Domain Integration `@bellona/integration` is the translation boundary that keeps upstream Oshun domains fully engine-agnostic. Neither Hathor nor Isis knows anything about Unity, Unreal, or Godot — they publish domain events, and this library translates those events into engine-native artifacts. - `HathorArtifactConsumer` — Ingests lore, quests, dialogues, and NPC data from Hathor world publication events - `LoreToEngineCompiler` — Compiles lore content to engine-native code (C# for Unity, Blueprint for Unreal, GDScript for Godot) - `IsisAssetConsumer` — Ingests AI-generated textures, 3D models, and audio from Isis asset generation events - `AssetConverter` — Converts raw assets to engine-native formats via the interchange pipeline #### Engine Adapters Each engine adapter wraps the engine's API surface in a uniform interface. The table below summarizes what each adapter covers. | Library | Engine | Key Capabilities (per source `src/` layout) | | ------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------- | | `@bellona/unity` | Unity | WebSocket bridge, prefab management, FBX import | | `@bellona/unreal` | Unreal Engine 5 | `src/{bridge,assets,project,metahuman}`, version discovery, plugin transport, `BellonaUnrealEditor` plugin | | `@bellona/godot` | Godot | WebSocket bridge, `.tscn` scenes, `project.godot`, version discovery | | `@bellona/blender` | Blender | `bpy` integration, GLTF/FBX/Blend import/export | | `@bellona/houdini` | Houdini | HDA assets, USD pipeline | | `@bellona/maya` | Autodesk Maya | Bridge runtime, action schema, import/export and rigging workflow contracts (releases 2023–2026) | | `@bellona/3dsmax` | Autodesk 3ds Max | Bridge runtime, action schema, import/export and rigging workflow contracts (releases 2023–2026) | | `@bellona/davinci` | DaVinci Resolve | Video/color pipeline integration | | `@bellona/openusd` | OpenUSD | USD stage/layer composition, variant management, MaterialX shaders | #### Specialized System Libraries These libraries provide production-grade capabilities that sit on top of the engine adapters and serve specific professional production workflows. | Library | Key Capabilities | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `@bellona/gameplay-systems` | Input (keyboard/mouse/gamepad/touch/VR), save/load with cloud sync, inventory, combat with abilities/effects, AI (behavior trees, utility AI, GOAP, perception) | | `@bellona/metahuman` | MetaHuman identity management, mesh types, LOD configuration, face rig, body customization | | `@bellona/mocap` | Multi-vendor streaming (OptiTrack, Vicon, Xsens, Rokoko), skeleton retargeting, BVH/C3D/TRC parsing, animation clip generation, keyframe reduction | | `@bellona/virtual-production` | Camera tracking (Ncam, Mo-Sys, OptiTrack, Vicon), LED wall control, ICVFX compositing, genlock and timecode sync | | `@bellona/xr` | visionOS (Apple Vision Pro), Meta Quest 2/Pro/3, WebXR. Hand tracking, eye tracking, spatial anchors, scene understanding | | `@bellona/sdk-cpp` | C++ SDK for native engine plugin integration; bridges Node.js services with C++ game engine code | #### Event System Libraries These two libraries form the complete event boundary between Bellona and the rest of the Oshun platform. `@bellona/event-publisher` handles outbound events; `@bellona/event-handlers` handles inbound ones. | Library | Key Capabilities | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `@bellona/event-publisher` | Type-safe publish methods: `publishSessionStarted`, `publishSessionEnded`, `publishBuildStarted`, `publishBuildProgress`, `publishBuildCompleted`, `publishExportStarted`, `publishExportReady`, `publishAssetSynced` | | `@bellona/event-handlers` | Subscriptions to cross-domain events from Hathor, Isis, and Yemaya; metrics collection and statistics tracking | --- ## 4. Data Flow ### 4.1 Build Pipeline The following diagram shows the lifecycle of a build job from the triggering event through artifact storage. The build-worker is responsible for all on-disk work; the build-api only manages the queue and cache. ``` External Domains Bellona Storage ──────────────── ────────────────────────── ────────────────────── yemaya.build .requested ──────> build-api enqueue build job │ build-worker (polls queue) │ ├── asset-bake │ (texture compression, │ mesh optimization, │ shader compilation) │ ├── validate │ (format checks, │ platform compatibility) │ ├── engine-project-generate │ (Unity .csproj, Unreal .uproject, │ Godot project.godot) │ └── export-package (ZIP / TAR_GZ / UNITYPACKAGE UASSET / GODOT_PCK) │ bellona.build ──────> S3/MinIO artifact storage .completed published (storageBucket + storageKey) ``` ### 4.2 Bridge Synchronization The bridge flow shows what happens during a live engine editor session. The handshake establishes the session, typed commands flow in both directions, and the session lifetime is tracked in the database and published to the event bus. ``` Engine Editor Bridge Service Oshun Platform ───────────── ────────────────────── ───────────────────── Unity/Unreal/ bridge-{engine} @bellona/integration Godot/Blender │ │ │ │ │ │ WebSocket ┌─────┴─────┐ │ ├──connect────> │ handshake │ │ │ │ ping/pong │ │ │ │ heartbeat │ │ │ commands │ routing │ │ ├──────────────> │ (14/11/9/6 │ │ │ (typed) │ commands) │ │ │ └─────┬─────┘ │ │ │ │ │ bellona.session │ │ .started ──────────────────────> │ │ │ │ │ asset sync │ │ PUSH / PULL ────────────────────> │ │ / BIDIRECTIONAL │ │ │ │ │ bellona.asset │ │ .synced ──────────────────────> │ │ │ │ │ disconnect bellona.session │ ├──────────────> .ended ───────────────────────> │ ``` ### 4.3 Cross-Domain Integration This is the most important flow in Bellona for understanding the domain boundary. Hathor and Isis never call Bellona directly — they publish events describing what they produced, and Bellona's integration layer translates that into engine-native output. This means Hathor's lore model and Isis's generative AI pipeline have no dependency on Unity, Unreal, or Godot concepts. ``` Hathor (Worldbuilding) Bellona Target Engine ────────────────────── ────────────────────── ────────────────────── hathor.world.published HathorArtifactConsumer (lore, quests, ────> │ dialogue, NPCs) LoreToEngineCompiler │ compile to: │ C# (Unity) │ Blueprint (Unreal) │ GDScript (Godot) ────> Engine-native files Isis (Generative AI) ────────────────────── isis.asset.generated IsisAssetConsumer (textures, 3D ────> │ models, audio) AssetConverter │ convert via │ @bellona/interchange │ (GLTF → FBX) │ (PNG → KTX2/DDS) ────> Engine-native assets │ (WAV → OGG/MP3) ``` ### 4.4 Build Cache Flow The content-addressable cache is the primary reason Bellona can serve large asset pipelines efficiently in CI/CD environments where the same assets are rebuilt frequently. A cache hit skips all build work entirely. ``` Build Worker │ ├── Compute content hash from (assetIds + platforms + settings) │ ├──[cache HIT]──> Return cached artifact immediately │ (no recompilation) │ └──[cache MISS]──> Run full build pipeline │ └──> Store artifact in cache (storageBucket + storageKey) Invalidate via Redis PubSub ``` --- ## 5. Key Design Patterns ### 5.1 Event-Driven Build Orchestration The Build API does not expose an HTTP/REST interface at all. It is a Node.js module that subscribes to cross-domain events (over the Redis-backed `@oshun/event-bus`) from Hathor, Isis, and Yemaya. This decouples the build system from upstream producers — Hathor never calls Bellona directly; it publishes a world completion event and Bellona reacts. ### 5.2 Content-Addressable Build Cache Build outputs are stored and retrieved by content hash (combination of input asset IDs, target platforms, optimization level, and compression settings). This produces deterministic caching: identical inputs always map to the same cached artifact, enabling instant delivery of previously built outputs without reprocessing. Redis PubSub handles cross-process cache invalidation. ### 5.3 Bridge-Core Abstraction Pattern All four engine bridges share the same WebSocket protocol from `@bellona/bridge-core` (handshake, ping, message envelope, error format). Each bridge adds engine-specific commands as a thin layer on top. This means new engines can be added by implementing only the engine-specific command set; connection management, heartbeat, and reconnection logic are inherited for free. ### 5.4 Adapter Pattern — Engine Backends All engine adapters inherit from `BaseBridge` in `@bellona/adapters`, which provides lifecycle management, connection state tracking, and command dispatch. The rest of the system interacts through the `BaseBridge` interface rather than calling engine-specific APIs directly, allowing engine adapters to be swapped or extended without touching application code. ### 5.5 Programmatic Module API The Build API and Render API are designed as Node.js modules with `initialize()` / `shutdown()` lifecycle methods rather than standalone HTTP servers. This allows them to be embedded in other services or tested in isolation without port binding, and makes integration testing simpler. ### 5.6 Strategy Pattern — Build Job Workers Each build job type (`asset-bake`, `validate`, `engine-project-generate`, `export-package`) is a separate worker function registered to the job queue. Adding a new job type requires only implementing the worker function and registering it — the queue polling, retry logic, and event publishing are handled by the build-worker framework. ### 5.7 Cross-Domain Compilation via Integration Layer The `@bellona/integration` library provides the translation boundary between Oshun domain models (Hathor lore, Isis assets) and engine-native artifacts. This separation ensures that engine-specific code is isolated in one place, and upstream domains remain engine-agnostic. The boundary exists because Hathor and Isis operate on Oshun's abstract content model, while engines operate on platform-specific representations. Mixing the two concerns would create a circular dependency between creative content systems and build tooling. --- ## 6. Technology Stack The table below shows the technology choice at each layer, followed by explanations of the non-obvious choices. | Layer | Technology | | -------------- | ------------------------------------------------------------------ | | Language | TypeScript (ESM modules) | | API Framework | Hono (build-api, render-api) | | WebSocket | `ws` library via `@bellona/bridge-core` | | Database | PostgreSQL with Prisma ORM (`bellona` schema, 11 models, 14 enums) | | Cache | Redis (content-addressable build cache, render cache) | | Object Storage | S3-compatible (MinIO in development) | | CLI Framework | Commander.js with chalk | | Event Bus | `@oshun/event-bus` (Redis-backed, via `ioredis`) | | Logging | `@oshun/logging` (Pino-based structured logging) | | Asset Formats | GLTF/GLB, USD/USDA/USDC/USDZ, FBX, OBJ, ABC, PLY, STL | | Native SDK | C++ via `@bellona/sdk-cpp` | | Build | Nx with `@nx/js:tsc` | | Testing | Vitest / Jest | ### Technology Rationale - **Event-driven build API** allows Bellona to be a passive consumer of upstream domain events, keeping domains fully decoupled from the build system. - **Redis content-addressable cache** enables zero-cost delivery of previously-built artifacts with a single hash lookup, critical for large asset pipelines where reprocessing is expensive. - **WebSocket bridges over REST** is the correct choice for engine integration because engine editors run as long-lived local processes; a persistent bidirectional channel is necessary for real-time sync, live preview, and low-latency command dispatch. - **Shared bridge-core protocol** across all four bridges reduces the surface area of the protocol, making it easier to implement engine-side clients (Unity C#, Unreal C++, Godot GDScript, Blender Python). - **Prisma ORM** provides type-safe database access with migration support appropriate for a PostgreSQL schema of 11 models. - **MinIO in development** makes the S3 object storage interface available locally without AWS credentials, enabling full-fidelity artifact storage testing. --- ## 7. Project Structure The directory layout below shows all 12 apps and 34 libraries with their primary purpose. This is the canonical source of truth for what packages exist in the domain. ``` apps/bellona/ (12 apps) build-api/ # Event-driven build orchestration module build-worker/ # Background job processor (4 job types) render-api/ # Render caching and output validation module cli/ # bellona CLI (Commander.js) bridge-unity/ # Unity WebSocket bridge (Port 9004) bridge-unreal/ # Unreal WebSocket bridge (Port 9003) bridge-godot/ # Godot WebSocket bridge (Port 9002) bridge-blender/ # Blender WebSocket bridge (Port 9001) control-room/ # Browser-first remote-control operator UI (React/Vite) remote-gateway/ # Remote-control gateway service remote-host/ # Remote-control host agent libs/bellona/ (34 libraries) bridge-core/ # WebSocket bridge protocol foundation adapters/ # BaseBridge, CommandQueue, StateManager, ProcessLauncher client/ # TypeScript SDK (@bellona/client) database/ # Prisma schema and generated client interchange/ # 3D format conversion pipeline interchange-models/ # Interchange data schemas integration/ # Hathor / Isis consumers and compilers asset-export/ # Asset export readiness/conversion planning unity/ # Unity adapter unreal/ # Unreal adapter (+ BellonaUnrealEditor plugin) godot/ # Godot adapter blender/ # Blender adapter houdini/ # Houdini integration maya/ # Maya bridge runtime contracts 3dsmax/ # 3ds Max bridge runtime contracts davinci/ # DaVinci Resolve integration openusd/ # OpenUSD pipeline (MaterialX) blender-agent/ # Blender-native agent runtime unity-agent/ # Unity Editor MCP server package cross-dcc-consistency/ # Cross-DCC workflow consistency contracts editor-productization/ # Editor release/onboarding/diagnostics contracts gameplay-systems/ # Input, save/load, inventory, combat, AI metahuman/ # MetaHuman pipeline mocap/ # Motion capture streaming, retargeting, frame-snap virtual-production/ # Camera tracking, LED wall, ICVFX xr/ # visionOS, Meta Quest, WebXR audio/ # Audio processing video/ # Video processing sdk-cpp/ # C++ native SDK remote-protocol/ # Remote-control protocol contracts mcp-gateway/ # Remote-control MCP gateway server event-publisher/ # Typed event publishing event-handlers/ # Cross-domain event subscriptions ``` --- ## 8. Deployment Architecture In production, each Bellona service runs as a separate container, allowing independent scaling. Build workers, which perform CPU- and GPU-intensive work, run on EC2 instances with GPU capability rather than serverless Fargate. ``` ┌─────────────────────────────────────────────────────────────┐ │ ECS Cluster │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │ build-api │ │ render-api │ │ build-worker │ │ │ │ (Fargate) │ │ (Fargate) │ │ (EC2 GPU) │ │ │ └──────┬───────┘ └──────┬───────┘ └────────┬─────────┘ │ │ │ │ │ │ │ ┌──────┴─────────────────┴────────────────────┴────────┐ │ │ │ Redis │ │ │ │ (cache + event bus) │ │ │ └──────────────────────┬────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────┴────────────────────────────────┐ │ │ │ PostgreSQL │ │ │ │ (bellona schema) │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────┐ ┌──────────────┐ ┌─────────────────────┐ │ │ │bridge-unity │ │bridge-unreal │ │bridge-godot/blender │ │ │ │ (Fargate) │ │ (Fargate) │ │ (Fargate) │ │ │ └─────────────┘ └──────────────┘ └─────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ┌─────────┴─────────┐ │ S3 (MinIO dev) │ │ Build artifacts │ └───────────────────┘ ``` - **build-api and render-api** run on AWS Fargate (serverless container compute) for independent scaling - **build-worker** runs on EC2 instances with GPU capability for shader compilation, texture baking, and render operations - **Bridge services** run on Fargate and expose WebSocket ports via an Application Load Balancer with WebSocket upgrade support - **Redis** is shared between the build cache, render cache, and event bus - **PostgreSQL** is a shared RDS instance with the `bellona` schema isolated from other domain schemas - **S3 / MinIO** stores build artifacts and export packages; MinIO is used locally to avoid AWS dependencies in development --- ## 9. Cross-Domain Dependencies Understanding Bellona's dependencies requires distinguishing between two kinds of relationships. Upstream domains trigger Bellona by publishing events that Bellona subscribes to. Bellona then notifies downstream consumers by publishing its own events in response. No domain calls Bellona directly over HTTP. ### Libraries Bellona Depends On | Library | Usage | | ------------------ | --------------------------------------------------- | | `@oshun/event-bus` | Redis-backed pub/sub for all cross-domain events | | `@oshun/logging` | Structured logging across all apps and libraries | | `@oshun/cache` | Redis client / cache primitives for the build cache | | `@oshun/contracts` | Event-type constants and Zod payload schemas | | `@oshun/metrics` | Event-handler metrics registry | ### Domains That Trigger Bellona | Domain | Integration | | ------ | -------------------------------------------------------------------------------------------------------------------- | | Yemaya | Publishes `yemaya.build.requested` and `yemaya.export.requested` events that Bellona processes | | Hathor | Publishes `hathor.world.published` events; Bellona compiles lore to engine-native formats via `LoreToEngineCompiler` | | Isis | Publishes `isis.asset.generated` events; Bellona bakes and converts generated assets via `AssetConverter` | ### Events Bellona Publishes (Consumed by Other Domains) | Event | Likely Consumers | | ------------------------- | -------------------------------------------- | | `bellona.build.completed` | Yemaya (notify creator of ready build) | | `bellona.export.ready` | Yemaya (expose download URL to creator) | | `bellona.asset.synced` | Hathor (confirm engine sync of world assets) | | `bellona.session.started` | Monitoring / observability | | `bellona.session.ended` | Monitoring / observability | ### Domain Responsibility Boundaries Bellona's scope is precisely defined relative to its neighboring domains. Bellona owns engine bridges, build pipeline, render pipeline, asset interchange, and runtime integration. It does not own the content itself. **Neith** owns the sovereign engine, renderer, and DCC primitives that Bellona bridges and exports. **Yemaya** owns creative production orchestration — Bellona executes the builds Yemaya requests but does not own the production workflow. **Hathor** owns narrative and world modeling; Bellona only consumes Hathor artifacts. **Isis** owns generative media creation; Bellona only adapts and packages its outputs. ### Optional Infrastructure | Service | Purpose | Profile | | ------- | ------------------------------------------- | ------------- | | Qdrant | Not used by Bellona directly | — | | MinIO | Local S3-compatible artifact storage in dev | default (dev) | | Redis | Build cache, render cache, event bus | required |