# jackzyx/hackslop-lunar architecture

> Architecture diagram of the GitHub repository jackzyx/hackslop-lunar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jackzyx/hackslop-lunar
- Repository: https://github.com/jackzyx/hackslop-lunar

## Overview

Sun Shade is a browser-based lunar south-pole landing-site planner. Users choose a date, compare sites, and adjust a launch slip to see sunlight and Earth-contact metrics over LOLA terrain; the app also supports custom sites, terrain views, validation, and an animated introduction. Python science modules compute ephemerides and horizon masks for static runtime data, while browser code calculates metrics and renders terrain. Edges reflect shown calls or README statements; unsampled component wiring is omitted.

Main entry points: [`web/src/App.jsx`](https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/App.jsx) (Planner interface), [`web/src/main.jsx`](https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/main.jsx) (Browser bootstrap), [`web/src/terrain/shadow.js`](https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/terrain/shadow.js) (Terrain shadowing), [`web/src/terrain/terrain-3d.js`](https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/terrain/terrain-3d.js) (3D terrain view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application workflow"]
  node_bootstrap["Browser bootstrap<br/>[main.jsx]"]
  node_routes["Page routing<br/>[routes.js]"]
  node_planner["Planner interface<br/>[App.jsx]"]
  node_date["Date selection"]
  node_custom["Custom sites<br/>[custom-site.js]"]
  node_siteviews["Site details<br/>[DetailTabs.jsx]"]
  node_intro["Animated introduction<br/>[intro.js]"]
end

subgraph group_analysis["Site analysis"]
  node_bestdays["Best-day search<br/>[best-days.js]"]
  node_metrics["Visibility metrics<br/>[metrics.js]"]
end

subgraph group_render["Terrain and visuals"]
  node_terrainstartup["Terrain startup<br/>[startup.js]"]
  node_terrain["3D terrain view<br/>[terrain-3d.js]"]
  node_shadow["Terrain shadowing<br/>[shadow.js]"]
  node_shadowworker["Shadow worker<br/>[shadow.worker.js]"]
  node_mapview["Terrain map<br/>[ShadowMap.jsx]"]
  node_surface["Surface rendering"]
  node_introassets["Intro asset preparation<br/>[intro-assets.js]"]
end

subgraph group_science["Science and data"]
  node_data["Planner data loader<br/>[data.js]"]
  node_ephemeris["Lunar ephemeris<br/>[lunar_ephemeris.py]"]
  node_horizons["Horizon masks<br/>[horizon_mask.py]"]
  node_validation["Horizons validation"]
  node_staticdata["Shipped static data<br/>[data.js]"]
end

node_visitor(("Planner user"))
node_horizonsservice(("JPL Horizons"))

node_visitor -->|"opens app"| node_bootstrap
node_bootstrap -->|"resolves page"| node_routes
node_bootstrap -->|"loads and mounts"| node_planner
node_bootstrap -->|"loads data"| node_data
node_bootstrap -->|"loads terrain"| node_terrainstartup
node_bootstrap -->|"starts intro"| node_intro
node_planner -->|"loads planner data"| node_data
node_planner -->|"manages sites"| node_custom
node_planner -->|"imports metrics"| node_metrics
node_planner -.->|"renders picker"| node_date
node_planner -.->|"presents details"| node_siteviews
node_custom -->|"uses terrain"| node_shadow
node_terrainstartup -->|"uses shading"| node_shadow
node_terrain -->|"uses terrain math"| node_shadow
node_terrain -.->|"renders map"| node_mapview
node_terrain -.->|"renders surface"| node_surface
node_shadowworker -->|"renders shadows"| node_shadow
node_shadow -->|"uses Sun fraction"| node_metrics
node_intro -->|"prepares assets"| node_introassets
node_introassets -->|"shades terrain"| node_shadow
node_planner -.->|"offers best days"| node_bestdays
node_ephemeris -.->|"supplies ephemeris"| node_staticdata
node_horizons -.->|"supplies masks"| node_staticdata
node_validation -.->|"validates against"| node_horizonsservice
node_staticdata -->|"provides runtime data"| node_planner

click node_bootstrap "https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/main.jsx"
click node_routes "https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/lib/routes.js"
click node_planner "https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/App.jsx"
click node_date "https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/components/LandingDatePicker.jsx"
click node_custom "https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/domain/custom-site.js"
click node_siteviews "https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/components/DetailTabs.jsx"
click node_bestdays "https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/domain/best-days.js"
click node_metrics "https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/domain/metrics.js"
click node_data "https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/lib/data.js"
click node_terrainstartup "https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/terrain/startup.js"
click node_terrain "https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/terrain/terrain-3d.js"
click node_shadow "https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/terrain/shadow.js"
click node_shadowworker "https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/terrain/shadow.worker.js"
click node_mapview "https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/components/ShadowMap.jsx"
click node_surface "https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/terrain/surface-renderer.js"
click node_intro "https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/intro/intro.js"
click node_introassets "https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/intro/intro-assets.js"
click node_ephemeris "https://github.com/jackzyx/hackslop-lunar/blob/main/science/lunar_ephemeris.py"
click node_horizons "https://github.com/jackzyx/hackslop-lunar/blob/main/science/horizon_mask.py"
click node_validation "https://github.com/jackzyx/hackslop-lunar/blob/main/science/validate_horizons.py"
click node_staticdata "https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/lib/data.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bootstrap,node_routes,node_planner,node_date,node_custom,node_siteviews,node_intro,node_visitor toneBlue
class node_bestdays,node_metrics toneAmber
class node_terrainstartup,node_terrain,node_shadow,node_shadowworker,node_mapview,node_surface,node_introassets toneMint
class node_data,node_ephemeris,node_horizons,node_validation,node_staticdata toneRose
class node_horizonsservice toneIndigo
```

## Components

### Application workflow

- [Browser bootstrap](https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/main.jsx): `web/src/main.jsx`
- [Page routing](https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/lib/routes.js): `web/src/lib/routes.js`
- [Planner interface](https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/App.jsx): `web/src/App.jsx`
- [Date selection](https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/components/LandingDatePicker.jsx): `web/src/components/LandingDatePicker.jsx`
- [Custom sites](https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/domain/custom-site.js): `web/src/domain/custom-site.js`
- [Site details](https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/components/DetailTabs.jsx): `web/src/components/DetailTabs.jsx`
- [Animated introduction](https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/intro/intro.js): `web/src/intro/intro.js`

### Site analysis

- [Best-day search](https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/domain/best-days.js): `web/src/domain/best-days.js`
- [Visibility metrics](https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/domain/metrics.js): `web/src/domain/metrics.js`

### Terrain and visuals

- [Terrain startup](https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/terrain/startup.js): `web/src/terrain/startup.js`
- [3D terrain view](https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/terrain/terrain-3d.js): `web/src/terrain/terrain-3d.js`
- [Terrain shadowing](https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/terrain/shadow.js): `web/src/terrain/shadow.js`
- [Shadow worker](https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/terrain/shadow.worker.js): `web/src/terrain/shadow.worker.js`
- [Terrain map](https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/components/ShadowMap.jsx): `web/src/components/ShadowMap.jsx`
- [Surface rendering](https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/terrain/surface-renderer.js): `web/src/terrain/surface-renderer.js`
- [Intro asset preparation](https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/intro/intro-assets.js): `web/src/intro/intro-assets.js`

### Science and data

- [Planner data loader](https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/lib/data.js): `web/src/lib/data.js`
- [Lunar ephemeris](https://github.com/jackzyx/hackslop-lunar/blob/main/science/lunar_ephemeris.py): `science/lunar_ephemeris.py`
- [Horizon masks](https://github.com/jackzyx/hackslop-lunar/blob/main/science/horizon_mask.py): `science/horizon_mask.py`
- [Horizons validation](https://github.com/jackzyx/hackslop-lunar/blob/main/science/validate_horizons.py): `science/validate_horizons.py`
- [Shipped static data](https://github.com/jackzyx/hackslop-lunar/blob/main/web/src/lib/data.js): `web/src/lib/data.js`

### Other components

- **Planner user**
- **JPL Horizons**

## Connections

- Planner user → Browser bootstrap: opens app (evidence: `web/src/main.jsx`)
- Browser bootstrap → Page routing: resolves page (evidence: `web/src/main.jsx`)
- Browser bootstrap → Planner interface: loads and mounts (evidence: `web/src/main.jsx`)
- Browser bootstrap → Planner data loader: loads data (evidence: `web/src/main.jsx`)
- Browser bootstrap → Terrain startup: loads terrain (evidence: `web/src/main.jsx`)
- Browser bootstrap → Animated introduction: starts intro (evidence: `web/src/main.jsx`)
- Planner interface → Planner data loader: loads planner data (evidence: `web/src/App.jsx`)
- Planner interface → Custom sites: manages sites (evidence: `web/src/App.jsx`)
- Planner interface → Visibility metrics: imports metrics (evidence: `web/src/App.jsx`)
- Planner interface → Date selection: renders picker
- Planner interface → Site details: presents details
- Custom sites → Terrain shadowing: uses terrain (evidence: `web/src/domain/custom-site.js`)
- Terrain startup → Terrain shadowing: uses shading (evidence: `web/src/terrain/startup.js`)
- 3D terrain view → Terrain shadowing: uses terrain math (evidence: `web/src/terrain/terrain-3d.js`)
- 3D terrain view → Terrain map: renders map
- 3D terrain view → Surface rendering: renders surface
- Shadow worker → Terrain shadowing: renders shadows (evidence: `web/src/terrain/shadow.worker.js`)
- Terrain shadowing → Visibility metrics: uses Sun fraction (evidence: `web/src/terrain/shadow.js`)
- Animated introduction → Intro asset preparation: prepares assets (evidence: `web/src/intro/intro.js`)
- Intro asset preparation → Terrain shadowing: shades terrain (evidence: `web/src/intro/intro-assets.js`)
- Planner interface → Best-day search: offers best days
- Lunar ephemeris → Shipped static data: supplies ephemeris (evidence: `README.md`)
- Horizon masks → Shipped static data: supplies masks (evidence: `README.md`)
- Horizons validation → JPL Horizons: validates against (evidence: `README.md`)
- Shipped static data → Planner interface: provides runtime data (evidence: `README.md`)
