# dev-armaan/satellites architecture

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

- Interactive diagram: https://gitdiagram.com/dev-armaan/satellites
- Repository: https://github.com/dev-armaan/satellites

## Overview

Watched is a browser-based satellite-overflight and imagery explorer. A user chooses or locates a place; the app computes a week of satellite passes, searches public imagery archives and matches captures to passes, then presents verdicts, photos, and a timeline. Users can replay a pass and share it with a generated preview card. The globe visualizes satellites and pass geometry alongside the results. The README documents these product stages; sampled controller, state, imagery, and UI excerpts support the main runtime links. Some subsystems are represented at directory level because their implementation was not sampled.

Main entry points: [`src/app/controller.ts`](https://github.com/dev-armaan/satellites/blob/main/src/app/controller.ts) (Flow controller), [`src/imagery`](https://github.com/dev-armaan/satellites/tree/main/src/imagery) (Imagery archives), [`src/ui/results/ResultsView.tsx`](https://github.com/dev-armaan/satellites/blob/main/src/ui/results/ResultsView.tsx) (Results panel), [`src/state/store.ts`](https://github.com/dev-armaan/satellites/blob/main/src/state/store.ts) (App state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App workflow"]
  node_landing["Place search<br/>[SearchBox.tsx]"]
  node_controller["Flow controller<br/>[controller.ts]"]
  node_state["App state<br/>[store.ts]"]
end

subgraph group_analysis["Orbit and imagery analysis"]
  node_catalog["Satellite catalog<br/>[catalog.ts]"]
  node_orbit["Pass computation"]
  node_profiles["Satellite profiles<br/>[profiles.ts]"]
  node_report["Pass report<br/>[report.ts]"]
  node_archives["Imagery archives"]
  node_cloud["Cloud checks<br/>[cloud.ts]"]
  node_pixels["Pixel processing<br/>[pixels.ts]"]
end

subgraph group_experience["Globe and results"]
  node_globe["3D globe"]
  node_results["Results panel<br/>[ResultsView.tsx]"]
  node_timeline["Pass timeline<br/>[Timeline.tsx]"]
  node_replay["Pass replay"]
end

subgraph group_sharing["Sharing"]
  node_shareui["Share sheet<br/>[ShareSheet.tsx]"]
  node_card["Share card spec<br/>[cardSpec.ts]"]
  node_og["Preview endpoint<br/>[og.tsx]"]
end

node_visitor(("Place seeker"))
node_external[("Public archives")]

node_visitor -->|"chooses place"| node_landing
node_landing -->|"submits place"| node_controller
node_controller -->|"loads catalog"| node_catalog
node_controller -->|"runs report"| node_orbit
node_controller -->|"searches captures"| node_archives
node_controller -->|"updates state"| node_state
node_catalog -->|"resolves satellites"| node_profiles
node_orbit -.->|"computes passes"| node_report
node_report -->|"matches photos"| node_archives
node_archives -->|"queries archives"| node_external
node_archives -->|"checks cloud"| node_cloud
node_archives -->|"decodes imagery"| node_pixels
node_state -->|"supplies scene state"| node_globe
node_state -->|"supplies report state"| node_results
node_results -->|"renders timeline"| node_timeline
node_results -->|"offers replay"| node_replay
node_results -->|"opens sharing"| node_shareui
node_shareui -->|"renders card fields"| node_card
node_og -->|"uses card spec"| node_card

click node_landing "https://github.com/dev-armaan/satellites/blob/main/src/ui/landing/SearchBox.tsx"
click node_controller "https://github.com/dev-armaan/satellites/blob/main/src/app/controller.ts"
click node_state "https://github.com/dev-armaan/satellites/blob/main/src/state/store.ts"
click node_catalog "https://github.com/dev-armaan/satellites/blob/main/src/engine/catalog.ts"
click node_orbit "https://github.com/dev-armaan/satellites/tree/main/src/engine"
click node_profiles "https://github.com/dev-armaan/satellites/blob/main/src/engine/profiles.ts"
click node_report "https://github.com/dev-armaan/satellites/blob/main/src/engine/report.ts"
click node_archives "https://github.com/dev-armaan/satellites/tree/main/src/imagery"
click node_cloud "https://github.com/dev-armaan/satellites/blob/main/src/imagery/cloud.ts"
click node_pixels "https://github.com/dev-armaan/satellites/blob/main/src/imagery/pixels.ts"
click node_globe "https://github.com/dev-armaan/satellites/tree/main/src/globe"
click node_results "https://github.com/dev-armaan/satellites/blob/main/src/ui/results/ResultsView.tsx"
click node_timeline "https://github.com/dev-armaan/satellites/blob/main/src/ui/results/Timeline.tsx"
click node_replay "https://github.com/dev-armaan/satellites/blob/main/src/ui/results/PushbroomReveal.tsx"
click node_shareui "https://github.com/dev-armaan/satellites/blob/main/src/ui/share/ShareSheet.tsx"
click node_card "https://github.com/dev-armaan/satellites/blob/main/api/_lib/cardSpec.ts"
click node_og "https://github.com/dev-armaan/satellites/blob/main/api/og.tsx"

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_landing,node_controller,node_state toneBlue
class node_catalog,node_orbit,node_profiles,node_report,node_archives,node_cloud,node_pixels,node_external toneAmber
class node_globe,node_results,node_timeline,node_replay toneMint
class node_shareui,node_card,node_og toneRose
class node_visitor toneIndigo
```

## Components

### App workflow

- [Place search](https://github.com/dev-armaan/satellites/blob/main/src/ui/landing/SearchBox.tsx): `src/ui/landing/SearchBox.tsx`
- [Flow controller](https://github.com/dev-armaan/satellites/blob/main/src/app/controller.ts): `src/app/controller.ts`
- [App state](https://github.com/dev-armaan/satellites/blob/main/src/state/store.ts): `src/state/store.ts`

### Orbit and imagery analysis

- [Satellite catalog](https://github.com/dev-armaan/satellites/blob/main/src/engine/catalog.ts): `src/engine/catalog.ts`
- [Pass computation](https://github.com/dev-armaan/satellites/tree/main/src/engine): `src/engine`
- [Satellite profiles](https://github.com/dev-armaan/satellites/blob/main/src/engine/profiles.ts): `src/engine/profiles.ts`
- [Pass report](https://github.com/dev-armaan/satellites/blob/main/src/engine/report.ts): `src/engine/report.ts`
- [Imagery archives](https://github.com/dev-armaan/satellites/tree/main/src/imagery): `src/imagery`
- [Cloud checks](https://github.com/dev-armaan/satellites/blob/main/src/imagery/cloud.ts): `src/imagery/cloud.ts`
- [Pixel processing](https://github.com/dev-armaan/satellites/blob/main/src/imagery/pixels.ts): `src/imagery/pixels.ts`

### Globe and results

- [3D globe](https://github.com/dev-armaan/satellites/tree/main/src/globe): `src/globe`
- [Results panel](https://github.com/dev-armaan/satellites/blob/main/src/ui/results/ResultsView.tsx): `src/ui/results/ResultsView.tsx`
- [Pass timeline](https://github.com/dev-armaan/satellites/blob/main/src/ui/results/Timeline.tsx): `src/ui/results/Timeline.tsx`
- [Pass replay](https://github.com/dev-armaan/satellites/blob/main/src/ui/results/PushbroomReveal.tsx): `src/ui/results/PushbroomReveal.tsx`

### Sharing

- [Share sheet](https://github.com/dev-armaan/satellites/blob/main/src/ui/share/ShareSheet.tsx): `src/ui/share/ShareSheet.tsx`
- [Share card spec](https://github.com/dev-armaan/satellites/blob/main/api/_lib/cardSpec.ts): `api/_lib/cardSpec.ts`
- [Preview endpoint](https://github.com/dev-armaan/satellites/blob/main/api/og.tsx): `api/og.tsx`

### Other components

- **Place seeker**
- **Public archives**

## Connections

- Place seeker → Place search: chooses place (evidence: `README.md`)
- Place search → Flow controller: submits place
- Flow controller → Satellite catalog: loads catalog (evidence: `src/app/controller.ts`)
- Flow controller → Pass computation: runs report (evidence: `src/app/controller.ts`)
- Flow controller → Imagery archives: searches captures (evidence: `src/app/controller.ts`)
- Flow controller → App state: updates state (evidence: `src/app/controller.ts`)
- Satellite catalog → Satellite profiles: resolves satellites (evidence: `src/engine/catalog.ts`)
- Pass computation → Pass report: computes passes (evidence: `src/engine/index.ts`)
- Pass report → Imagery archives: matches photos (evidence: `README.md`)
- Imagery archives → Public archives: queries archives (evidence: `README.md`)
- Imagery archives → Cloud checks: checks cloud (evidence: `src/imagery/index.ts`)
- Imagery archives → Pixel processing: decodes imagery (evidence: `src/imagery/index.ts`)
- App state → 3D globe: supplies scene state (evidence: `src/state/store.ts`)
- App state → Results panel: supplies report state (evidence: `src/ui/results/ResultsView.tsx`)
- Results panel → Pass timeline: renders timeline (evidence: `src/ui/results/ResultsView.tsx`)
- Results panel → Pass replay: offers replay (evidence: `src/ui/results/index.ts`)
- Results panel → Share sheet: opens sharing (evidence: `src/ui/results/ResultsView.tsx`)
- Share sheet → Share card spec: renders card fields (evidence: `api/_lib/cardSpec.ts`)
- Preview endpoint → Share card spec: uses card spec (evidence: `api/og.tsx`)