# V3 — Systems Deep Dive

> The `apps/v3/` area: the seven deployable applications behind the V3 "Lilith /
> Saraswati" real-time 3D experience — five Rust control/data-plane services
> plus two Next.js browser shells — that together stream the Lilith Commons and
> Saraswati concert worlds to the browser.

## What this area is

V3 is the real-time, multiplayer 3D product tier of the monorepo: members enter
the **Lilith Commons Atrium** (and sibling venues — Tara Studio, Saraswati
Stage) either through an Unreal Engine **Pixel Streaming** worker or, on
constrained devices, a **Tier-2 three.js / WebGPU fallback** rendered locally.
`apps/v3/` holds the _applications_ for that tier (not the libraries): seven
tracked Nx projects, every one of which is a real, implemented app — there are
no empty scaffolds in this area.

The seven split into two technology families. **Five are Rust backend
applications** — `lilith-world-server`, `lilith-realtime-gateway`,
`lilith-pxstream-relay`, `lilith-commerce-service`, and `saraswati-service` —
sharing a single Cargo workspace at `apps/v3/Cargo.toml` (`resolver = "2"`,
`unsafe_code = "forbid"`). All five build with `cargo build -p <crate>` driven
through `nx:run-commands`, and all five carry an `implicitDependencies` edge to
`@oshun/multiplayer-protocol` — the `multiplayer_protocol` crate at
`libs/v3/multiplayer-protocol/rust`, which gives them a shared wire format
(`encode_presence_packet`, `encode_service_health`, `serve_http_health`,
`SnapshotPacket`/`EntityTransform`). **Two are Next.js applications** —
`@oshun/v3-lilith-web` (port 3041) and `@oshun/v3-lilith-web-fallback`
(port 3042) — typed in TypeScript/React and tested with Vitest + Playwright.

The Rust services divide the real-time plane by responsibility: the
**world-server** is the authoritative room/snapshot/presence shard (port 43101);
the **realtime-gateway** is the transport edge — WebTransport over QUIC with a
WebRTC/WebSocket fallback and a voice SFU (port 43102); the **pxstream-relay**
is the Pixel Streaming matchmaker, worker autoscaler, and admission controller
(port 43103). Alongside those two domain services carry V3 business logic:
**commerce-service** (royalties, subscriptions, tips, tickets, refunds,
fan-token boundaries) and **saraswati-service** (the concert performance
pipeline and C2PA-signed recording exports).

The two web shells are the clients to that plane. `lilith-web` is the primary
Pixel Streaming entry surface; `lilith-web-fallback` is the locally-rendered
Tier-2 surface with one route per tenant. Both compose the same V3 accessibility
and tenant libraries (`@oshun/tenant-lilith-commons`, `@oshun/spatial-audio`,
`@oshun/design-tokens`).

## How it fits the wider system

These apps sit at the top of the V3 stack and depend downward on the V3
libraries in `libs/v3/` (and shared platform libs). The Rust services consume
`@oshun/multiplayer-protocol` for their wire and health contracts; the web
shells consume the per-tenant and capability libraries via
`implicitDependencies` — `lilith-web` pulls `@oshun/lilith-web-pxstream`,
`@oshun/lilith-identity-bridge`, `@oshun/tenant-lilith-commons`,
`@oshun/spatial-audio`, `@oshun/navigation`, and `@oshun/ui`;
`lilith-web-fallback` pulls `@oshun/lilith-engine-web-fallback`,
`@oshun/tenant-saraswati-stage`, `@oshun/sophia-saraswati-grounding`, and
`@oshun/spatial-audio`. The browser shells reach the services over HTTP at run
time — `lilith-web` POSTs to `/api/v3/pxstream/match` (served by the relay) to
obtain a worker, and `lilith-web-fallback` connects to the realtime-gateway with
transport fallback. Walk the "used by" / "depends on" edges on each node below
for the exact graph.

## Entity reference

### v3-lilith-world-server

The authoritative room-shard server for V3 (`apps/v3/lilith-world-server`, port
43101). Its `src/lib.rs` builds an `axum` `RoomRegistry` that owns participant
state (`ParticipantState`, `EntityTransform`), snapshot authority, presence
visibility bands (`VisibilityBand`: public/tenant/cohort/invited/invisible), and
a long list of V3-specific gameplay rules baked into its `SERVICE_DESCRIPTOR`
capabilities — server-validated pickup/place, asana-lock and physical-adjustment
explicit consent, Tara live-class spawn, and opt-in recording. Physics use
`rapier3d`/`nalgebra` and spatial queries use an `rstar` R-tree. The
`durable_persistence` module is real: `PostgresDurableSessionStore` writes
session-boundary checkpoints via `sqlx` and `RedisHotStateStream` appends
hot-state via Redis `XADD`/`XREVRANGE`, with `recover_room_from_redis_hot_state`
replaying the latest checkpoint on crash (exercised by a live Postgres+Redis
round-trip integration test). `run_service()` binds `build_router()`
(`/healthz`, `/readyz`, `/metrics`) with `axum::serve`; the `tests/` directory
holds focused suites (`pickup_place`, `asana_lock`, `visibility_band`,
`tara_*`).

### v3-lilith-realtime-gateway

The real-time transport edge (`apps/v3/lilith-realtime-gateway`, port 43102).
Its `src/lib.rs` implements a **WebTransport-over-QUIC** echo edge using `quinn`
(`spawn_quinn_webtransport_echo_server`, `quinn_webtransport_echo_round_trip`,
`configure_quinn_server`/`configure_quinn_client` with `rustls` self-signed
certs) plus a **WebSocket fallback** echo server
(`spawn_websocket_fallback_echo_server`) for the WebRTC-fallback path. It also
owns the V3 auth handshake: `AuthPrimitiveJwtConfig` and
`JwtRefreshRotationConfig` (HMAC-SHA256, 15-minute access / 30-day refresh
rotation, `v3:realtime` scope). The declared capabilities span the voice SFU
(`voice-sfu`, `livekit-compatible-sfu`, `opus-24kbps-mono`,
`listener-position-hrtf`, `operator-sfu-controls`, `voice-chat-opt-in-policy`).
Tests in `lib.rs` run real QUIC and WebSocket echo round-trips. `run_service()`
serves the gateway; `main.rs` is a thin wrapper.

### v3-lilith-pxstream-relay

The Pixel Streaming control plane (`apps/v3/lilith-pxstream-relay`, port 43103).
`src/lib.rs` builds an `axum` matchmaker router exposing the real endpoints the
browser shell calls — `PXSTREAM_MATCH_PATH` (`/api/v3/pxstream/match`),
signalling exchange, autoscale plan, scheduled concert pre-warm, admission
evaluate, and a POP-capacity dashboard — wired in `matchmaker_router()` and
served by `run_service()` via `axum::serve`. It encodes V3 streaming policy as
typed constants: first-frame budget (8 s), free-tier limits
(`PXSTREAM_MAX_FREE_TIER_MINUTES_PER_DAY = 120`, per-user/per-network session
caps), abuse-admission thresholds in basis points, and POP capacity-forecast
lead times. Session JWTs are HMAC-SHA256 (`hmac`/`sha2`, base64-url). It targets
the Epic UE5.5 signalling protocol (`EPIC_SIGNALLER_PROTOCOL_VERSION`) and ships
an operational planning doc at `config/pops/quota-review-2026-05-22.md` (GPU
quota across AWS G6e / Azure NVadsA10 / GCP L4, festival burst pools).

### v3-lilith-commerce-service

The V3 commerce domain service (`apps/v3/lilith-commerce-service`). It is
structured as a domain-logic library plus a health binary: `run_service()`
serves only `serve_http_health`, while the real value is the set of fully
implemented modules re-exported from `src/lib.rs`. These cover Lilith and
Saraswati monetization — `lilith_royalty_waterfall` (basis-point splits across
Artist / Producer / VoiceContributor / PromptContributor / PlatformReserve, with
Stripe-Connect and Aje-native-USDC payout routing and quarterly settlement),
`lilith_subscription_billing`, `lilith_tip_routing`, `lilith_ticket_issuance`,
`lilith_cancellation_refunds` (user/platform/provider-outage cancellation,
chargeback handling, tax-reversal flows), `lilith_fan_token_boundaries`,
`lilith_platform_billing_bridges` (Apple IAP / Google Play / PSN wallet policy
refs), `lilith_rights_takedown_cascade`, and the `saraswati_*` counterparts
(club pass, concert tips, signed editions, remix rights, free tier). Logic is
domain-specific (real basis-point math against `BASIS_POINTS_DENOMINATOR`,
policy-ID constants, region allowlists), with unit tests across ~14 source
files.

### v3-saraswati-service

The Saraswati concert-pipeline service (`apps/v3/saraswati-service`). Like the
commerce service it pairs a health binary (`run_service()` →
`serve_http_health`) with a rich domain library. `src/lib.rs` performs **real
C2PA provenance signing** using the `c2pa` crate — `Builder::from_json`,
`create_signer::from_keys` (ES256), and `Reader::from_manifest_data_and_stream`
verification — emitting concert-recording manifests with custom assertions
(recording-consent, rights-waterfall, generated-artifact-provenance,
Adobe-CAI-verification). The performance pipeline is modular: `performance_plan`
compiles a `ConcertPerformancePlanRequest` into a sequencer asset bound to UE
cue tracks (`SequencerCueTrackType`: music-sync, lighting, particles,
persona-motion, audience-cam, between-song-speech) targeting a
`/Game/Saraswati/Templates/ConcertMaster` master and a MinIO bucket. Other
modules cover `per_song_execution` (music-sync drift simulation across client
tiers), `pre_show_warmup`, `between_song_speech`, `audience_interaction`,
`stage_transition`, `stadium_tier_fallback`, `festival_event_flow`,
`drop_day_flow`, `recording_pipeline`, `royalty_settlement`, and
`tier2_cue_forwarding` — each with its own schema constant and latency/drift
budgets.

### @oshun/v3-lilith-web

The primary V3 browser shell (`apps/v3/lilith-web`, port 3041) — per its README,
"V3 browser shell for Pixel Streaming entry." It is a Next.js App-Router app
whose `src/app/LilithLanding.tsx` is the main client surface: it creates a Pixel
Streaming client (`createLilithPixelStreamingClient` /
`createEpicPixelStreamingAdapter`), matches a worker by POSTing the launch
request to `/api/v3/pxstream/match` (the relay endpoint), and mounts the stream
into the Commons Atrium frame with live status, mic-consent, and reconnect
controls. The shell is built around an extensive accessibility surface sourced
from `@oshun/tenant-lilith-commons` and `@oshun/spatial-audio` — reduced motion,
color-vision palettes, one-handed mobile HUD, photosensitive safe mode,
spatial-audio-off (flat stereo), cognitive-load reduction,
keyboard/single-switch navigation, launch localization, audio-description bed,
and live avatar captions — each surfaced as `data-*` attributes for E2E
assertion. It also integrates Tara live-class booking (`bookTaraLiveClass`) and
a cross-tenant weekly programming calendar. `src/index.ts`
(`createLilithWebShellState`) computes the required capability set and readiness
score. Localized HUD strings live under `locales/` (20+ locales, incl. RTL
`ar`/`he`). Tested via Vitest unit specs and Playwright E2E.

### @oshun/v3-lilith-web-fallback

The Tier-2 three.js / WebGPU fallback shell (`apps/v3/lilith-web-fallback`,
port 3042) — per its README, the "V3 Tier-2 three.js fallback app shell." A
Next.js app with a `[tenant]` dynamic route, it renders one of three
locally-drawn scenes (`tenantScenes.ts`: `commons`, `tara-studio`,
`saraswati-stage`) via `FallbackThreeCanvas`, with per-tenant fidelity profiles
(baked lighting, reduced particles, 30/60 fps targets).
`src/app/FallbackExperience.tsx` is a large client component that composes
`@oshun/lilith-engine-web-fallback` (Rapier prop-pickup misprediction
prediction, gateway connect-with-fallback against the realtime-gateway,
browser/network profile detection, Tara instructor HUD, recording timeline
scrub + practice room + engagement telemetry), `@oshun/spatial-audio` (a real
Web-Audio spatial runtime plus flat-stereo mode), the Commons educational scenes
from `@oshun/tenant-lilith-commons` (Nisaba open-stack shelves, Metis lecture
hall/breakouts/assessment review, Veritas debate hall turn machine + inline
Sophia citations, Arete journal/cohort review), and the Saraswati in-world
discography catalog. A service worker (`public/v3-tier2-sw.js`, registered via
`serviceWorkerCache.ts`) provides offline asset caching with cold/warm-join
budgets. `src/index.ts` (`createLilithFallbackShellState`) computes the fallback
capability set and readiness. Tested via Vitest and Playwright (including a
service-worker-cache spec).