# abdullahmahfouz/neo-watch architecture

> Architecture diagram of the GitHub repository abdullahmahfouz/neo-watch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abdullahmahfouz/neo-watch
- Repository: https://github.com/abdullahmahfouz/neo-watch

## Overview

NeoWatch ingests NASA near-Earth-object data, estimates impact energy, stores approach and risk history, and serves a dashboard and per-asteroid history to a React 3D interface. The graph preserves the documented ingestion, read, and display stages. Some frontend component wiring and backend cache configuration were not sampled, so those internal connections are shown only where the README or sampled source supports them.

Main entry points: [`src/main/java/com/abdullah/neowatch/service/AsteroidService.java`](https://github.com/abdullahmahfouz/neo-watch/blob/main/src/main/java/com/abdullah/neowatch/service/AsteroidService.java) (Asteroid service), [`frontend/src/App.jsx`](https://github.com/abdullahmahfouz/neo-watch/blob/main/frontend/src/App.jsx) (Frontend app), [`frontend/src/pages/OrbitView.jsx`](https://github.com/abdullahmahfouz/neo-watch/blob/main/frontend/src/pages/OrbitView.jsx) (3D home view), [`src/main/java/com/abdullah/neowatch/config`](https://github.com/abdullahmahfouz/neo-watch/tree/main/src/main/java/com/abdullah/neowatch/config) (Request filters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data ingestion"]
  node_nasa_client["NASA feed client<br/>[NasaClient.java]"]
  node_ingest_controller["Ingest endpoint"]
end

subgraph group_backend["API and persistence"]
  node_asteroid_service["Asteroid service"]
  node_asteroid_repo["Asteroid repository"]
  node_approach_repo["Approach repository"]
  node_snapshot_repo["Risk snapshot repository"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis cache")]
  node_neo_controller["NEO read API<br/>[NeoController.java]"]
  node_dashboard_row["Dashboard response row<br/>[DashboardRow.java]"]
  node_detail_api["Detail data API<br/>[NeoController.java]"]
end

subgraph group_frontend["Dashboard frontend"]
  node_app["Frontend app<br/>[App.jsx]"]
  node_data_hook["Dashboard data hook<br/>[useAsteroidData.js]"]
  node_detail_hook["Asteroid detail hook"]
  node_api_client["API client<br/>[client.js]"]
  node_orbit_view["3D home view<br/>[OrbitView.jsx]"]
  node_archive_view["Asteroid list view<br/>[ArchiveView.jsx]"]
  node_impact_view["Impact detail view<br/>[ImpactView.jsx]"]
  node_scene["3D scene<br/>[SystemScene.jsx]"]
  node_hud["Dashboard panels"]
  node_energy["Energy explanations"]
  node_table["Asteroid table<br/>[AsteroidTable.jsx]"]
end

subgraph group_security["Request safeguards"]
  node_filters["Request filters"]
  node_web_config["Web configuration<br/>[WebConfig.java]"]
end

node_scheduler(("Daily scheduler"))
node_operator(("Ingest operator"))
node_visitor(("Dashboard visitor"))
node_nasa{{"NASA NeoWs"}}

node_scheduler -->|"triggers daily ingest"| node_asteroid_service
node_operator -->|"requests ingest"| node_filters
node_filters -->|"passes request"| node_ingest_controller
node_ingest_controller -->|"calls ingest"| node_asteroid_service
node_asteroid_service -->|"fetches feed"| node_nasa_client
node_nasa_client -->|"requests NEO feed"| node_nasa
node_asteroid_service -->|"upserts asteroids"| node_asteroid_repo
node_asteroid_service -->|"upserts approaches"| node_approach_repo
node_asteroid_service -->|"records energy snapshots"| node_snapshot_repo
node_asteroid_repo -->|"reads and writes"| node_postgres
node_approach_repo -->|"reads and writes"| node_postgres
node_snapshot_repo -->|"reads and writes"| node_postgres
node_asteroid_service -->|"evicts read caches"| node_redis
node_neo_controller -->|"requests read data"| node_asteroid_service
node_asteroid_service -->|"serves cached reads"| node_redis
node_asteroid_service -->|"builds dashboard rows"| node_dashboard_row
node_visitor -->|"uses dashboard"| node_app
node_app -->|"shows home"| node_orbit_view
node_app -->|"shows asteroid list"| node_archive_view
node_app -->|"shows asteroid detail"| node_impact_view
node_orbit_view -->|"loads dashboard data"| node_data_hook
node_archive_view -->|"loads asteroid data"| node_data_hook
node_impact_view -->|"loads histories"| node_detail_hook
node_data_hook -->|"requests dashboard"| node_api_client
node_detail_hook -->|"requests histories"| node_api_client
node_api_client -->|"calls read API"| node_filters
node_scene -->|"presents scene status"| node_hud
node_orbit_view -->|"renders globe"| node_scene
node_orbit_view -->|"explains impact energy"| node_energy
node_archive_view -->|"renders tracked objects"| node_table
node_impact_view -->|"displays approach and energy history"| node_detail_api
node_web_config -->|"configures web access"| node_filters

click node_nasa_client "https://github.com/abdullahmahfouz/neo-watch/blob/main/src/main/java/com/abdullah/neowatch/client/NasaClient.java"
click node_ingest_controller "https://github.com/abdullahmahfouz/neo-watch/blob/main/src/main/java/com/abdullah/neowatch/controller/IngestController.java"
click node_asteroid_service "https://github.com/abdullahmahfouz/neo-watch/blob/main/src/main/java/com/abdullah/neowatch/service/AsteroidService.java"
click node_asteroid_repo "https://github.com/abdullahmahfouz/neo-watch/blob/main/src/main/java/com/abdullah/neowatch/repository/AsteroidRepository.java"
click node_approach_repo "https://github.com/abdullahmahfouz/neo-watch/blob/main/src/main/java/com/abdullah/neowatch/repository/CloseApproachRepository.java"
click node_snapshot_repo "https://github.com/abdullahmahfouz/neo-watch/blob/main/src/main/java/com/abdullah/neowatch/repository/RiskSnapshotRepository.java"
click node_neo_controller "https://github.com/abdullahmahfouz/neo-watch/blob/main/src/main/java/com/abdullah/neowatch/controller/NeoController.java"
click node_dashboard_row "https://github.com/abdullahmahfouz/neo-watch/blob/main/src/main/java/com/abdullah/neowatch/dto/DashboardRow.java"
click node_filters "https://github.com/abdullahmahfouz/neo-watch/tree/main/src/main/java/com/abdullah/neowatch/config"
click node_web_config "https://github.com/abdullahmahfouz/neo-watch/blob/main/src/main/java/com/abdullah/neowatch/config/WebConfig.java"
click node_app "https://github.com/abdullahmahfouz/neo-watch/blob/main/frontend/src/App.jsx"
click node_data_hook "https://github.com/abdullahmahfouz/neo-watch/blob/main/frontend/src/hooks/useAsteroidData.js"
click node_detail_hook "https://github.com/abdullahmahfouz/neo-watch/blob/main/frontend/src/hooks/useAsteroidDetail.js"
click node_api_client "https://github.com/abdullahmahfouz/neo-watch/blob/main/frontend/src/api/client.js"
click node_orbit_view "https://github.com/abdullahmahfouz/neo-watch/blob/main/frontend/src/pages/OrbitView.jsx"
click node_archive_view "https://github.com/abdullahmahfouz/neo-watch/blob/main/frontend/src/pages/ArchiveView.jsx"
click node_impact_view "https://github.com/abdullahmahfouz/neo-watch/blob/main/frontend/src/pages/ImpactView.jsx"
click node_scene "https://github.com/abdullahmahfouz/neo-watch/blob/main/frontend/src/three/SystemScene.jsx"
click node_hud "https://github.com/abdullahmahfouz/neo-watch/tree/main/frontend/src/components/hud"
click node_energy "https://github.com/abdullahmahfouz/neo-watch/blob/main/frontend/src/components/EnergyExplainer.jsx"
click node_table "https://github.com/abdullahmahfouz/neo-watch/blob/main/frontend/src/components/AsteroidTable.jsx"
click node_detail_api "https://github.com/abdullahmahfouz/neo-watch/blob/main/src/main/java/com/abdullah/neowatch/controller/NeoController.java"

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_nasa_client,node_ingest_controller toneBlue
class node_asteroid_service,node_asteroid_repo,node_approach_repo,node_snapshot_repo,node_postgres,node_redis,node_neo_controller,node_dashboard_row,node_detail_api toneAmber
class node_app,node_data_hook,node_detail_hook,node_api_client,node_orbit_view,node_archive_view,node_impact_view,node_scene,node_hud,node_energy,node_table toneMint
class node_filters,node_web_config,node_scheduler toneRose
class node_operator,node_visitor,node_nasa toneIndigo
```

## Components

### Data ingestion

- [NASA feed client](https://github.com/abdullahmahfouz/neo-watch/blob/main/src/main/java/com/abdullah/neowatch/client/NasaClient.java): `src/main/java/com/abdullah/neowatch/client/NasaClient.java`
- [Ingest endpoint](https://github.com/abdullahmahfouz/neo-watch/blob/main/src/main/java/com/abdullah/neowatch/controller/IngestController.java): `src/main/java/com/abdullah/neowatch/controller/IngestController.java`

### API and persistence

- [Asteroid service](https://github.com/abdullahmahfouz/neo-watch/blob/main/src/main/java/com/abdullah/neowatch/service/AsteroidService.java): `src/main/java/com/abdullah/neowatch/service/AsteroidService.java`
- [Asteroid repository](https://github.com/abdullahmahfouz/neo-watch/blob/main/src/main/java/com/abdullah/neowatch/repository/AsteroidRepository.java): `src/main/java/com/abdullah/neowatch/repository/AsteroidRepository.java`
- [Approach repository](https://github.com/abdullahmahfouz/neo-watch/blob/main/src/main/java/com/abdullah/neowatch/repository/CloseApproachRepository.java): `src/main/java/com/abdullah/neowatch/repository/CloseApproachRepository.java`
- [Risk snapshot repository](https://github.com/abdullahmahfouz/neo-watch/blob/main/src/main/java/com/abdullah/neowatch/repository/RiskSnapshotRepository.java): `src/main/java/com/abdullah/neowatch/repository/RiskSnapshotRepository.java`
- **PostgreSQL**
- **Redis cache**
- [NEO read API](https://github.com/abdullahmahfouz/neo-watch/blob/main/src/main/java/com/abdullah/neowatch/controller/NeoController.java): `src/main/java/com/abdullah/neowatch/controller/NeoController.java`
- [Dashboard response row](https://github.com/abdullahmahfouz/neo-watch/blob/main/src/main/java/com/abdullah/neowatch/dto/DashboardRow.java): `src/main/java/com/abdullah/neowatch/dto/DashboardRow.java`
- [Detail data API](https://github.com/abdullahmahfouz/neo-watch/blob/main/src/main/java/com/abdullah/neowatch/controller/NeoController.java): `src/main/java/com/abdullah/neowatch/controller/NeoController.java`

### Dashboard frontend

- [Frontend app](https://github.com/abdullahmahfouz/neo-watch/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Dashboard data hook](https://github.com/abdullahmahfouz/neo-watch/blob/main/frontend/src/hooks/useAsteroidData.js): `frontend/src/hooks/useAsteroidData.js`
- [Asteroid detail hook](https://github.com/abdullahmahfouz/neo-watch/blob/main/frontend/src/hooks/useAsteroidDetail.js): `frontend/src/hooks/useAsteroidDetail.js`
- [API client](https://github.com/abdullahmahfouz/neo-watch/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`
- [3D home view](https://github.com/abdullahmahfouz/neo-watch/blob/main/frontend/src/pages/OrbitView.jsx): `frontend/src/pages/OrbitView.jsx`
- [Asteroid list view](https://github.com/abdullahmahfouz/neo-watch/blob/main/frontend/src/pages/ArchiveView.jsx): `frontend/src/pages/ArchiveView.jsx`
- [Impact detail view](https://github.com/abdullahmahfouz/neo-watch/blob/main/frontend/src/pages/ImpactView.jsx): `frontend/src/pages/ImpactView.jsx`
- [3D scene](https://github.com/abdullahmahfouz/neo-watch/blob/main/frontend/src/three/SystemScene.jsx): `frontend/src/three/SystemScene.jsx`
- [Dashboard panels](https://github.com/abdullahmahfouz/neo-watch/tree/main/frontend/src/components/hud): `frontend/src/components/hud`
- [Energy explanations](https://github.com/abdullahmahfouz/neo-watch/blob/main/frontend/src/components/EnergyExplainer.jsx): `frontend/src/components/EnergyExplainer.jsx`
- [Asteroid table](https://github.com/abdullahmahfouz/neo-watch/blob/main/frontend/src/components/AsteroidTable.jsx): `frontend/src/components/AsteroidTable.jsx`

### Request safeguards

- [Request filters](https://github.com/abdullahmahfouz/neo-watch/tree/main/src/main/java/com/abdullah/neowatch/config): `src/main/java/com/abdullah/neowatch/config`
- [Web configuration](https://github.com/abdullahmahfouz/neo-watch/blob/main/src/main/java/com/abdullah/neowatch/config/WebConfig.java): `src/main/java/com/abdullah/neowatch/config/WebConfig.java`

### Other components

- **Daily scheduler**
- **Ingest operator**
- **Dashboard visitor**
- **NASA NeoWs**

## Connections

- Daily scheduler → Asteroid service: triggers daily ingest
- Ingest operator → Request filters: requests ingest
- Request filters → Ingest endpoint: passes request
- Ingest endpoint → Asteroid service: calls ingest
- Asteroid service → NASA feed client: fetches feed
- NASA feed client → NASA NeoWs: requests NEO feed
- Asteroid service → Asteroid repository: upserts asteroids
- Asteroid service → Approach repository: upserts approaches
- Asteroid service → Risk snapshot repository: records energy snapshots
- Asteroid repository → PostgreSQL: reads and writes
- Approach repository → PostgreSQL: reads and writes
- Risk snapshot repository → PostgreSQL: reads and writes
- Asteroid service → Redis cache: evicts read caches
- NEO read API → Asteroid service: requests read data
- Asteroid service → Redis cache: serves cached reads
- Asteroid service → Dashboard response row: builds dashboard rows
- Dashboard visitor → Frontend app: uses dashboard
- Frontend app → 3D home view: shows home
- Frontend app → Asteroid list view: shows asteroid list
- Frontend app → Impact detail view: shows asteroid detail
- 3D home view → Dashboard data hook: loads dashboard data
- Asteroid list view → Dashboard data hook: loads asteroid data
- Impact detail view → Asteroid detail hook: loads histories
- Dashboard data hook → API client: requests dashboard
- Asteroid detail hook → API client: requests histories
- API client → Request filters: calls read API
- 3D scene → Dashboard panels: presents scene status
- 3D home view → 3D scene: renders globe
- 3D home view → Energy explanations: explains impact energy
- Asteroid list view → Asteroid table: renders tracked objects
- Impact detail view → Detail data API: displays approach and energy history
- Web configuration → Request filters: configures web access