# deaththekid1614/cosmic_eye architecture

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

- Interactive diagram: https://gitdiagram.com/deaththekid1614/cosmic_eye
- Repository: https://github.com/deaththekid1614/cosmic_eye

## Overview

Cosmic Eye is a React/FastAPI explorer for public NASA SPHEREx observations. Users search by object name or sky coordinates, browse curated or recent results, and inspect metadata and FITS-derived previews; Color Lab explores wavelength bands and palettes, while Sky Map offers deep-sky and Solar System views. The backend resolves names, queries and normalizes archive products, and generates cached previews. Relationships for unsampled features are included only where the README documents them; source excerpts and the SOURCE INDEX support the shown implementation links.

Main entry points: [`backend/app/api/observations.py`](https://github.com/deaththekid1614/cosmic_eye/blob/main/backend/app/api/observations.py) (Observation Routes), [`frontend/src/App.tsx`](https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/App.tsx) (App routes), [`frontend/src/api/client.ts`](https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/api/client.ts) (HTTP Client), [`frontend/src/api/observations.ts`](https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/api/observations.ts) (Observation Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Explorer interface"]
  node_app["App routes<br/>[App.tsx]"]
  node_ai_page["AI Search<br/>[AISearchPage.tsx]"]
  node_explore_page["Manual Search<br/>[ExplorePage.tsx]"]
  node_browse_page["Browse and Regions<br/>[BrowsePage.tsx]"]
  node_rgb_page["Color Lab"]
  node_sky_page["Sky Map<br/>[SkyMapPage.tsx]"]
  node_sky_globe["Deep-sky Globe<br/>[SkyMapGlobe.tsx]"]
  node_solar_view["Solar System View"]
  node_observation_viewer["Observation Viewer"]
  node_api_client["HTTP Client<br/>[client.ts]"]
  node_observation_api["Observation Client<br/>[observations.ts]"]
end

subgraph group_api["API and routing"]
  node_api_router["Observation Routes<br/>[observations.py]"]
  node_app_boot["FastAPI App<br/>[main.py]"]
  node_observation_schema["Observation Schemas<br/>[observation.py]"]
end

subgraph group_archive["Archive and previews"]
  node_archive_service["Archive Search<br/>[archive_service.py]"]
  node_irsa_adapter["SPHEREx Adapter<br/>[irsa_spherex.py]"]
  node_preview_service["FITS Preview<br/>[preview_service.py]"]
end

subgraph group_targets["Targets and models"]
  node_name_resolver["Name Resolver<br/>[ai_service.py]"]
  node_featured_targets["Featured Targets"]
  node_solar_model["Orbital Model"]
end

node_user(("Explorer"))
node_irsa["NASA/IPAC IRSA"]
node_simbad["SIMBAD"]
node_jpl["JPL Horizons / SBDB"]

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_ai_page
node_app -->|"routes to"| node_explore_page
node_app -->|"routes to"| node_browse_page
node_app -->|"routes to"| node_rgb_page
node_app -->|"routes to"| node_sky_page
node_ai_page -->|"resolves name"| node_api_client
node_ai_page -->|"searches coordinates"| node_observation_api
node_explore_page -->|"searches archive"| node_observation_api
node_browse_page -->|"loads observations"| node_observation_api
node_rgb_page -->|"loads wavelength sets"| node_observation_api
node_observation_api -->|"sends requests"| node_api_client
node_ai_page -->|"opens result"| node_observation_viewer
node_observation_viewer -->|"builds preview URL"| node_api_client
node_sky_page -->|"renders deep sky"| node_sky_globe
node_sky_page -->|"renders solar view"| node_solar_view
node_sky_page -->|"requests model"| node_api_client
node_api_client -->|"HTTP requests"| node_api_router
node_app_boot -->|"includes routes"| node_api_router
node_api_router -->|"validates responses"| node_observation_schema
node_api_router -->|"resolves targets"| node_name_resolver
node_api_router -->|"loads featured"| node_featured_targets
node_api_router -->|"gets orbital model"| node_solar_model
node_api_router -->|"searches archive"| node_archive_service
node_api_router -->|"generates previews"| node_preview_service
node_archive_service -->|"queries coverage"| node_irsa_adapter
node_irsa_adapter -->|"queries SPHEREx"| node_irsa
node_preview_service -->|"downloads FITS"| node_irsa
node_name_resolver -->|"looks up names"| node_simbad
node_solar_model -->|"fetches elements"| node_jpl

click node_app "https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/App.tsx"
click node_ai_page "https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/routes/AISearchPage.tsx"
click node_explore_page "https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/routes/ExplorePage.tsx"
click node_browse_page "https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/routes/BrowsePage.tsx"
click node_rgb_page "https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/routes/RGBExplorerPage.tsx"
click node_sky_page "https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/routes/SkyMapPage.tsx"
click node_sky_globe "https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/components/SkyMapGlobe.tsx"
click node_solar_view "https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/components/SolarSystemExplorer.tsx"
click node_observation_viewer "https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/components/ObservationViewer.tsx"
click node_api_client "https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/api/client.ts"
click node_observation_api "https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/api/observations.ts"
click node_api_router "https://github.com/deaththekid1614/cosmic_eye/blob/main/backend/app/api/observations.py"
click node_app_boot "https://github.com/deaththekid1614/cosmic_eye/blob/main/backend/app/main.py"
click node_observation_schema "https://github.com/deaththekid1614/cosmic_eye/blob/main/backend/app/schemas/observation.py"
click node_name_resolver "https://github.com/deaththekid1614/cosmic_eye/blob/main/backend/app/services/ai_service.py"
click node_featured_targets "https://github.com/deaththekid1614/cosmic_eye/blob/main/backend/app/services/featured_service.py"
click node_solar_model "https://github.com/deaththekid1614/cosmic_eye/blob/main/backend/app/services/solar_system_model_service.py"
click node_archive_service "https://github.com/deaththekid1614/cosmic_eye/blob/main/backend/app/services/archive_service.py"
click node_irsa_adapter "https://github.com/deaththekid1614/cosmic_eye/blob/main/backend/app/adapters/irsa_spherex.py"
click node_preview_service "https://github.com/deaththekid1614/cosmic_eye/blob/main/backend/app/services/preview_service.py"

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_app,node_ai_page,node_explore_page,node_browse_page,node_rgb_page,node_sky_page,node_sky_globe,node_solar_view,node_observation_viewer,node_api_client,node_observation_api toneBlue
class node_api_router,node_app_boot,node_observation_schema toneAmber
class node_archive_service,node_irsa_adapter,node_preview_service toneMint
class node_name_resolver,node_featured_targets,node_solar_model toneRose
class node_user,node_irsa,node_simbad,node_jpl toneIndigo
```

## Components

### Explorer interface

- [App routes](https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [AI Search](https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/routes/AISearchPage.tsx): `frontend/src/routes/AISearchPage.tsx`
- [Manual Search](https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/routes/ExplorePage.tsx): `frontend/src/routes/ExplorePage.tsx`
- [Browse and Regions](https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/routes/BrowsePage.tsx): `frontend/src/routes/BrowsePage.tsx`
- [Color Lab](https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/routes/RGBExplorerPage.tsx): `frontend/src/routes/RGBExplorerPage.tsx`
- [Sky Map](https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/routes/SkyMapPage.tsx): `frontend/src/routes/SkyMapPage.tsx`
- [Deep-sky Globe](https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/components/SkyMapGlobe.tsx): `frontend/src/components/SkyMapGlobe.tsx`
- [Solar System View](https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/components/SolarSystemExplorer.tsx): `frontend/src/components/SolarSystemExplorer.tsx`
- [Observation Viewer](https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/components/ObservationViewer.tsx): `frontend/src/components/ObservationViewer.tsx`
- [HTTP Client](https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Observation Client](https://github.com/deaththekid1614/cosmic_eye/blob/main/frontend/src/api/observations.ts): `frontend/src/api/observations.ts`

### API and routing

- [Observation Routes](https://github.com/deaththekid1614/cosmic_eye/blob/main/backend/app/api/observations.py): `backend/app/api/observations.py`
- [FastAPI App](https://github.com/deaththekid1614/cosmic_eye/blob/main/backend/app/main.py): `backend/app/main.py`
- [Observation Schemas](https://github.com/deaththekid1614/cosmic_eye/blob/main/backend/app/schemas/observation.py): `backend/app/schemas/observation.py`

### Archive and previews

- [Archive Search](https://github.com/deaththekid1614/cosmic_eye/blob/main/backend/app/services/archive_service.py): `backend/app/services/archive_service.py`
- [SPHEREx Adapter](https://github.com/deaththekid1614/cosmic_eye/blob/main/backend/app/adapters/irsa_spherex.py): `backend/app/adapters/irsa_spherex.py`
- [FITS Preview](https://github.com/deaththekid1614/cosmic_eye/blob/main/backend/app/services/preview_service.py): `backend/app/services/preview_service.py`

### Targets and models

- [Name Resolver](https://github.com/deaththekid1614/cosmic_eye/blob/main/backend/app/services/ai_service.py): `backend/app/services/ai_service.py`
- [Featured Targets](https://github.com/deaththekid1614/cosmic_eye/blob/main/backend/app/services/featured_service.py): `backend/app/services/featured_service.py`
- [Orbital Model](https://github.com/deaththekid1614/cosmic_eye/blob/main/backend/app/services/solar_system_model_service.py): `backend/app/services/solar_system_model_service.py`

### Other components

- **Explorer**
- **NASA/IPAC IRSA**
- **SIMBAD**
- **JPL Horizons / SBDB**

## Connections

- Explorer → App routes: uses (evidence: `README.md`)
- App routes → AI Search: routes to (evidence: `frontend/src/App.tsx`)
- App routes → Manual Search: routes to (evidence: `frontend/src/App.tsx`)
- App routes → Browse and Regions: routes to (evidence: `frontend/src/App.tsx`)
- App routes → Color Lab: routes to (evidence: `frontend/src/App.tsx`)
- App routes → Sky Map: routes to (evidence: `frontend/src/App.tsx`)
- AI Search → HTTP Client: resolves name (evidence: `frontend/src/routes/AISearchPage.tsx`)
- AI Search → Observation Client: searches coordinates (evidence: `frontend/src/routes/AISearchPage.tsx`)
- Manual Search → Observation Client: searches archive (evidence: `frontend/src/api/observations.ts`)
- Browse and Regions → Observation Client: loads observations (evidence: `frontend/src/api/observations.ts`)
- Color Lab → Observation Client: loads wavelength sets (evidence: `frontend/src/api/observations.ts`)
- Observation Client → HTTP Client: sends requests (evidence: `frontend/src/api/observations.ts`)
- AI Search → Observation Viewer: opens result (evidence: `frontend/src/routes/AISearchPage.tsx`)
- Observation Viewer → HTTP Client: builds preview URL (evidence: `frontend/src/components/ObservationViewer.tsx`)
- Sky Map → Deep-sky Globe: renders deep sky (evidence: `frontend/src/routes/SkyMapPage.tsx`)
- Sky Map → Solar System View: renders solar view (evidence: `frontend/src/routes/SkyMapPage.tsx`)
- Sky Map → HTTP Client: requests model (evidence: `frontend/src/routes/SkyMapPage.tsx`)
- HTTP Client → Observation Routes: HTTP requests (evidence: `frontend/src/api/client.ts`)
- FastAPI App → Observation Routes: includes routes (evidence: `backend/app/main.py`)
- Observation Routes → Observation Schemas: validates responses (evidence: `backend/app/api/observations.py`)
- Observation Routes → Name Resolver: resolves targets (evidence: `backend/app/api/observations.py`)
- Observation Routes → Featured Targets: loads featured (evidence: `backend/app/api/observations.py`)
- Observation Routes → Orbital Model: gets orbital model (evidence: `backend/app/api/observations.py`)
- Observation Routes → Archive Search: searches archive (evidence: `backend/app/api/observations.py`)
- Observation Routes → FITS Preview: generates previews (evidence: `backend/app/api/observations.py`)
- Archive Search → SPHEREx Adapter: queries coverage (evidence: `backend/app/services/archive_service.py`)
- SPHEREx Adapter → NASA/IPAC IRSA: queries SPHEREx (evidence: `README.md`)
- FITS Preview → NASA/IPAC IRSA: downloads FITS (evidence: `backend/app/services/preview_service.py`)
- Name Resolver → SIMBAD: looks up names (evidence: `README.md`)
- Orbital Model → JPL Horizons / SBDB: fetches elements (evidence: `README.md`)