Files
Paul HittandClaude Opus 5 3915e879cd feat(research): add the Pipeline page
Every other reduction surface answers a question about one frame. The
question an operator actually wakes up with is "did last night get
processed", and answering it meant opening frames one at a time until
you found the broken one.

The failure this is really built for is the quiet one. The sidecar runs
in its own container; when it stops claiming, every job stays pending,
no error is ever written, and a stalled queue looks exactly like a busy
one in the counts. So the page leads with which workers have claimed and
when, checked per side: a healthy local Node worker says nothing about a
dead sidecar, and the warning names the side that stopped along with the
number of jobs waiting on it.

Below that, the stages in dependency order with their counts and the age
of the oldest waiting job (ten jobs a minute old is a healthy queue, one
job from last Tuesday is a broken one), then the failures with the error
the worker reported and a batch retry.

Server side, GET /reduction/queue grew from bare counts into the whole
payload, and POST /reduction/retry requeues up to 100 frames under one
click, authorizing each frame individually and reporting what it
refused rather than failing the batch.

Two bugs found while verifying against a live queue rather than a
fixture:

- The failure scope SQL checked site_members but not site ownership. A
  site's owner has no site_members row, so the list hid an operator's
  own failures on their own telescope, which is the single case the page
  exists for.
- A retried frame never left the list. Reprocessing creates a new run
  and keeps the old one, which is the provenance model working, but the
  old failed rows stay in the table. Failures are now scoped to each
  frame's current run, so acting on one clears it while the history
  stays intact.

Verified against an isolated stack seeded with a real mix: one stage
done, two frames failed on different stages with real errors, five
sidecar jobs waiting, and a worker whose last claim was 40 minutes old.
The page named the stalled sidecar rather than the failures, the batch
retry reported "Queued 2 frames", the superseded failures dropped off,
and the new run's genuine ENOENT failures took their place.

Research is now full at three items, which the nav invariant tests
enforce. DESIGN.md says what each of the three answers and that anything
else has to displace one of them.

253 server tests, 22 client tests.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-12 16:49:55 -04:00

9.5 KiB

Caelum Design System

Source of truth for all visual + IA decisions. Read this before any UI change. Do not deviate without explicit user approval.

Product

Caelum is a shared observatory network: publish telescope time, run live imaging sessions, coordinate with federated operators, and share an imaging archive. Ships with Nox, a typed DSL for telescope/dome control.

Users are observatory operators and astronomers. The UI is a dark, data-dense control surface that favors information density over whitespace. Operators want to see state at a glance, not scroll.

Information architecture

Navigation follows the lifecycle of a night, top to bottom, the same arc the landing page tells. Read the sidebar as a story, not a taxonomy: your telescope goes on the network → people book it → it runs live → the data lands → all inside a community. Sidebar order is fixed and is the narrative.

Workspace Pages Lifecycle beat
Tonight Dashboard, Inbox What needs you right now
Your Observatory Sites, Hardware The gear you operate
Get Time Schedule, Discover, Proposals Acquiring time, yours or someone else's
Prepare Targets, Observation Plans, Nox Console Deciding and scripting what to observe
Archive Archive, SpaceDB The data that lands, and the catalog to compare it to
Research Analysis, Calibration, Pipeline Turning those frames into measurements
Community Activity, Leaderboard, Messages The people around it
Gear Shop, Shop Catalog The store. An appendix, below the arc

Two rules keep the rail legible, and both were broken before:

No group exceeds three items. "Plan & Book" had six. They split cleanly into acquiring time and preparing a run, which are different jobs on different days.

A page sits with the question it answers, not the data it touches. Inbox answers "what needs me?", so it belongs in Tonight, not Community. Activity is the network firehose, so it belongs in Community, not Tonight. The store answers neither, so it sits below the arc entirely rather than inside "Your Observatory", where it also put an admin CRUD page next to user-facing ones.

The same rule put Calibration in Research rather than Archive. Archive answers "what did we take?"; Calibration answers "can these frames be trusted?", which is science work. Research sits after Archive because a measurement needs frames before it can exist.

Research is now full at three, and the three answer different questions. Analysis asks whether a target can be measured yet. Calibration asks whether the frames can be trusted. Pipeline asks whether the processing is running at all, which is the operational question underneath both. Anything else that wants to live here has to displace one of them.

No icons in the rail. The rail is 240px and the labels carry it. A mixed set of emoji and geometric glyphs read as unfinished and told the reader nothing the label did not. The command palette is text-only for the same reason: its group column already says what kind of result a row is.

/research is labelled Targets. The page answers "what is worth observing tonight"; analysing data you already have is the archive's job, and one word cannot carry both. The route keeps its path so existing links survive.

Live sessions render as a dynamic group above the workspaces while active. That is the "Run" beat, given top billing for as long as it lasts. Quick-jump (⌘K) searches both destinations and remote entities.

Rule: a page belongs to exactly one workspace, and the workspace answers "which stage of the night is this?". If a concept spans two, the surfaces co-locate inside one page (e.g. "My Bookings" and "Schedule" are the same page, not two nav items). That is what kills the "scheduled here but not there" confusion.

One home per surface. A given kind of thing has a single canonical page: the network activity firehose lives on Activity (not also as an Archive tab); "needs your attention" (notifications + booking approvals + your outstanding requests) lives on Inbox; the schedule is the one home for upcoming sessions. Other pages may link to these, but do not re-implement them.

Color

Defined as CSS variables in client/src/assets/style.css :root. Never hard-code hex in a component.

Token Value Use
--bg-primary #0f172a App background
--bg-secondary #1e293b Sidebar, modals
--bg-card #1e293b Cards
--bg-input #334155 Inputs, row hover
--border #334155 All borders
--text-primary #f1f5f9 Headings, primary text
--text-secondary #94a3b8 Body, table cells
--text-muted #64748b Labels, captions
--accent #38bdf8 Primary action, links, scheduled
--success #4ade80 Live, online, confirmed
--warning #fbbf24 Pending, idle
--danger #f87171 Error, cancelled, offline-critical

Lifecycle state semantics (single source of truth)

The API returns session_state (live | scheduled | completed | raw status). Bind it directly to the pill component. Never re-derive state in a view, and never invent a fourth color:

<span class="pill" :class="'pill-' + s.session_state">{{ s.session_state }}</span>
State Token Color
live --state-live green (pulsing dot)
scheduled / confirmed --state-scheduled accent blue
completed --state-completed muted gray
pending --state-pending warning amber
cancelled / error --state-error danger red
offline --state-offline muted gray

Reduction jobs use the same .pill component with a second vocabulary, because a reduction stage's states have no session equivalent: skipped means correctly not needed, and blocked means the stage is fine but is waiting on a failure above it.

Job status Reuses Colour
done --state-live green
running --state-scheduled accent blue
pending --state-pending warning amber
blocked --state-pending warning amber
skipped --state-completed muted gray
failed --state-error danger red

A frame's own reduction_state adds raw, queued, reducing, reduced and partial, mapped onto the same set. No new colours were introduced: the app still has exactly six status colours.

This guarantees a session looks identical on Schedule, Proposal, Feed and Dashboard. Status inconsistency was the #1 reported UX problem; it is now a presentation-layer invariant.

Spacing scale

Use tokens only. No ad-hoc 0.625rem / 0.35rem in views.

--space-1 .25rem · --space-2 .5rem · --space-3 .75rem · --space-4 1rem · --space-5 1.5rem · --space-6 2rem

  • Card padding: --space-5
  • Page header bottom margin: --space-6
  • Between stacked sections: .section + .section → --space-6
  • Grid gap: --space-4

Type scale

All sizes in rem via tokens. Font: system stack (air-gap safe, no CDN).

--text-xs .75 · --text-sm .85 · --text-base .9 · --text-md 1 · --text-lg 1.1 · --text-xl 1.75 · --text-2xl 2

  • Page title (.page-header h1/h2): --text-xl, weight 700
  • Section title (.section-title): --text-lg, weight 600
  • Card header (.card-header h3): --text-lg, weight 600
  • Body: --text-base
  • Labels / table headers: --text-xs uppercase, --text-muted
  • Stat value: --text-2xl, weight 700

Components

One pattern per concern. Don't hand-roll a second variant in a view.

  • Page shell: .page-header (title block + right-aligned actions slot) inside .page-container (max 1200px, centered), provided by App.vue.
  • Card: .card. Header row: .card-header + <h3>. Stack with .card + .card.
  • Stat strip: .stat-card with .label + .value, laid out in .grid .grid-3 / .grid-2.
  • Table: .data-table. Numeric columns get .num (right-aligned, tabular figures). Don't style raw <table>.
  • State pill: .pill + .pill-<state> (see lifecycle table). The only status component. .badge-* is legacy: migrate on touch, don't add new.
  • Buttons: .btn + .btn-primary / -secondary / -danger / -ghost, .btn-sm for dense rows. Hover color is pinned (RouterLink renders <a>; global a:hover would otherwise eat the label).
  • Forms: .form-group (label + .form-control), .form-row for 2-up.
  • Modal: .modal-overlay > .modal, actions in .modal-actions.
  • Empty state: .empty-state inside a .card.

Grid

.grid-2 = exactly 2 cols, .grid-3 = exactly 3 (→ 2 at ≤1024px, 1 at ≤768px). Uses minmax(0,1fr) so cards shrink instead of overflowing. Never use auto-fill/auto-fit (it silently rendered 3 cramped columns in a 2-col grid and wrapped titles mid-word).

Density rules

  • Tables: compact rows (--space-3 padding), no zebra striping, hover only.
  • Headers: roomy (--space-6 below page header).
  • Lists of entities: prefer table over card grid past ~6 rows.
  • Calendar/sky-viewer keep their specialized treatments.

Responsive

  • ≤768px: sidebar hidden, content full-width, grids collapse to 1 col, form rows stack.
  • Sidebar is a fixed 240px rail; content has margin-left:240px.
  • Nox IDE opts into full width via .main-content-wide.

Non-negotiables

  1. Read this file before any visual change. In QA, flag deviations.
  2. No hard-coded colors, spacing, or font sizes. Tokens only.
  3. One component per concern; migrate legacy on touch, never fork.
  4. Lifecycle state = API session_state → .pill. Never re-derive.
  5. A page lives in exactly one workspace.