Apogee uses a monorepo with uv workspaces for modular organization.

Directory Structure¶

apogee/
├── packages/                       # Python packages (uv workspace)
│   ├── apogee-physics/            # Pure physics engine (JAX/Diffrax)
│   │   └── src/apogee_physics/
│   │       ├── atmosphere.py      # USSA76 atmosphere model
│   │       ├── dynamics.py        # ODE right-hand side functions
│   │       ├── simulate.py        # Hybrid simulation with events
│   │       ├── orbit.py           # Two-body orbital diagnostics
│   │       ├── shooting.py        # Shooting method solver
│   │       ├── trajectory.py      # Trajectory data structure
│   │       └── types.py           # Type definitions
│   │
│   ├── apogee-launch/             # Launch simulator + CLI
│   │   └── src/apogee_launch/
│   │       ├── simulator.py       # Public API
│   │       ├── falcon9.py         # Falcon 9 v1.2 FT parameters
│   │       ├── plotting.py        # Visualization
│   │       └── cli.py             # Command-line interface
│   │
│   ├── apogee-orbit/              # Orbital mechanics & yaw steering
│   │   └── src/apogee_orbit/
│   │       ├── core.py            # EquatorialOrbit class
│   │       ├── attitude.py        # Yaw steering algorithm
│   │       ├── simulator.py       # Orbit simulation API
│   │       └── cli.py             # Command-line interface
│   │
│   └── apogee-api/                # FastAPI REST API
│       └── src/apogee_api/
│           ├── main.py            # FastAPI application
│           ├── routers/           # API endpoints
│           └── schemas/           # Pydantic models
│
├── frontend/                       # React Three Fiber 3D visualization
│   └── src/
│       ├── features/              # Feature modules
│       │   ├── beach/             # Launch site scene
│       │   ├── launch/            # Trajectory animation
│       │   └── navigation/        # Intro scenes
│       ├── services/              # API client
│       ├── stores/                # Zustand state
│       └── utils/                 # Coordinate transforms
│
├── docs/                          # This documentation
├── pyproject.toml                 # Workspace root configuration
└── README.md

Dependency Flow¶

graph TD
    A[Frontend<br/>React + Three.js] --> B[apogee-api<br/>FastAPI]
    B --> C[apogee-launch]
    B --> D[apogee-orbit]
    C --> E[apogee-physics<br/>JAX/Diffrax]
    D --> C

Design principle: Each layer consumes the layer below. No logic duplication.

Package Details¶

apogee-physics¶

The core numerical engine. Pure physics with no CLI or API dependencies.

Dependencies:

dependencies = [
    "jax",
    "diffrax",
    "ussa1976",
]

Key modules:

apogee-launch¶

User-facing simulator with Falcon 9 vehicle model.

Dependencies:

dependencies = [
    "apogee-physics",
    "typer>=0.15.0",
    "matplotlib",
]

CLI Entry Point:

uv run apogee-launch --h-target-km 200 --payload-kg 5000

apogee-orbit¶

Orbital propagation and attitude control.

Dependencies:

dependencies = [
    "numpy",
    "typer",
    "matplotlib",
    "apogee-launch",
]

Key features:

• Circular equatorial orbit propagation
• LVLH coordinate frame
• Yaw steering for solar panels

apogee-api¶

REST API for frontend integration.

Dependencies:

dependencies = [
    "fastapi",
    "uvicorn[standard]",
    "pydantic",
    "apogee-launch",
    "apogee-orbit",
]

Endpoints:

Technology Stack¶

Backend (Python)¶

Frontend (TypeScript)¶

Code-to-Equation Mapping¶

Every equation in the documentation maps to specific code:

See Packages for detailed module documentation.