# 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//Cargo.toml`. Toolchains are pinned per workspace via `rust-toolchain.toml`. ``` libs/neith// │ ├── 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. | Domain | Neith Crates Used | Purpose | | --------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------- | | Maya (`@maya/engine`) | render-graph, pbr, gi, shadows, lighting, postfx, atmosphere, virt-geom, gpu-driven, physics | Full game engine rendering and physics | | Maya (`@maya/nexus`) | game-net, transport | Multiplayer netcode | | Maya (`@maya/immersion`) | input, sensor, gpu | VR device abstraction | | Maya (`@maya/engine/audio`) | audio-hal | Spatial audio system | | Aphrodite (VR streaming) | render2d, widgets, webrtc | VR streaming client UI and WebRTC | | Nyx (Star Map) | render2d, render-graph | WebGL star map rendering | | Nyx (VR Planetarium) | render-graph, pbr, atmosphere | VR sky rendering | ### 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.