Web Application — Container
This C3 Component view opens the Web Application container and shows the browser-owned session, pre-flight, world initialization, flight, recovery, and outcome paths.
loading...
Components
| Component | Responsibility |
|---|---|
| Nginx static server | Receives HTTP from Kubernetes Ingress and serves the Vite SPA, SPA fallback, and health endpoint |
| Keycloak session client | Runs OIDC/OAuth 2.0 Authorization Code with PKCE, refreshes tokens, protects application routes, and restores the intended route |
| Pre-flight and launch configurator | Consumes bundled governed aircraft, world, and condition catalogues; selects controls and camera; binds every snapshot to the application revision; validates and summarizes the complete launch configuration |
| Flight deck and world bootstrap | Owns flight-attempt identity, launch, pause, resume, end, retry, and restart; initializes the selected world, terrain asset, physics profile, environment snapshot, and failure boundary before the render loop starts |
| Input and runtime-binding controller | Maps keyboard, mouse, and gamepad input into bounded typed control state and rejects controls that are not part of the active binding contract |
| Authoritative deterministic flight runtime | Advances Rapier dynamics at a fixed 60 Hz step, applies class-specific production physics, wind, collisions, world-boundary policy, and recovery decisions, and emits the authoritative flight frame |
| R3F world and aircraft compositor | Loads governed aircraft and terrain assets, applies the world-space contract, composes airfield or water infrastructure, maintains production camera rigs, and renders the selected world |
| Flight-state and recovery presenter | Projects authoritative frames into instruments, telemetry, environment state, control response, boundary warnings, and recovery guidance without becoming a second physics authority |
| Attempt and outcome coordinator | Preserves the active attempt through completion, failure, and abort; applies governed retry semantics; and creates a new provenance-linked attempt for deliberate restart |
| Pilot data API client | Loads pilot profile, preferences, progress, and outcomes over HTTPS/JSON |
| Persistence API client | Persists the selected preferences together with progress and outcomes over HTTPS/JSON |
Pre-flight flow
- The Keycloak session client establishes the pilot identity.
- The API client loads profile and preferences; the configurator reads the revision-bound governed catalogues compiled into the Web Application.
- The pilot selects aircraft, world, conditions, controls, and camera.
- The configurator binds each selected snapshot to the active source revision, validates the complete selection, and presents one review summary.
- The flight deck creates an attempt identity and reserves world initialization for the exact world, terrain, physics, catalogue, and source-revision tuple.
Flight flow
- World bootstrap loads and validates the governed terrain asset and physics profile before exposing a ready session world.
- The input controller publishes bounded typed control state from the active runtime-binding contract.
- The authoritative runtime advances aircraft forces, wind, collision, and recovery state at a fixed 60 Hz step.
- The R3F compositor aligns governed terrain and aircraft assets to the world-space contract, updates production cameras, and renders the authoritative pose.
- The presenter projects the authoritative frame into instruments, warnings, environment state, and recovery guidance.
- The outcome coordinator preserves the attempt identity through completion, failure, and abort; applies the governed retry contract; and creates a new provenance-linked attempt for deliberate restart.
- The outcome coordinator supplies progress and the final outcome to the Persistence API client. The browser-local flight path does not depend on Socket.IO.
Inactive socket scaffold
The repository contains a typed Socket.IO client library, and Kubernetes routes /socket.io to the API. The Release 1 application composition does not connect that library into the flight path, while the API has no production flight-command forwarder. Architecture therefore does not model it as an active Web Application component or required runtime relationship.
Fail-closed boundaries
| Boundary | Failure behavior |
|---|---|
| Launch configuration | Reject missing, disabled, stale-revision, or mismatched aircraft, world, control, camera, terrain, physics, and catalogue references before flight |
| World initialization | Cancel replaced initialization, dispose partially created resources, and render a stable world diagnostic instead of a partial scene |
| Asset and world-space composition | Reject invalid manifests, empty geometry, attribution or role mismatches, unavailable camera anchors, and terrain/collision misalignment |
| Physics and frame lifecycle | Keep one authoritative fixed-step state; convert world, camera, asset, and frame errors into typed diagnostics rather than continuing with divergent state |
| Completion persistence | Keep the terminal attempt state, report persistence failure, and withhold the saved debrief and progress checkpoint until the write succeeds |
Canonical realization links
These links make the C3 implementation boundary reciprocal with the governed product records. Status remains visible in each reader; implementation evidence does not approve a Proposed Feature or requirement.
| Concern | Feature | Requirement | Canonical Tasks |
|---|---|---|---|
| React/Vite browser foundation | AEROSIM-FT-41 | FR-0048 | TASK-0011, TASK-0012, TASK-0013 |
| Three.js and React Three Fiber rendering | AEROSIM-FT-45 | FR-0052 | TASK-0025, TASK-0026, TASK-0027, TASK-0139 |
| Rapier fixed-step flight physics | AEROSIM-FT-46 | FR-0053 | TASK-0028, TASK-0029, TASK-0030 |
Implementation anchors
| Component | Principal implementation paths |
|---|---|
| Pre-flight and launch configurator | applications/web/src/preflight/, applications/web/src/session/launch/ |
| Flight deck and world bootstrap | applications/web/src/App.tsx, applications/web/src/flight/FlightCanvas.tsx, applications/web/src/flight/world/initialize-session-world.ts |
| Authoritative deterministic flight runtime | applications/web/src/flight/authoritative-flight-state.ts, applications/web/src/flight/physics/ |
| R3F world and aircraft compositor | applications/web/src/flight/SceneRoot.tsx, applications/web/src/flight/world/, applications/web/src/flight/assets/, applications/web/src/flight/cameras/ |
| Flight-state and recovery presenter | applications/web/src/flight/presentation/, applications/web/src/flight/instruments/, applications/web/src/flight/warnings/, applications/web/src/flight/recovery/ |
| Attempt and outcome coordinator | applications/web/src/flight/session/, applications/web/src/flight/outcome/ |
Deployment boundary
Public HTTPS terminates on Osgiliath. Osgiliath forwards HTTP to Kubernetes Ingress, which routes / over HTTP to this container's Nginx Service. Public URLs and browser-observed API protocols remain HTTPS/WSS; the internal proxy hop does not require an aerosim-tls Secret.