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 catalog (7)#
The 7 tracked Nx projects in v3, each a code-linked entity node — package, type, source path, declared targets, and its internal dependency graph (depends-on / used-by, resolved from the package manifests, §6/§8), read from the project graph. Grouped by architectural layer; walk the dependency links to travel the system. 7 of these carry an authored deep-dive (what / why / how it fits); the rest are generated scaffolds awaiting one.
service (5)#
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.
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).
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.
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_*).
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.
web (2)#
V3 browser shell for Pixel Streaming entry.
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.
V3 Tier-2 three.js fallback app shell.
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).