# qimingtian/pomfret-astro-website architecture

> Architecture diagram of the GitHub repository qimingtian/pomfret-astro-website, 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/qimingtian/pomfret-astro-website
- Repository: https://github.com/qimingtian/pomfret-astro-website

## Overview

Pomfret Astro is a multi-observatory platform for member imaging requests, weather-aware scheduling, and autonomous observatory operation. Members submit sessions through the Remote dashboard; the server stores requests, reconciles them against weather and target constraints, and delivers eligible NINA sequences to an on-site agent. The agent runs imaging and reports progress; the app tracks completion and exposes session files. Other major capabilities include site membership and administration, planning and astronomy tools, weather and sky-camera views, and member galleries. The graph follows README-documented flows and sampled route calls; unsampled subsystem wiring is omitted.

Main entry points: [`observatory/nina_agent.py`](https://github.com/qimingtian/pomfret-astro-website/blob/main/observatory/nina_agent.py) (Observatory agent), [`app/api/imaging/tonight-weather-prediction/route.ts`](https://github.com/qimingtian/pomfret-astro-website/blob/main/app/api/imaging/tonight-weather-prediction/route.ts) (Weather forecast API), [`app/api/imaging/nina-sequence/route.ts`](https://github.com/qimingtian/pomfret-astro-website/blob/main/app/api/imaging/nina-sequence/route.ts) (NINA sequence API), [`lib/imaging/queue/store.ts`](https://github.com/qimingtian/pomfret-astro-website/blob/main/lib/imaging/queue/store.ts) (Queue store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_member["Member access"]
  node_remote["Remote dashboard<br/>[remote-page.tsx]"]
  node_account["Member account<br/>[page.tsx]"]
  node_auth_api["Authentication API<br/>[route.ts]"]
  node_member_store[("Member store<br/>[member-store.ts]")]
  node_postgres[("Postgres")]
  node_admin["Admin tools<br/>[page.tsx]"]
  node_membership_api["Membership requests<br/>[route.ts]"]
end

subgraph group_planning["Planning and weather"]
  node_weather_gate["Weather gate"]
  node_weather_api["Weather forecast API<br/>[route.ts]"]
  node_weather_ui["Weather dashboard"]
  node_plan_ui["Plan workspace<br/>[plan-page.tsx]"]
  node_astro_tools["Target and sky tools"]
  node_camera_ui["Camera and sky views"]
end

subgraph group_imaging["Imaging operations"]
  node_queue_api["Imaging request API<br/>[route.ts]"]
  node_queue_store[("Queue store<br/>[store.ts]")]
  node_planner["Project planner<br/>[planner.ts]"]
  node_reconcile["Queue reconcile<br/>[reconcile.ts]"]
  node_agent_api["NINA sequence API<br/>[route.ts]"]
  node_progress_api["Progress webhook<br/>[route.ts]"]
  node_board[("Session board<br/>[board.ts]")]
end

subgraph group_operations["Observatory services"]
  node_agent["Observatory agent<br/>[nina_agent.py]"]
  node_nina["NINA and PDU"]
  node_redis[("Upstash Redis")]
  node_camera["All-sky camera<br/>[camera_service.py]"]
end

subgraph group_media["Media and results"]
  node_r2[("Cloudflare R2")]
  node_download_api["Session downloads<br/>[route.ts]"]
  node_gallery["Gallery submissions<br/>[route.ts]"]
end

node_member(("Member"))
node_external_weather(("Weather services"))

node_member -->|"uses"| node_remote
node_remote -->|"submits request"| node_queue_api
node_queue_api -->|"creates request"| node_queue_store
node_queue_api -->|"plans project"| node_planner
node_planner -->|"updates schedule"| node_queue_store
node_weather_ui -->|"requests forecast"| node_weather_api
node_weather_api -->|"fetches forecast"| node_external_weather
node_weather_api -->|"evaluates conditions"| node_weather_gate
node_weather_api -->|"may reconcile"| node_reconcile
node_plan_ui -->|"uses target data"| node_astro_tools
node_agent -->|"polls sequences"| node_agent_api
node_agent_api -->|"reads queued work"| node_queue_store
node_agent_api -->|"marks delivered"| node_board
node_agent_api -->|"returns sequence"| node_agent
node_agent -->|"runs sequence"| node_nina
node_agent -->|"reports progress"| node_progress_api
node_progress_api -->|"updates completion"| node_board
node_queue_store -->|"persists state"| node_redis
node_board -->|"persists state"| node_redis
node_agent -->|"uploads session files"| node_r2
node_account -->|"requests files"| node_download_api
node_download_api -->|"reads objects"| node_r2
node_member -->|"authenticates"| node_auth_api
node_auth_api -->|"verifies account"| node_member_store
node_member_store -->|"reads and writes"| node_postgres
node_admin -->|"manages requests"| node_membership_api
node_membership_api -->|"approves affiliation"| node_member_store
node_member -->|"submits work"| node_gallery
node_camera -->|"serves stream"| node_camera_ui

click node_remote "https://github.com/qimingtian/pomfret-astro-website/blob/main/components/remote/remote-page.tsx"
click node_queue_api "https://github.com/qimingtian/pomfret-astro-website/blob/main/app/api/imaging/queue/route.ts"
click node_queue_store "https://github.com/qimingtian/pomfret-astro-website/blob/main/lib/imaging/queue/store.ts"
click node_planner "https://github.com/qimingtian/pomfret-astro-website/blob/main/lib/imaging/project/planner.ts"
click node_reconcile "https://github.com/qimingtian/pomfret-astro-website/blob/main/lib/imaging/queue/reconcile.ts"
click node_weather_gate "https://github.com/qimingtian/pomfret-astro-website/blob/main/lib/tonight-weather-gate.ts"
click node_weather_api "https://github.com/qimingtian/pomfret-astro-website/blob/main/app/api/imaging/tonight-weather-prediction/route.ts"
click node_weather_ui "https://github.com/qimingtian/pomfret-astro-website/blob/main/components/weather/ObservatoryWeatherDashboard.tsx"
click node_plan_ui "https://github.com/qimingtian/pomfret-astro-website/blob/main/components/plan/plan-page.tsx"
click node_astro_tools "https://github.com/qimingtian/pomfret-astro-website/blob/main/lib/variable-star-catalog.ts"
click node_agent_api "https://github.com/qimingtian/pomfret-astro-website/blob/main/app/api/imaging/nina-sequence/route.ts"
click node_agent "https://github.com/qimingtian/pomfret-astro-website/blob/main/observatory/nina_agent.py"
click node_progress_api "https://github.com/qimingtian/pomfret-astro-website/blob/main/app/api/imaging/session-progress/route.ts"
click node_board "https://github.com/qimingtian/pomfret-astro-website/blob/main/lib/imaging/session/board.ts"
click node_download_api "https://github.com/qimingtian/pomfret-astro-website/blob/main/app/api/imaging/download/route.ts"
click node_account "https://github.com/qimingtian/pomfret-astro-website/blob/main/app/dashboard/account/page.tsx"
click node_auth_api "https://github.com/qimingtian/pomfret-astro-website/blob/main/app/api/auth/login/route.ts"
click node_member_store "https://github.com/qimingtian/pomfret-astro-website/blob/main/lib/member-store.ts"
click node_admin "https://github.com/qimingtian/pomfret-astro-website/blob/main/app/dashboard/admin/page.tsx"
click node_membership_api "https://github.com/qimingtian/pomfret-astro-website/blob/main/app/api/admin/imaging-requests/route.ts"
click node_gallery "https://github.com/qimingtian/pomfret-astro-website/blob/main/app/api/member/gallery-submissions/route.ts"
click node_camera "https://github.com/qimingtian/pomfret-astro-website/blob/main/observatory/camera_service.py"
click node_camera_ui "https://github.com/qimingtian/pomfret-astro-website/blob/main/components/AllSkyCameraView.tsx"

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_remote,node_account,node_auth_api,node_member_store,node_postgres,node_admin,node_membership_api toneBlue
class node_weather_gate,node_weather_api,node_weather_ui,node_plan_ui,node_astro_tools,node_camera_ui toneAmber
class node_queue_api,node_queue_store,node_planner,node_reconcile,node_agent_api,node_progress_api,node_board toneMint
class node_agent,node_nina,node_redis,node_camera toneRose
class node_r2,node_download_api,node_gallery,node_member,node_external_weather toneIndigo
```

## Components

### Member access

- [Remote dashboard](https://github.com/qimingtian/pomfret-astro-website/blob/main/components/remote/remote-page.tsx): `components/remote/remote-page.tsx`
- [Member account](https://github.com/qimingtian/pomfret-astro-website/blob/main/app/dashboard/account/page.tsx): `app/dashboard/account/page.tsx`
- [Authentication API](https://github.com/qimingtian/pomfret-astro-website/blob/main/app/api/auth/login/route.ts): `app/api/auth/login/route.ts`
- [Member store](https://github.com/qimingtian/pomfret-astro-website/blob/main/lib/member-store.ts): `lib/member-store.ts`
- **Postgres**
- [Admin tools](https://github.com/qimingtian/pomfret-astro-website/blob/main/app/dashboard/admin/page.tsx): `app/dashboard/admin/page.tsx`
- [Membership requests](https://github.com/qimingtian/pomfret-astro-website/blob/main/app/api/admin/imaging-requests/route.ts): `app/api/admin/imaging-requests/route.ts`

### Planning and weather

- [Weather gate](https://github.com/qimingtian/pomfret-astro-website/blob/main/lib/tonight-weather-gate.ts): `lib/tonight-weather-gate.ts`
- [Weather forecast API](https://github.com/qimingtian/pomfret-astro-website/blob/main/app/api/imaging/tonight-weather-prediction/route.ts): `app/api/imaging/tonight-weather-prediction/route.ts`
- [Weather dashboard](https://github.com/qimingtian/pomfret-astro-website/blob/main/components/weather/ObservatoryWeatherDashboard.tsx): `components/weather/ObservatoryWeatherDashboard.tsx`
- [Plan workspace](https://github.com/qimingtian/pomfret-astro-website/blob/main/components/plan/plan-page.tsx): `components/plan/plan-page.tsx`
- [Target and sky tools](https://github.com/qimingtian/pomfret-astro-website/blob/main/lib/variable-star-catalog.ts): `lib/variable-star-catalog.ts`
- [Camera and sky views](https://github.com/qimingtian/pomfret-astro-website/blob/main/components/AllSkyCameraView.tsx): `components/AllSkyCameraView.tsx`

### Imaging operations

- [Imaging request API](https://github.com/qimingtian/pomfret-astro-website/blob/main/app/api/imaging/queue/route.ts): `app/api/imaging/queue/route.ts`
- [Queue store](https://github.com/qimingtian/pomfret-astro-website/blob/main/lib/imaging/queue/store.ts): `lib/imaging/queue/store.ts`
- [Project planner](https://github.com/qimingtian/pomfret-astro-website/blob/main/lib/imaging/project/planner.ts): `lib/imaging/project/planner.ts`
- [Queue reconcile](https://github.com/qimingtian/pomfret-astro-website/blob/main/lib/imaging/queue/reconcile.ts): `lib/imaging/queue/reconcile.ts`
- [NINA sequence API](https://github.com/qimingtian/pomfret-astro-website/blob/main/app/api/imaging/nina-sequence/route.ts): `app/api/imaging/nina-sequence/route.ts`
- [Progress webhook](https://github.com/qimingtian/pomfret-astro-website/blob/main/app/api/imaging/session-progress/route.ts): `app/api/imaging/session-progress/route.ts`
- [Session board](https://github.com/qimingtian/pomfret-astro-website/blob/main/lib/imaging/session/board.ts): `lib/imaging/session/board.ts`

### Observatory services

- [Observatory agent](https://github.com/qimingtian/pomfret-astro-website/blob/main/observatory/nina_agent.py): `observatory/nina_agent.py`
- **NINA and PDU**
- **Upstash Redis**
- [All-sky camera](https://github.com/qimingtian/pomfret-astro-website/blob/main/observatory/camera_service.py): `observatory/camera_service.py`

### Media and results

- **Cloudflare R2**
- [Session downloads](https://github.com/qimingtian/pomfret-astro-website/blob/main/app/api/imaging/download/route.ts): `app/api/imaging/download/route.ts`
- [Gallery submissions](https://github.com/qimingtian/pomfret-astro-website/blob/main/app/api/member/gallery-submissions/route.ts): `app/api/member/gallery-submissions/route.ts`

### Other components

- **Member**
- **Weather services**

## Connections

- Member → Remote dashboard: uses
- Remote dashboard → Imaging request API: submits request
- Imaging request API → Queue store: creates request
- Imaging request API → Project planner: plans project
- Project planner → Queue store: updates schedule
- Weather dashboard → Weather forecast API: requests forecast
- Weather forecast API → Weather services: fetches forecast
- Weather forecast API → Weather gate: evaluates conditions
- Weather forecast API → Queue reconcile: may reconcile
- Plan workspace → Target and sky tools: uses target data
- Observatory agent → NINA sequence API: polls sequences
- NINA sequence API → Queue store: reads queued work
- NINA sequence API → Session board: marks delivered
- NINA sequence API → Observatory agent: returns sequence
- Observatory agent → NINA and PDU: runs sequence
- Observatory agent → Progress webhook: reports progress
- Progress webhook → Session board: updates completion
- Queue store → Upstash Redis: persists state
- Session board → Upstash Redis: persists state
- Observatory agent → Cloudflare R2: uploads session files
- Member account → Session downloads: requests files
- Session downloads → Cloudflare R2: reads objects
- Member → Authentication API: authenticates
- Authentication API → Member store: verifies account
- Member store → Postgres: reads and writes
- Admin tools → Membership requests: manages requests
- Membership requests → Member store: approves affiliation
- Member → Gallery submissions: submits work
- All-sky camera → Camera and sky views: serves stream