Imported from ahenkes1/planetarium (AGENTS.md). Install upstream with npx skills add ahenkes1/planetarium. Copyright stays with the author.

AI Agents and Architectural Roles

This document defines the roles and responsibilities within the Terminal-Based Planetary Simulation. While this project is a single executable, we adopt an "Actor Model" mindset for concurrency, where distinct components (Agents) handle specific domains.

1. The Coordinator (Main Thread)

Role: Orchestrator

• Responsibilities:
  • Initializes the application state.
  • Runs the main event loop (tokio::select!).
  • Dispatches events (Input, Resize, Tick) to the appropriate systems.
  • Manages the lifecycle of the application (startup, shutdown, error recovery).
  • Tracks real-world delta time to keep the simulation clock aligned with true UTC and surfaces state (paused/live, time-scale multiplier) to the Renderer for HUD display.
  • Handles the L “Jump to Live” shortcut by snapping the simulation clock back to real-world time and requesting an immediate Horizons refresh so splines are reseeded.

2. The Ephemeris Provider (Fetcher Agent)

Role: Data Acquisition & Persistence

• Responsibilities:
  • Fetch: Asynchronously retrieves vector data from JPL Horizons API via HTTP.
  • Cache: Manages local disk cache to prevent redundant network requests.
  • Parse: Converts raw text responses into structured CartesianState objects.
  • Mock: Provides static sample data when offline or for testing.
• Communication: Receives FetchRequest(BodyId, TimeRange) -> Returns Result<Vec<CartesianState>> via channels.

3. The Physicist (Math Engine)

Role: Simulation & Interpolation

• Responsibilities:
  • Interpolate: Uses cubic Hermite splines seeded with the Horizons position and velocity vectors so the hand-off into physics preserves the exact state.
  • Propagate (Fallback): Runs an N-Body Physics simulation (Velocity Verlet/RK4) when real data is unavailable or for future extrapolation.
  • Time Management: Converts between UTC DateTime and simulation ticks.
  • Immediate Seeding: When ephemeris data arrives, body positions are seeded immediately from the spline so planets appear without waiting for the next update tick.
  • Time Clamping: The simulation clock is clamped to the intersection of all loaded spline windows, ensuring path.sample() always succeeds once data is available.

4. The Cinematographer (Camera & Projection)

Role: View Transformation

• Responsibilities:
  • Transform: Converts World Coordinates (ICRF) to Camera Coordinates.
  • Project: Applies perspective projection to map 3D space to 2D screen space.
  • Correct: Applies Aspect Ratio correction (scaling X by ~0.5 or Y by ~2.0) to ensure circular orbits look circular on rectangular terminal cells.
  • Orbit Focus: Supports cycling through planet orbits (O key) with automatic zoom to fit the selected orbit in view, and centering on the Sun (C key).

5. The Renderer (TUI Agent)

Role: Visualization

• Responsibilities:
  • Draw: Uses Ratatui to render the state into the terminal buffer.
  • Canvas: Manages the high-resolution Braille marker canvas.
  • UI Elements: Renders overlays (HUD, Debug Info, Loading Spinners).
    • Shows the simulation status HUD (Paused/Live + multiplier) and keybinding hints whenever the Coordinator reports state changes (recent commits added the Space/F/S/H indicators and help overlay toggle).
    • Displays a help overlay (H shortcut) describing controls, keeping it in sync with the latest keymap.
  • Optimization: Uses double-buffering to minimize flicker and bandwidth.

Licensing

Planetarium is distributed under the GNU Affero General Public License v3. When operating or extending any agent (especially ones exposed over a network such as the Renderer via remote terminals), ensure you comply with AGPL obligations: publish your modifications, include prominent notices about changes, and provide users a way to obtain the corresponding source of the running version. See LICENSE for the full terms.