# ullasds007-hub/lunar-window-planner architecture

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

- Interactive diagram: https://gitdiagram.com/ullasds007-hub/lunar-window-planner
- Repository: https://github.com/ullasds007-hub/lunar-window-planner

## Overview

Lunar Window Planner combines Earth-based observing windows with lunar-surface visibility planning. Users enter observing goals and dates for Earth windows, or lunar coordinates and a time range for surface intervals; the surface planner can compare scenarios and export intervals. The Earth API also exposes phase, rise/set, positions, twilight, and daily-report calculations. The graph separates the two planning domains, their HTTP interfaces and calculation layers, and the validation modules. Main application mounting and several UI-to-server links were not shown, so those connections are omitted.

Main entry points: [`validation/validationEngine.js`](https://github.com/ullasds007-hub/lunar-window-planner/blob/main/validation/validationEngine.js) (Validation runner), [`api.py`](https://github.com/ullasds007-hub/lunar-window-planner/blob/main/api.py) (Earth API), [`app/routers/lunar.py`](https://github.com/ullasds007-hub/lunar-window-planner/blob/main/app/routers/lunar.py) (Surface routes), [`app/static/compare.js`](https://github.com/ullasds007-hub/lunar-window-planner/blob/main/app/static/compare.js) (Scenario comparison)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_earth["Earth Observation"]
  node_earth_api["Earth API<br/>[api.py]"]
  node_earth_model["Earth calculations"]
end

subgraph group_surface["Lunar Surface"]
  node_surface_routes["Surface routes<br/>[lunar.py]"]
  node_surface_model["Surface calculations<br/>[lunar.py]"]
  node_surface_compare["Scenario comparison<br/>[compare.js]"]
end

subgraph group_validation["Validation"]
  node_validation_engine["Validation runner"]
  node_input_validator["Input checks<br/>[inputValidator.js]"]
  node_moon_validator["Moon data checks<br/>[moonValidator.js]"]
  node_calculation_validator["Calculation checks"]
  node_window_validator["Window checks<br/>[windowValidator.js]"]
end

node_observer(("Planner user"))

node_observer -->|"requests windows"| node_earth_api
node_earth_api -->|"uses astronomy model"| node_earth_model
node_observer -->|"enters scenarios"| node_surface_compare
node_surface_compare -->|"fetches windows"| node_surface_routes
node_surface_routes -->|"calculates windows"| node_surface_model
node_validation_engine -->|"validates inputs"| node_input_validator
node_validation_engine -->|"validates moon data"| node_moon_validator
node_validation_engine -->|"validates calculations"| node_calculation_validator
node_validation_engine -->|"validates windows"| node_window_validator

click node_earth_api "https://github.com/ullasds007-hub/lunar-window-planner/blob/main/api.py"
click node_earth_model "https://github.com/ullasds007-hub/lunar-window-planner/blob/main/moon_observation.py"
click node_surface_routes "https://github.com/ullasds007-hub/lunar-window-planner/blob/main/app/routers/lunar.py"
click node_surface_model "https://github.com/ullasds007-hub/lunar-window-planner/blob/main/app/services/lunar.py"
click node_surface_compare "https://github.com/ullasds007-hub/lunar-window-planner/blob/main/app/static/compare.js"
click node_validation_engine "https://github.com/ullasds007-hub/lunar-window-planner/blob/main/validation/validationEngine.js"
click node_input_validator "https://github.com/ullasds007-hub/lunar-window-planner/blob/main/validation/validators/inputValidator.js"
click node_moon_validator "https://github.com/ullasds007-hub/lunar-window-planner/blob/main/validation/validators/moonValidator.js"
click node_calculation_validator "https://github.com/ullasds007-hub/lunar-window-planner/blob/main/validation/validators/calculationValidator.js"
click node_window_validator "https://github.com/ullasds007-hub/lunar-window-planner/blob/main/validation/validators/windowValidator.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_earth_api,node_earth_model,node_observer toneBlue
class node_surface_routes,node_surface_model,node_surface_compare toneAmber
class node_validation_engine,node_input_validator,node_moon_validator,node_calculation_validator,node_window_validator toneMint
```

## Components

### Earth Observation

- [Earth API](https://github.com/ullasds007-hub/lunar-window-planner/blob/main/api.py): `api.py`
- [Earth calculations](https://github.com/ullasds007-hub/lunar-window-planner/blob/main/moon_observation.py): `moon_observation.py`

### Lunar Surface

- [Surface routes](https://github.com/ullasds007-hub/lunar-window-planner/blob/main/app/routers/lunar.py): `app/routers/lunar.py`
- [Surface calculations](https://github.com/ullasds007-hub/lunar-window-planner/blob/main/app/services/lunar.py): `app/services/lunar.py`
- [Scenario comparison](https://github.com/ullasds007-hub/lunar-window-planner/blob/main/app/static/compare.js): `app/static/compare.js`

### Validation

- [Validation runner](https://github.com/ullasds007-hub/lunar-window-planner/blob/main/validation/validationEngine.js): `validation/validationEngine.js`
- [Input checks](https://github.com/ullasds007-hub/lunar-window-planner/blob/main/validation/validators/inputValidator.js): `validation/validators/inputValidator.js`
- [Moon data checks](https://github.com/ullasds007-hub/lunar-window-planner/blob/main/validation/validators/moonValidator.js): `validation/validators/moonValidator.js`
- [Calculation checks](https://github.com/ullasds007-hub/lunar-window-planner/blob/main/validation/validators/calculationValidator.js): `validation/validators/calculationValidator.js`
- [Window checks](https://github.com/ullasds007-hub/lunar-window-planner/blob/main/validation/validators/windowValidator.js): `validation/validators/windowValidator.js`

### Other components

- **Planner user**

## Connections

- Planner user → Earth API: requests windows (evidence: `README.md`)
- Earth API → Earth calculations: uses astronomy model (evidence: `api.py`)
- Planner user → Scenario comparison: enters scenarios (evidence: `README.md`)
- Scenario comparison → Surface routes: fetches windows (evidence: `app/static/compare.js`)
- Surface routes → Surface calculations: calculates windows (evidence: `app/routers/lunar.py`)
- Validation runner → Input checks: validates inputs (evidence: `validation/validationEngine.js`)
- Validation runner → Moon data checks: validates moon data (evidence: `validation/validationEngine.js`)
- Validation runner → Calculation checks: validates calculations (evidence: `validation/validationEngine.js`)
- Validation runner → Window checks: validates windows (evidence: `validation/validationEngine.js`)