Repository map
The project is intentionally plain C. Simulation, app state, and raylib rendering live in separate directories so each new planet or moon can be reviewed as a physics milestone.
01 / Small-body atlas and source epoch
docs/public/catalog/ + data/planet_epoch.jsonPinned shard/index/density inventory, physical-data supplements in data/, and planetary vectors for bounded selected-body experiments. Provenance lives in data/README.md and data/SMALL_BODIES.md.
Offline tools/small_body_catalog.py --check and tools/planet_epoch.py --check; conic/experiment C tests and catalog-worker tests.
02 / Jovian satellite catalog
data/jovian_moons.jsonVersioned source elements, stable JPL codes, physical-data quality and references for all 115 Jupiter moons; shared with C and Astro.
Offline tools/jovian_catalog.py --check, C satellite/geometry tests, and full-scene convergence.
03 / Project spec
SPEC.mdCurrent goals, constraints, interfaces, invariants, tasks, and bug history.
Review before an implementation task; check drift after verification.
04 / Simulation core
src/sim/raylib-independent SI bodies, Newtonian forces, Verlet/Euler stepping, diagnostics, lessons, opt-in head-on contact, conic propagation, and scene factories.
make test-core covers initial states, orbital references, convergence, conservation, collisions, and source-catalog contracts without raylib.
05 / Application helpers
src/app/C-owned sessions, fixed-step playback, physical inspection, camera, synchronized bounded trails, shared SI CSV writer, versioned lesson descriptors, and matched A/B comparison checkpoints.
C tests exercise reset/step, inspection, camera framing, 100-day accuracy, trail retention, descriptor validation, and comparison timing/identity.
06 / Rendering boundary
src/render/raylib conversion from SI-unit simulation state into readable 3D drawing policies.
Renderer helper tests guard scale conversion, visual radius policy, family framing, and grid sizing.
07 / Runtime loop
src/main.cnative window loop, Emscripten callback loop, input handling, simulation stepping, and draw orchestration.
Native and WebAssembly builds compile both loop targets; artifact checks validate generated files.
08 / Headless and comparison entrypoints
src/headless.c + src/lab_web.cThe raylib-free solar-lab CLI and the C-only comparison WASM module share sessions, descriptors, measurements, and CSV export. examples/ holds replayable .solar inputs.
make test-cli; tools/test_learning_wasm.mjs compares matching native/WASM experiments.
09 / Test binaries
tests/Focused C binaries plus Python CLI, build-graph, catalog-import, and artifact-validation tests; no desktop window is required.
make test test-build test-cli test-validators; make test-sanitize for address/undefined-behavior checks.
10 / Public site
docs/Astro Pages site, documentation routes, public lab shell, and source-backed explanatory content.
npm test --prefix docs, npm run check --prefix docs, npm run build --prefix docs, and make docs-check; docs/browser-tests/ covers browser interaction.
11 / Catalog and delivery tools
tools/Explicit source refresh/import, offline audits, C/WASM parity checks, runtime artifact provenance/staging, generated-route validation, and the loopback site server.
make test-build test-validators, offline catalog checks, WASM checks, and make docs-check.
12 / Browser runtime
docs/src/pages/simulator.astroShared Astro layout, controls, and canvas; simulator.ts sends commands to C and presents live physical readouts and errors.
Runtime integration tests, generated route checks, and headless browser verification.
13 / Automation
.github/workflows/Read-only Build gates produce a checked Pages tree; trusted workflow-run deployment publishes that exact artifact. CodeQL separately analyzes C/C++, JavaScript/TypeScript, and Actions.
Inspect Build/CodeQL for the revision and, on eligible main delivery, Deploy Pages plus the public runtime manifest.