Neith Domain — Architecture

Architectural overview of the Neith sovereign runtime kernel: Rust crate workspace organization, design philosophy, dependency model, and cross-domain usage.

Neith is the lowest software layer in the entire Oshun stack. Every performance-critical application in the monorepo — the Maya game engine, the Aphrodite VR streaming client, the Nyx star map — runs on top of Neith, never the other way around. The domain is named after the ancient Egyptian creator goddess who wove the world into existence: Neith literally weaves the fabric on which everything else is built.

The domain lives in libs/neith/ and is organized as approximately sixty self-contained Cargo workspaces (plus a small set of standalone TypeScript support packages). Each workspace bundles one or more focused Rust crates. Because Neith has no upstream monorepo dependencies, any individual crate can be compiled and embedded in isolation — outside the Oshun monorepo entirely — which is a hard architectural invariant.

A new engineer should think of Neith as three concentric rings:

1. Foundational engine workspaces (core, crypto, hal, net, renderer, ui) — battle-hardened, fully implemented, and described in detail in specifications.md.
2. Extended platform workspaces (ai-runtime, scene, assets, particles, procgen, weaver, embedded, android, vr-os, browser, linux, and the audio-suite and creative-tool collections) — each following the same workspace structure as the foundational six.
3. Sovereignty closure roadmap (Phases 132–174) — planned workspaces that will extend Neith from a runtime kernel into a complete replacement for external runtimes, creative suites, and platform infrastructure.

Design Philosophy#

The five principles below are strict architectural rules, not preferences. Every crate addition or change must be evaluated against them.

1. Sovereign and self-contained — Neith has no upstream dependencies within the monorepo. It depends only on carefully audited Rust crates from crates.io. All of Oshun's performance-critical systems build on Neith, not the other way around.
2. No Tokio dependency — The Neith async runtime is custom-built on crossbeam and mio. This enables embedding in game loops, VR render loops, and other contexts where Tokio's threading model is incompatible.
3. Platform-agnostic abstractions — HAL crates provide unified interfaces for GPU, audio, input, camera, and sensors. Platform-specific code is encapsulated; consumer code is portable.
4. Composable crates — No Neith crate forces consumers to take all of Neith. A project that only needs neith-physics and neith-render-graph takes just those crates.
5. Backend-agnostic GPU abstraction — neith-gpu exposes a single Backend enum spanning Vulkan, Metal, DirectX12, WebGPU, and Software, so renderer code is written once against the abstraction regardless of the target backend.

Crate Dependency Graph#

The diagram below shows how the major crate groups relate to each other and to the consumer domains. Arrows point from consumer to dependency.

Consumer Code (Maya, Aphrodite VR, Nyx StarMap)
        │
        ├── renderer workspace (render-graph, pbr, gi, postfx, physics...)
        │       └── neith-gpu (HAL) → self-contained GPU abstraction
        │
        ├── neith-physics → self-contained (own broadphase/GJK/EPA/solver)
        │
        ├── neith-game-net (networking)
        │       ├── neith-transport (reliable UDP)
        │       └── neith-webrtc → WebRTC stack
        │
        ├── neith-audio-hal → platform audio (cpal)
        │
        ├── neith-input → unified input event abstraction
        │
        └── neith-runtime (async executor)
                ├── neith-events (event bus)
                ├── neith-alloc (memory)
                └── neith-serde (serialization)
                        └── crossbeam-deque, mio, serde

Two implementation details are important to call out here because they differ from common assumptions:

neith-gpu is not a thin wgpu wrapper — it is a self-contained abstraction defining its own Backend enum (Vulkan, Metal, DirectX12, WebGPU, Software), handle types and GpuDevice trait. neith-physics implements its own sweep-and-prune / BVH broadphase, GJK/EPA narrowphase and constraint solver over plain [f32; 3] math types — it does not depend on rapier3d. The only external real-time crate used in the foundational workspaces is cpal (audio HAL).

Workspace Architecture#

libs/neith/ contains approximately sixty Cargo workspaces plus a small set of standalone TypeScript packages. The six foundational engine workspaces are shown below; the remaining workspaces — ai-runtime, scene, assets, particles, procgen, weaver, embedded, android, vr-os, browser, linux, the audio-suite workspaces (audio-runtime, audio-graph, composer, vst3-host, clap-host, notation, …) and the creative-tool workspaces (sculptor, animator, cutter, forge-core) — follow the same structure (Cargo.toml workspace manifest + crates/ + project.json). The full inventory is enumerated in specifications.md.

libs/neith/
│
├── core/                   ← async runtime, memory, serialization, events, reflection
│   ├── Cargo.toml          ← workspace manifest
│   ├── rust-toolchain.toml ← pinned nightly/stable toolchain version
│   └── crates/
│       ├── neith-runtime/  ← work-stealing executor
│       ├── neith-alloc/    ← allocator and memory budgets
│       ├── neith-serde/    ← zero-copy serialization
│       ├── neith-reflect/  ← runtime type metadata
│       ├── neith-events/   ← typed in-process event bus
│       └── neith-log/      ← structured diagnostics
│
├── crypto/                 ← all cryptographic primitives
│   └── crates/
│       ├── neith-hash/     ← SHA, BLAKE3, HMAC
│       ├── neith-asym/     ← Ed25519, X25519, RSA, ECDSA
│       ├── neith-sym/      ← AES-GCM, ChaCha20-Poly1305
│       ├── neith-rand/     ← CSPRNG, deterministic RNG
│       └── neith-tls/      ← TLS 1.3 via rustls
│
├── hal/                    ← hardware abstraction layer
│   └── crates/
│       ├── neith-gpu/      ← GPU device, buffers, pipelines (self-contained abstraction)
│       ├── neith-camera/   ← camera capture and calibration
│       ├── neith-input/    ← gamepad, keyboard, mouse, XR input
│       ├── neith-audio-hal/ ← audio device streams (cpal)
│       ├── neith-storage/  ← async file I/O, asset streaming
│       ├── neith-sensor/   ← IMU, GPS, environmental sensors
│       └── neith-net-hal/  ← network interface abstraction
│
├── net/                    ← networking crates
│   └── crates/
│       ├── neith-http/     ← HTTP/1.1, HTTP/2 client and server
│       ├── neith-transport/ ← UDP, reliable UDP, QUIC
│       ├── neith-webrtc/   ← WebRTC data channels and media
│       └── neith-game-net/ ← interest management, delta compression, prediction
│
├── renderer/               ← 16-crate workspace: rendering + physics + ECS + scripting
│   └── crates/
│       ├── neith-render-graph/      ← frame graph, pass scheduling, barriers
│       ├── neith-pbr/               ← GGX BRDF, IBL, area lights
│       ├── neith-gi/                ← GI probes, SDF GI, reflections
│       ├── neith-shadows/           ← CSM, point shadows, soft shadows
│       ├── neith-lighting/          ← directional/point/spot/area, IES, MegaLights
│       ├── neith-material-graph/    ← node-based material system
│       ├── neith-postfx/            ← TAA, SSAO/GTAO, bloom, DoF, tonemap
│       ├── neith-atmosphere/        ← Rayleigh/Mie scattering, clouds
│       ├── neith-virt-geom/         ← Nanite-class virtualized geometry
│       ├── neith-gpu-driven/        ← multi-draw indirect, GPU culling
│       ├── neith-gaussian-splatting/← 3D Gaussian splatting renderer
│       ├── neith-physics/           ← self-contained physics, deterministic step
│       ├── neith-audio/             ← engine audio
│       ├── neith-ecs/               ← archetype-based entity component system
│       ├── neith-scripting/         ← Lua, WASM, visual scripting
│       └── neith-animation/         ← skeletal, blend-tree animation
│
└── ui/                     ← UI rendering and widget system
    └── crates/
        ├── neith-render2d/   ← 2D batch renderer, SDF shapes
        ├── neith-text/       ← font loading, text shaping, layout
        ├── neith-layout/     ← Flexbox/grid layout engine
        ├── neith-widgets/    ← retained-mode widget tree
        ├── neith-theme/      ← design token system in Rust
        └── neith-animation/  ← spring physics, gesture-driven UI animation

Render Graph Architecture#

Every frame, all rendering work — shadow maps, global illumination probes, opaque geometry, transparent geometry, and post-processing — is expressed as nodes in a directed acyclic graph (DAG). The render graph compiler schedules those nodes automatically, inserts GPU pipeline barriers where needed, and aliases transient resources to minimize GPU memory usage. Consumer code never writes manual synchronization.

The diagram below shows a single frame's DAG from left to right, converging at the final present step:

Frame N:
  [Shadow Pass] ──────────────────────────────┐
                                              │
  [GI Probe Update] ──────────────────────────┤
                                              │
  [Opaque Geometry Pass] ──────────────────── ▼
                                        [Lighting Composite]
  [Transparent Geometry Pass] ────────────── ▼
                                        [Post-Processing Chain]
                                        (TAA → SSAO → Bloom → Tonemap)
                                              │
                                         [Present]

Resource handles are declared per pass using TextureDesc and related types from neith-render-graph::resource. The compiler runs a Kahn topological sort (compiler::ordering) to determine pass order. Automatic resource allocation and GPU pipeline barrier insertion follow from that sorted order. No manual synchronization is required in consumer code.

Physics Integration Architecture#

neith-physics runs as a fixed-tick simulation that is fully decoupled from the render frame rate. Each tick, the engine advances through four sequential stages: broadphase (cheap candidate-pair detection), narrowphase (precise contact generation), constraint solving (velocity correction), and integration (position update). The resulting body positions are then read by the Maya engine and applied to ECS entity transforms.

Game Loop (60Hz fixed tick)
        │
        ▼
neith-physics::PhysicsWorld::step(dt: f32)
        │
        ├── Broad phase: BVH tree collision candidate detection
        │
        ├── Narrow phase: GJK/EPA contact generation
        │
        ├── Constraint solver: iterative velocity correction
        │
        └── Integration: Euler semi-implicit position update
                │
                ▼
        RigidBody positions available for read (bodies keyed by usize index)
                │
                ▼
        @maya/engine applies to ECS entity transforms

PhysicsWorld::step(dt) exercises the neith-physics crate's own SapBroadphase/BvhTree broadphase, gjk_closest_points/epa_penetration narrowphase, and constraint solver — there is no external physics dependency.

Build Architecture#

Each Cargo workspace under libs/neith/ carries a project.json that exposes Nx targets via the nx:run-commands executor — build, test, lint (cargo clippy -- -D warnings), and fmt — each shelling out to cargo with --manifest-path libs/neith/<workspace>/Cargo.toml. Toolchains are pinned per workspace via rust-toolchain.toml.

libs/neith/<workspace>/
        │
        ├── Cargo.toml          ← [workspace] manifest + pinned deps
        ├── rust-toolchain.toml ← pinned toolchain
        ├── project.json        ← Nx targets → cargo build/test/clippy/fmt
        └── crates/             ← member crates

The foundational engine crates are consumed as native Rust crates — there is no wasm-bindgen/napi-rs binding layer for core, crypto, hal, net, renderer, or ui. neith-gpu exposes a WebGPU value in its Backend enum as a backend target, not as a JS interop boundary.

The standalone TypeScript packages under libs/neith/ (@neith/cloud, @neith/docs, the integration-* packages, and others) are independent TypeScript libraries built with tsup/tsc. They are not generated bindings to the Rust crates — they are separate infrastructure concerns (cloud management, observability, domain integration adapters) that happen to live under the same directory.

Cross-Domain Consumers#

The table below shows which Neith crates each consuming domain uses and what problem they solve. Neith never depends on any of these consumers; the dependency arrow always points toward Neith.

Why the boundary exists#

Each consuming domain owns its own product layer. Maya owns the virtual-world and gameplay logic; Bellona owns external engine export bridges; Aphrodite owns the VR streaming client UX. Neith owns none of those product concerns — it provides only the low-level primitives those products build on.

This separation means Neith crates can be compiled, tested, and embedded independently of any product decision. A change to Maya's game loop cannot break a Neith crate build. Conversely, upgrading a Neith primitive (say, replacing the broadphase algorithm) automatically benefits all consumers without requiring them to change their code.

Neith Has No Upstream Monorepo Dependencies#

Neith is the lowest layer of the Oshun stack. It imports nothing from other Oshun domains or libs/shared/. This is a hard invariant — maintaining it ensures Neith crates remain independently buildable and embeddable outside the Oshun monorepo. Any pull request that introduces an import from another Oshun domain into a Neith Rust crate must be rejected.