# red1-rahman/cosmic-detective-release architecture

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

- Interactive diagram: https://gitdiagram.com/red1-rahman/cosmic-detective-release
- Repository: https://github.com/red1-rahman/cosmic-detective-release

## Overview

Cosmic Detective is a citizen-science game for inspecting archival sky images, submitting candidate flags to visible verification, and earning progression; it also provides a live SPHEREx research portal and collaborative squads. The player enters through the app router: training cases load image or light-curve data, then run staged checks and update game progress. The portal searches IRSA and can submit registered image-processing jobs to a Python worker. Accounts and squad workflows use Supabase. Some backend and screen implementations were not sampled, so those links follow explicit README statements rather than inferred code calls.

Main entry points: [`src/screens/ResearchPortal.tsx`](https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/screens/ResearchPortal.tsx) (Research Portal), [`src/App.tsx`](https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/App.tsx) (App Router), [`worker/spherex_worker.py`](https://github.com/red1-rahman/cosmic-detective-release/blob/main/worker/spherex_worker.py) (SPHEREx Worker), [`src/lib/spherex.ts`](https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/lib/spherex.ts) (SPHEREx Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_game["Game and Cases"]
  node_app["App Router<br/>[App.tsx]"]
  node_map["Case Map<br/>[MapScreen.tsx]"]
  node_skycase["Sky Plate Cases<br/>[CaseScreen.tsx]"]
  node_bandcase["Multi-band Case<br/>[BandsCase.tsx]"]
  node_curvecase["Light Curve Case<br/>[LightCurveCase.tsx]"]
  node_verification["Verification Pipeline<br/>[Pipeline.tsx]"]
  node_casefixtures["Case Data<br/>[fixtures.ts]"]
  node_curvedata["Light Curve Data<br/>[lightcurves.ts]"]
end

subgraph group_research["SPHEREx Research"]
  node_researchportal["Research Portal<br/>[ResearchPortal.tsx]"]
  node_spherexclient["SPHEREx Client<br/>[spherex.ts]"]
  node_irsaquery["IRSA Query<br/>[irsa.ts]"]
  node_spectralimport["Spectral Import<br/>[spherex-irsa.ts]"]
  node_seriesanalysis["Series Analysis<br/>[spherex-series.ts]"]
  node_registry["Target Registry<br/>[registry.ts]"]
  node_processingclient["Processing Client<br/>[processing.ts]"]
end

subgraph group_backend["Processing Services"]
  node_netlifyjob["Job API<br/>[spherex-job.mjs]"]
  node_processinglib["Job Processing<br/>[processing.mjs]"]
  node_worker["SPHEREx Worker<br/>[spherex_worker.py]"]
  node_blink["Blink Reprojection<br/>[blink.py]"]
  node_cutouts["Image Cutouts<br/>[cutouts.py]"]
  node_products["Image Products<br/>[products.py]"]
  node_jobqueue["Worker Jobs<br/>[jobs.py]"]
end

subgraph group_progress["Progress and Accounts"]
  node_gamestate["Game State<br/>[store.tsx]"]
  node_auth["Authentication<br/>[auth.tsx]"]
  node_supabaseclient["Supabase Client<br/>[supabase.ts]"]
  node_supabase[("Supabase")]
end

subgraph group_squads["Research Squads"]
  node_squadpanel["Squad Panel<br/>[SquadPanel.tsx]"]
  node_squadservice["Squad Service<br/>[squad.ts]"]
end

node_player(("Player"))
node_irsa["IRSA SPHEREx Archive"]

node_player -->|"plays"| node_app
node_app -->|"routes to"| node_map
node_app -->|"routes to"| node_skycase
node_app -->|"routes to"| node_bandcase
node_app -->|"routes to"| node_curvecase
node_app -->|"routes to"| node_researchportal
node_skycase -->|"reads tiles"| node_casefixtures
node_bandcase -->|"reads bands"| node_casefixtures
node_curvecase -->|"loads series"| node_curvedata
node_skycase -->|"runs checks"| node_verification
node_bandcase -->|"runs checks"| node_verification
node_curvecase -->|"runs checks"| node_verification
node_researchportal -->|"uses capabilities"| node_spherexclient
node_researchportal -->|"queries archive"| node_irsaquery
node_irsaquery -->|"uses types"| node_spherexclient
node_researchportal -->|"parses import"| node_spectralimport
node_spectralimport -->|"uses types"| node_spherexclient
node_researchportal -->|"uses analysis"| node_seriesanalysis
node_seriesanalysis -->|"uses types"| node_spherexclient
node_researchportal -->|"loads registry"| node_registry
node_researchportal -->|"requests jobs"| node_processingclient
node_researchportal -->|"searches archive"| node_irsa
node_processingclient -->|"submits request"| node_netlifyjob
node_netlifyjob -->|"delegates jobs"| node_processinglib
node_worker -->|"uses job state"| node_jobqueue
node_worker -->|"builds cutouts"| node_cutouts
node_worker -->|"reprojects images"| node_blink
node_worker -->|"writes products"| node_products
node_player -->|"earns progress"| node_gamestate
node_gamestate -->|"syncs saves"| node_auth
node_auth -->|"authenticates"| node_supabaseclient
node_supabaseclient -->|"connects"| node_supabase
node_player -->|"joins squad work"| node_squadpanel
node_squadpanel -->|"calls service"| node_squadservice
node_squadservice -->|"uses client"| node_supabaseclient
node_squadservice -->|"reads squad data"| node_supabase

click node_app "https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/App.tsx"
click node_map "https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/screens/MapScreen.tsx"
click node_skycase "https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/screens/CaseScreen.tsx"
click node_bandcase "https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/screens/BandsCase.tsx"
click node_curvecase "https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/screens/LightCurveCase.tsx"
click node_verification "https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/components/Pipeline.tsx"
click node_casefixtures "https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/data/fixtures.ts"
click node_curvedata "https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/data/lightcurves.ts"
click node_researchportal "https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/screens/ResearchPortal.tsx"
click node_spherexclient "https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/lib/spherex.ts"
click node_irsaquery "https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/lib/irsa.ts"
click node_spectralimport "https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/lib/spherex-irsa.ts"
click node_seriesanalysis "https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/lib/spherex-series.ts"
click node_registry "https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/lib/registry.ts"
click node_processingclient "https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/lib/processing.ts"
click node_netlifyjob "https://github.com/red1-rahman/cosmic-detective-release/blob/main/netlify/functions/spherex-job.mjs"
click node_processinglib "https://github.com/red1-rahman/cosmic-detective-release/blob/main/netlify/lib/processing.mjs"
click node_worker "https://github.com/red1-rahman/cosmic-detective-release/blob/main/worker/spherex_worker.py"
click node_blink "https://github.com/red1-rahman/cosmic-detective-release/blob/main/worker/lib/blink.py"
click node_cutouts "https://github.com/red1-rahman/cosmic-detective-release/blob/main/worker/lib/cutouts.py"
click node_products "https://github.com/red1-rahman/cosmic-detective-release/blob/main/worker/lib/products.py"
click node_jobqueue "https://github.com/red1-rahman/cosmic-detective-release/blob/main/worker/lib/jobs.py"
click node_gamestate "https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/lib/store.tsx"
click node_auth "https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/lib/auth.tsx"
click node_supabaseclient "https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/lib/supabase.ts"
click node_squadpanel "https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/components/SquadPanel.tsx"
click node_squadservice "https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/lib/squad.ts"

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_map,node_skycase,node_bandcase,node_curvecase,node_verification,node_casefixtures,node_curvedata toneBlue
class node_researchportal,node_spherexclient,node_irsaquery,node_spectralimport,node_seriesanalysis,node_registry,node_processingclient toneAmber
class node_netlifyjob,node_processinglib,node_worker,node_blink,node_cutouts,node_products,node_jobqueue toneMint
class node_gamestate,node_auth,node_supabaseclient,node_supabase toneRose
class node_squadpanel,node_squadservice,node_player,node_irsa toneIndigo
```

## Components

### Game and Cases

- [App Router](https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/App.tsx): `src/App.tsx`
- [Case Map](https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/screens/MapScreen.tsx): `src/screens/MapScreen.tsx`
- [Sky Plate Cases](https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/screens/CaseScreen.tsx): `src/screens/CaseScreen.tsx`
- [Multi-band Case](https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/screens/BandsCase.tsx): `src/screens/BandsCase.tsx`
- [Light Curve Case](https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/screens/LightCurveCase.tsx): `src/screens/LightCurveCase.tsx`
- [Verification Pipeline](https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/components/Pipeline.tsx): `src/components/Pipeline.tsx`
- [Case Data](https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/data/fixtures.ts): `src/data/fixtures.ts`
- [Light Curve Data](https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/data/lightcurves.ts): `src/data/lightcurves.ts`

### SPHEREx Research

- [Research Portal](https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/screens/ResearchPortal.tsx): `src/screens/ResearchPortal.tsx`
- [SPHEREx Client](https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/lib/spherex.ts): `src/lib/spherex.ts`
- [IRSA Query](https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/lib/irsa.ts): `src/lib/irsa.ts`
- [Spectral Import](https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/lib/spherex-irsa.ts): `src/lib/spherex-irsa.ts`
- [Series Analysis](https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/lib/spherex-series.ts): `src/lib/spherex-series.ts`
- [Target Registry](https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/lib/registry.ts): `src/lib/registry.ts`
- [Processing Client](https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/lib/processing.ts): `src/lib/processing.ts`

### Processing Services

- [Job API](https://github.com/red1-rahman/cosmic-detective-release/blob/main/netlify/functions/spherex-job.mjs): `netlify/functions/spherex-job.mjs`
- [Job Processing](https://github.com/red1-rahman/cosmic-detective-release/blob/main/netlify/lib/processing.mjs): `netlify/lib/processing.mjs`
- [SPHEREx Worker](https://github.com/red1-rahman/cosmic-detective-release/blob/main/worker/spherex_worker.py): `worker/spherex_worker.py`
- [Blink Reprojection](https://github.com/red1-rahman/cosmic-detective-release/blob/main/worker/lib/blink.py): `worker/lib/blink.py`
- [Image Cutouts](https://github.com/red1-rahman/cosmic-detective-release/blob/main/worker/lib/cutouts.py): `worker/lib/cutouts.py`
- [Image Products](https://github.com/red1-rahman/cosmic-detective-release/blob/main/worker/lib/products.py): `worker/lib/products.py`
- [Worker Jobs](https://github.com/red1-rahman/cosmic-detective-release/blob/main/worker/lib/jobs.py): `worker/lib/jobs.py`

### Progress and Accounts

- [Game State](https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/lib/store.tsx): `src/lib/store.tsx`
- [Authentication](https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/lib/auth.tsx): `src/lib/auth.tsx`
- [Supabase Client](https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/lib/supabase.ts): `src/lib/supabase.ts`
- **Supabase**

### Research Squads

- [Squad Panel](https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/components/SquadPanel.tsx): `src/components/SquadPanel.tsx`
- [Squad Service](https://github.com/red1-rahman/cosmic-detective-release/blob/main/src/lib/squad.ts): `src/lib/squad.ts`

### Other components

- **Player**
- **IRSA SPHEREx Archive**

## Connections

- Player → App Router: plays (evidence: `README.md`)
- App Router → Case Map: routes to (evidence: `src/App.tsx`)
- App Router → Sky Plate Cases: routes to (evidence: `src/App.tsx`)
- App Router → Multi-band Case: routes to (evidence: `src/App.tsx`)
- App Router → Light Curve Case: routes to (evidence: `src/App.tsx`)
- App Router → Research Portal: routes to (evidence: `src/App.tsx`)
- Sky Plate Cases → Case Data: reads tiles (evidence: `src/screens/CaseScreen.tsx`)
- Multi-band Case → Case Data: reads bands (evidence: `src/screens/BandsCase.tsx`)
- Light Curve Case → Light Curve Data: loads series (evidence: `src/screens/LightCurveCase.tsx`)
- Sky Plate Cases → Verification Pipeline: runs checks (evidence: `README.md`)
- Multi-band Case → Verification Pipeline: runs checks (evidence: `src/screens/BandsCase.tsx`)
- Light Curve Case → Verification Pipeline: runs checks (evidence: `src/screens/LightCurveCase.tsx`)
- Research Portal → SPHEREx Client: uses capabilities (evidence: `src/screens/ResearchPortal.tsx`)
- Research Portal → IRSA Query: queries archive (evidence: `src/screens/ResearchPortal.tsx`)
- IRSA Query → SPHEREx Client: uses types (evidence: `src/lib/irsa.ts`)
- Research Portal → Spectral Import: parses import (evidence: `src/screens/ResearchPortal.tsx`)
- Spectral Import → SPHEREx Client: uses types (evidence: `src/lib/spherex-irsa.ts`)
- Research Portal → Series Analysis: uses analysis (evidence: `src/screens/ResearchPortal.tsx`)
- Series Analysis → SPHEREx Client: uses types (evidence: `src/lib/spherex-series.ts`)
- Research Portal → Target Registry: loads registry (evidence: `src/screens/ResearchPortal.tsx`)
- Research Portal → Processing Client: requests jobs (evidence: `src/screens/ResearchPortal.tsx`)
- Research Portal → IRSA SPHEREx Archive: searches archive (evidence: `README.md`)
- Processing Client → Job API: submits request (evidence: `README.md`)
- Job API → Job Processing: delegates jobs (evidence: `netlify/functions/spherex-job.mjs`)
- SPHEREx Worker → Worker Jobs: uses job state (evidence: `worker/spherex_worker.py`)
- SPHEREx Worker → Image Cutouts: builds cutouts (evidence: `worker/spherex_worker.py`)
- SPHEREx Worker → Blink Reprojection: reprojects images (evidence: `worker/spherex_worker.py`)
- SPHEREx Worker → Image Products: writes products (evidence: `worker/spherex_worker.py`)
- Player → Game State: earns progress (evidence: `README.md`)
- Game State → Authentication: syncs saves (evidence: `src/lib/auth.tsx`)
- Authentication → Supabase Client: authenticates (evidence: `src/lib/auth.tsx`)
- Supabase Client → Supabase: connects (evidence: `README.md`)
- Player → Squad Panel: joins squad work (evidence: `README.md`)
- Squad Panel → Squad Service: calls service (evidence: `src/components/SquadPanel.tsx`)
- Squad Service → Supabase Client: uses client (evidence: `src/lib/squad.ts`)
- Squad Service → Supabase: reads squad data (evidence: `README.md`)
