Figures
All diagrams and charts referenced throughout the bible
Overview
1
Solution Architecture OverviewFour major subsystems (Game Data, Simulation Engine, Portal, Hosted Pool) and their data flow from DBC files through to simulation results.overview/motivation
2
System ContextThe whole platform at one zoom level: Browser, Edge (Cloudflare), Game Data (Supabase), Engine, sentinel, beacon, Nodes, and supporting Infra, with the in-browser WASM path and the hosted node path shown as the two branches that run the same engine.overview/architecture
3
Hosted Job LifecycleA hosted simulation end to end: studio creates a job in Supabase, a NOTIFY on pending_job wakes the sentinel scheduler, chunks publish to chunks:{node}, the node runs simulate_intent and POSTs a signed completion to /chunks/complete, the sentinel finalizes and publishes progress on jobs:{id}, and studio renders.overview/architecture
4
Rust Crate Dependency GraphExpands the Engine box of the system context: the engine workspace split by clean-architecture layers (ports, domain, combat, sim, content, application, adapter-data) and the node and sentinel host shells that drive it.overview/architecture
5
Language Decision MatrixDecision tree showing key requirements and how each candidate language meets or fails them.overview/language-evaluation
6
Rotation Compilation PipelineFull path from JSON APL definition through AST parsing, schema validation, and IR generation to native machine code, with the WASM interpreter fallback branch.overview/rotation-language
7
Scripting Language EvolutionProgression from Lua to Rhai to custom DSL to expression trees to JIT-compiled APL with rejection reasons at each stage.overview/rotation-language
Game Data
8
Data Resolution PipelineExpands the Game Data box of the system context: the three sources (CSV, Supabase, JS bridge) behind the DataResolver port, the DBC-to-flat transform, and the resolve_game_data pass that folds them into ResolvedGameData.game-data/data-resolution
9
Game Data Cache LayersExpands the GameDataCache box of the data-resolution pipeline: the L1 Moka memory, L2 disk JSON, and L3 PostgREST read-through path, plus patch-version invalidation.game-data/data-resolution
10
Spec Codegen PipelineExpands the build-time content facet of the Engine box: per-spec manifests/*.toml validated against manifest-schema, compiled by codegen-cli into engine-content/src/generated, whose builder functions read ResolvedGameData at bootstrap.game-data/codegen
Engine
11
Simulation PipelineExpands the Engine box of the system context: simulate_intent bootstraps (descriptor, gear to stats, resolve_game_data, build handler), then run_chunk drives SimEngine.run per iteration and accumulates telemetry into a ChunkReport.engine/discrete-event-simulation
12
SimEngine Event LoopExpands the SimEngine.run box of the simulation pipeline: the eight Event variants and the scheduling transitions between them, with the encounter-end and event-budget terminals.engine/event-system
13
Timing Wheel Event QueueExpands the EventQueue box of the simulation pipeline: 32768 slots of 32 ms with a bitmap scan, an arena and free list for nodes, and an overflow bucket reinserted on wheel rotation.engine/event-system
14
Rotation Compilation (JIT vs Interpreter)Expands the build-handler box of the simulation pipeline: JSON to parse_and_validate to lower::prepare to the shared lower_rotation, lowered through either the LLVM JIT backend or the interpreter to one EvalResult; the WASM build and decision-trace mode use the interpreter.engine/rotation-compiler
15
DenseBuffer Slot ModelExpands the DenseBuffer box of the rotation compiler: singleton slots (player, combat, pet) and keyed maps (cooldown, aura, resource, spell, ...) as repr(C) 8-aligned structs in one flat byte buffer, indexed by the FieldDescriptor inventory.engine/rotation-compiler
16
process_cast PipelineExpands the CastComplete handling of the SimEngine loop: the thirteen steps of process_cast from spell lookup through resources, channel branch, cooldown, damage, aura, cooldown reduction, hooks, stealth, and history.engine/cast-pipeline
17
Damage Calculation PipelineExpands the deal_damage step of process_cast: DamageCalc::calculate in order — weapon roll, raw (base plus coefficient times attack power), crit, versatility, armor mitigation, damage multiplier, mastery.engine/combat-formulas
18
Aura LifecycleExpands the apply_aura step of process_cast: the aura state machine through fresh application, pandemic refresh (30% carryover), periodic tick rescheduling, snapshotting, and expiry.engine/auras
19
Telemetry and Metrics PipelineExpands the telemetry box of the simulation pipeline: per-iteration TelemetrySink events fold into the TelemetryAccumulator (per-second buckets, representative iteration, running stats), merge across chunks, and encode to a protobuf ChunkTelemetry.engine/metrics
Distribution
20
Chunk Execution LifecycleExpands the run_chunk loop box of the simulation pipeline: a chunk moves Assigned to Bootstrapped to Running, then to ConvergedEarly (adaptive target_error) or Exhausted to Reported, or Failed on event-budget overflow.distribution/orchestration
21
WASM BoundaryExpands the Browser box of the system context: the engine and common crates compiled to wasm-bindgen exports, loaded in a Comlink web worker, with JsResolver adapting the JS resolver (in-memory, IndexedDB, Supabase).distribution/wasm-boundary
22
Browser Worker PoolExpands the web-worker box of the WASM boundary: a pool slot from initializing to idle to busy (fetching, simulating, signing, submitting) and back, with watchdog timeout to restart.distribution/wasm-boundary
23
Realtime TopologyExpands the beacon box of the system context: sentinel and clients over Centrifugo, with NATS as the broker and Redis as the presence manager, the chunks/nodes/jobs channel namespace, and studio's ownership-checked token mint.distribution/realtime
24
Hosted Compute FlowExpands the Nodes box of the system context: the sentinel assigns a chunk, the node receives it on chunks:{key}, fetches its work context, runs simulate_intent in its worker pool, signs the result, and POSTs it to /chunks/complete.distribution/hosted-compute
25
Node State MachineExpands the node box of the hosted compute flow: the NodeCore lifecycle through Setup, Verifying, Registering, Running, NotFound, and Unavailable.distribution/hosted-compute
26
Chunk Claim LifecycleExpands the claim box of the hosted compute flow: a chunk is claimed from the in-memory runtime, completed with one of four CompletionOutcomes (Accepted, Idempotent, Conflict, Stale), or swept by the reclaim cron back into the queue or to Failed.distribution/hosted-compute
27
Deployment TopologyExpands the Infra box of the system context: the six Fly apps in region lhr, Supabase, the Cloudflare edge, Latitude.sh burst nodes joined over the headscale mesh, and alloy shipping metrics to Grafana Cloud.distribution/deployment
Portal
28
Portal Island Provider TreeThe nesting order of the studio provider islands: the locale layout mounts theme, redux, query, and auth-events islands; the authenticated shell adds the search, WASM, and node islands around the app shell.portal/architecture
29
Browser Simulation FlowExpands the Browser box of the system context for the user-facing path: SimC paste to parseSimc to buildSimConfig, then either a submitted job or a local worker WASM run, then decodeJobResult to charts.portal/simulation-ui