Skip to content

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

This is an idea vault for OpenAstro — a distributed amateur telescope network for time-domain astronomy. There is no runnable codebase here. All work is in .md files only.

The project: A network of geographically distributed amateur telescopes coordinating on science cases where distribution is the architectural advantage — stellar occultations, exoplanet transit timing variations (TTVs), GRB/kilonova follow-up, FRB optical counterpart hunting. Single telescopes and even professional observatories cannot replicate these observations.

Folder Structure

The vault has two layers: root-level dumps (older, unprocessed) and NewOpenAstro/ (current, structured thinking). NewOpenAstro/ is authoritative.

NewOpenAstro/ — Current thinking (start here)

  • Science/Projects/ — Prioritized science cases (FRBs, occultations, exoplanet transits, GRBs, M-dwarf flares)
  • Science/Gaps/ — Open research questions and gaps the network could fill
  • Science/Machine Learning/ — Ideas for ML in scheduling, classification, and data processing
  • Tech/Server Infrastructure/ — MVP server design, FastAPI + SQLite stack, deployment, API endpoints
  • Tech/Algorithms/ — Scheduling algorithm designs (greedy handover, task selection)
  • Non Tech/ — Community policy, cash prizes, public comms

Root-level folders

  • Algorithms/ — Older algorithm drafts; prefer NewOpenAstro/Tech/Algorithms/ for current versions
  • Decisions/ — Decision records for choices already made
  • Idea Capture/ — Raw, unprocessed ideas; first stop for new thoughts
  • Archive/ — Dropped or deprecated ideas; check here before re-suggesting anything
  • Resources/ — Reference material and links
  • Stuff To look into/ — Research queue
  • templates/ — Templates for new notes

How To Work Here

  • New raw ideas → Idea Capture/ first, then refine into the right subfolder
  • Before suggesting an idea, check Archive/ — it may already be considered and dropped
  • For science cases, NewOpenAstro/Science/Projects/ has the prioritized list with rationale
  • For technical design, NewOpenAstro/Tech/Server Infrastructure/ has the MVP plan (FastAPI + SQLite + Astropy scheduler)
  • Root-level .md files (e.g., dump.md, massive info dump.md) are brain dumps — useful for context, not authoritative

Key Technical Context

The MVP stack (documented in NewOpenAstro/Tech/Server Infrastructure/): - Server: FastAPI (Python), SQLite → PostgreSQL later, hosted on cheap VPS - Telescope control: ASCOM Alpaca (REST) or INDI - Scheduling: Astropy-based altitude/priority scorer, greedy handover - Data format: FITS files, WCS coordinates, photometry in magnitudes - Client polling: Sites poll /targets every ~60s, submit to /observations

Science case priority (from Value we bring.md): occultations > TTVs > microlensing > GRB/kilonova follow-up, because these require geographic distribution that no single telescope (including Rubin/LSST) can provide.