From 8aaf5c7976f64249e421ded9588729763a413fbe Mon Sep 17 00:00:00 2001
From: cinnaboot <cinnaboot@protonmail.com>
Date: Wed, 7 Jan 2026 18:00:50 -0500
Subject: [PATCH] Add Data Flow section, Main Program section, and enhance
 Technical Notes with details from verbose_project_overview.md: SOI
 hysteresis, physics steps per frame, code style, architecture layers

---
 docs/implementation_plan.md | 69 +++++++++++++++++++++++++++++++++++--
 1 file changed, 66 insertions(+), 3 deletions(-)

diff --git a/docs/implementation_plan.md b/docs/implementation_plan.md
index 348e961..5f699b1 100644
--- a/docs/implementation_plan.md
+++ b/docs/implementation_plan.md
@@ -83,11 +83,28 @@ struct AccelerationContext {
 Vector math and gravity calculations. RK4 (Runge-Kutta 4th order) integration with `rk4_step()`.
 
 ### Bodies (bodies.cpp/h)
-Simulation state management and updates. SOI detection using Hill sphere: `r_soi = a * (m/M)^(2/5)`
+Simulation state management and updates. SOI detection using Hill sphere: `r_soi = a * (m/M)^(2/5)`.
+
+**Key functions:**
+- `find_dominant_body()` - determines which body has gravitational dominance
+- `update_soi()` - calculates sphere of influence radius using Hill sphere
+- `update_simulation()` - runs one physics step: finds dominant parent, calculates gravity, applies RK4 integration
+- Dynamic parent switching when bodies cross SOI boundaries (with hysteresis)
 
 ### Config Loader (config_loader.cpp/h)
 TOML-based config parser using tomlc17 library. Auto-calculates circular orbit velocities and SOI radii.
 
+**Key functions:**
+- `parse_toml_body()` - parses individual body entries
+- `calculate_initial_velocities()` - sets circular orbit velocities using vis-viva equation
+- `calculate_soi_radii()` - computes sphere of influence for all bodies
+
+**Config format details:**
+- TOML array of tables: `[[bodies]]`
+- Comments start with `#`
+- `parent_index = -1` indicates root bodies (stars)
+- Supports binary/multiple star systems with barycentric orbit calculation
+
 **Config format (TOML):**
 ```toml
 [[bodies]]
@@ -114,6 +131,42 @@ semi_major_axis = 1.496e11
 ### Renderer (renderer.cpp/h)
 Raylib 3D visualization with logarithmic distance scaling and size scaling for visibility.
 
+### Main Program (main.cpp)
+GUI-only application with interactive 3D visualization.
+- Initializes simulation with MAX_BODIES=100, TIME_STEP=60 seconds
+- Runs 100 physics steps per frame (adjustable with speed multiplier)
+- Game loop: input handling → camera update → physics update (if not paused) → rendering
+- Supports speed multiplier (2x/0.5x per keypress, min 0.125x)
+
+**Controls:**
+- Arrow keys: Rotate and zoom camera
+- Space: Pause/Resume
+- +/-: Speed up/slow down simulation
+- I: Toggle info display
+- ESC: Quit
+
+## Data Flow
+
+### Initialization Sequence
+1. Configuration file → `load_system_config()` → populates `SimulationState`
+2. `calculate_initial_velocities()` → sets circular orbit velocities for all bodies
+3. `calculate_soi_radii()` → computes sphere of influence for each body
+
+### Main Simulation Loop
+1. `update_simulation()` → for each body:
+   - `find_dominant_body()` → determine gravitational parent based on SOI
+   - `evaluate_acceleration()` → compute gravitational force from parent
+   - `rk4_step()` → update position/velocity using Runge-Kutta 4th order
+2. `render_simulation()` → for each body:
+   - `scale_position()` → convert to render coordinates using logarithmic scaling
+   - `scale_radius()` → convert to render size using exponential scaling
+   - `render_body()` → draw sphere with color
+
+### SOI Transition Mechanics
+- Bodies dynamically switch gravitational parents when crossing SOI boundaries
+- Uses 0.5x distance hysteresis to prevent oscillation between parents
+- `find_dominant_body()` checks all bodies and selects most dominant influence
+
 ## Implementation Status
 
 ### ✅ Completed
@@ -134,15 +187,25 @@ Raylib 3D visualization with logarithmic distance scaling and size scaling for v
 
 ## Technical Notes
 
+### Code Style and Architecture
+- C-style C++: structs and functions only, no classes or templates
+- All headers use include guards
+- Memory management uses malloc/free
+- Layer separation: Physics, Simulation, Configuration, Rendering layers
+
 ### Scaling for Visualization
 - Distance: logarithmic/power-law scaling for solar system scale
 - Size: minimum visible radius to prevent tiny bodies from disappearing
 - Origin at Sun for simplicity
+- Both distance_scale and size_scale are configurable in RenderState
 
 ### Physics Considerations
-- Timestep: ~60 seconds for solar system scale
+- Timestep: 60 seconds for solar system scale
 - Circular orbit velocity: `v = sqrt(G * M / r)`
-- May need multiple physics sub-steps per render frame
+- Physics steps per frame: 100 (default) with speed multiplier adjustment
+- Simulation time per frame: 60s * 100 = 6000 seconds at 1x speed
+- SOI (Sphere of Influence) uses Hill sphere approximation: `r_soi = a * (m/M)^(2/5)`
+- SOI transitions use 0.5x distance hysteresis to prevent oscillation
 
 ## Future Enhancements
 - More accurate integration methods (Newton-Raphson propagation)