BioSim Next-Gen Architecture

This document describes the technical architecture and subsystems of the BioSim Next-Gen interactive biological life support simulator.

🏗️ System Architecture

The simulation is designed entirely as a client-side web application, utilizing standard web technologies to achieve high-fidelity rendering, telemetry visualization, and interaction.

+--------------------------------------------------------------+
|                         Web Browser                          |
+--------------------------------------------------------------+
                               |
        +----------------------+----------------------+
        |                      |                      |
        v                      v                      v
+---------------+      +---------------+      +---------------+
|   Three.js    |      | Crew AI Engine|      |  ECLSS Engine |
| 3D Render Loop|      | (Possession)  |      |   Telemetry   |
+---------------+      +---------------+      +---------------+

🛰️ ECLSS Subsystems

The Environmental Control and Life Support System (ECLSS) models several interconnected loops:

1. Atmosphere Loop

Oxygen (O₂): Consumed by the crew; regenerated via algae photobioreactors and aeroponic plant systems.
Carbon Dioxide (CO₂): Produced by the crew; scrubbed by mechanical and chemical filters.
Pressure: Models cabin structural seals and emergency pressure venting.

2. Water & Nutrition Loop

Water Recycling: Condensation collection and wastewater distillation systems.
Aeroponic System: Grow chambers providing fresh biomass (food) and air filtering.

3. Crew Physiology

Stress Levels: Influenced by space confinement, high CO₂ levels, malfunction alerts, and crew communications.
Metabolic Rate: Dynamic based on crew archetype and physical activity levels.

👾 Crew Archetypes & Possession

The simulation features an interactive crew selection overlay at launch. Users can set the crew size and select an archetype configuration:

Commander: High resilience, manages operational efficiency.
Bio-Engineer: Maximizes ECLSS efficiency, handles malfunctions quickly.
Science Officer: Enhances plant growth rates and atmospheric regeneration.

Possession Mode

By entering first-person mode, the user possesses a crew member’s viewpoint inside the 3D grid layout, allowing direct interaction with specific room consoles.

⚠️ Malfunction Injector

To test system resilience, the malfunction injector inserts simulated hazards:

ECLSS Valve Leak: Rapid pressure drop and oxygen loss.
Solar Flare Surge: High power draw and emergency cooling shutoff.
Algae PBR Contamination: Reduced oxygen regeneration and rising CO₂.

🛠️ Technical Stack & Modules

The client-side simulation is composed of several modular scripts that coordinate rendering, audio, and physical modeling:

Module / Script	File Path	Subsystem Role	Key APIs & Libraries
3D Rendering	`js/three_habitat.js`	Draws the pressure vessel, ribs, solar panels, and astronaut meshes.	Three.js (WebGL), OrbitControls, ACESFilmicToneMapping
Simulation Engine	`js/blss_engine.js`	Models atmospheric loops, algae PBR, and metabolic decay math.	Custom state-machine, Delta-time loop
Audio Synthesizer	`js/audio_engine.js`	Generates keyboard clicks, background engine hums, and malfunction sirens.	Web Audio API (Oscillators, GainNodes, BiquadFilters)
Possession / FPS	`js/fps_controller.js`	Locks camera into astronaut perspective and handles WASD keys.	Pointer Lock API, KeyboardEvents
Crew Mind Engine	`js/agent_mind.js`	Simulates crew conversations and latency CAPCOM responses.	Fictional prompt simulator, queue system
Application Coordinator	`js/app.js`	Binds user click handlers, time speed dials, overlay states, and themes.	EventListeners, DOM API