Astro Brain

AstroBrain is an AI copilot for deep-sky astrophotographers. It combines your real equipment, location, horizon, weather, moon, and targets to recommend best nights to image and explain its reasoning.

Comment

AstroBrain

AstroBrain helps deep-sky astrophotographers decide what to image, when to image it, and whether it fits the equipment they own.

Inspiration

I built AstroBrain from a frustration I know well: a clear night arrives, yet planning it means jumping between a target catalog, weather forecast, Moon chart, framing calculator, capture software, and a spreadsheet. Each tool gives one piece of the answer. The photographer still has to connect everything by hand.

AstroBrain started with one question:

With my rig, my observing site, my horizon, my targets, tonight's weather, and the Moon, what should I image—and why?

I did not want another generic target list. I wanted an answer based on the observer's real telescope, camera, location, horizon, and sky. I also wanted every recommendation to explain itself. A score is useful only when the photographer can see what improved it, what reduced it, and which inputs are missing.

What AstroBrain does

AstroBrain brings equipment, location, horizon, target visibility, Moon conditions, weather, framing, and saved plans into one web application.

A user can:

  • Build and save an imaging rig
  • Enter an observing location and upload a custom horizon
  • Search a deep-sky object catalog
  • Explore targets in an interactive sky atlas
  • Inspect altitude, rise, transit, set, twilight, and Moon separation
  • Compare a target across the next 14 nights
  • Preview the target through the selected telescope and camera
  • Rotate the camera frame and compare compositions
  • Save targets and build a persistent session plan
  • Try the main workflow without creating an account

A saved plan preserves the rig, location, horizon, target, weather, and scoring context behind the decision. Changing equipment later does not rewrite an earlier session.

How the planning model works

AstroBrain calculates a deterministic score from named components, including altitude window, observable hours, Moon separation, framing fit, cloud forecast, light-pollution context, and the user's preferences.

For components with valid data, the normalized score is:

$$ S = 100 \times \frac{\sum_{i \in A} w_i c_i}{\sum_{i \in A} w_i} $$

Here, (A) is the set of available components, (w_i) is the weight of each component, and (c_i) is a normalized value between (0) and (1).

The result includes component values, reason codes, confidence penalties, assumptions, source provenance, missing inputs, and the scoring model version. AstroBrain does not hide stale weather or missing target dimensions behind invented defaults. It lowers confidence and explains why.

How I built it

AstroBrain is a TypeScript application built with Next.js and React. I designed it as a modular monolith with separate domain services for equipment, locations, catalog search, ephemeris calculations, weather, scoring, framing, and planning sessions.

The main technical components are:

  • Astronomy Engine for celestial positions, altitude, twilight, and Moon geometry
  • PostgreSQL and Drizzle ORM for equipment, locations, targets, model versions, and planning snapshots
  • Aladin Lite for the interactive sky atlas
  • Open-Meteo for weather data with freshness and provenance
  • WorkOS AuthKit for optional accounts
  • Cloudflare Workers and OpenNext for deployment
  • Neon PostgreSQL through Cloudflare Hyperdrive for production persistence
  • Cloudflare R2 for catalog imagery
  • Vitest, static checks, build verification, and browser smoke tests for validation

Business rules stay outside React components. The interface asks domain services for calculations, keeping the astronomy and planning logic testable. Historical plans use immutable snapshots, so later equipment or location edits cannot change an earlier decision.

How I used OpenAI Codex

OpenAI Codex was part of how I built AstroBrain, but it is not a hidden input to the astronomy score.

I used Codex to research integrations, turn product ideas into specifications, implement focused tasks, write tests, inspect browser behavior, and review changes for regressions and edge cases.

The repository holds the project's memory. Requirements live in feature specifications, architecture decisions live in Architecture Decision Records, and completed work includes validation evidence. This gave Codex stable context across development sessions.

AstroBrain's recommendations remain deterministic. AI does not invent weather, alter target coordinates, or quietly change a score.

Challenges I faced

Combining data with different lifetimes

Target coordinates are stable. Weather expires quickly. Equipment and horizon profiles may change between sessions. I handled this with timestamps, provenance labels, versioned records, and immutable planning snapshots.

Making recommendations explainable

Generating a number was easy. Generating a result someone could trust and inspect later was harder. Every score needed named components, stable reason codes, confidence penalties, assumptions, and a model version. Rejected targets also needed an explanation instead of silently disappearing.

Handling incomplete data

Catalog objects may lack angular dimensions. A rig may be missing sensor details. Weather may be stale or unavailable. AstroBrain shows these gaps and explains their effect on confidence rather than pretending the data is complete.

Integrating the sky atlas

Aladin Lite depends on browser APIs, WebGL, and WebAssembly, while AstroBrain uses server rendering and deploys to Cloudflare Workers. I placed the viewer behind a client-only adapter. Search, visibility, and field-of-view logic remain independently testable, while Cloudflare builds and browser smoke tests validate the integration boundary.

Preserving anonymous work

I wanted people to experience AstroBrain before creating an account. That required a safe migration path for locally created rigs, locations, targets, and plans. The workflow previews what will move and keeps the local copy until the server confirms the transfer.

What I learned

Accurate astronomy math is essential, but trust also depends on timestamps, provenance, model versions, and visible assumptions. A recommendation becomes useful when the photographer can question it.

I learned that planning history must be part of the data model from the beginning. Without immutable snapshots, a saved session eventually stops describing the original decision.

I also learned that AI-assisted engineering needs clear boundaries. Codex performed best when requirements were documented, tasks were focused, tests were repeatable, and a separate review challenged the implementation.

What is next

The next step is to connect plans with completed-session results, including achieved integration time and image-quality notes. I also plan to add a source-grounded planning copilot after its provider, privacy, retention, and evaluation rules are approved. It will explain retrieved AstroBrain data and suggest actions, while deterministic services remain responsible for astronomy calculations and scoring.

Built With

Share this project:

Updates