5.3 KiB
Astrolabe — What This Project Is About
The Problem
People who work with Vega-Lite directly — analysts, educators, chart authors — don't have a fast, private place to keep their charts. The official Vega-Lite editor is great for a single spec in a tab, but it forgets everything when you close it. Notebooks bury charts in code. BI tools hide the spec behind a GUI and lock you into an account.
Astrolabe fills this gap: a local-first workspace where you author Vega-Lite specs as JSON, see them render live, and keep a personal, searchable library of them — with no account, no server, and full offline use.
The Core Idea
The central artifact is the snippet: a saved Vega-Lite specification plus metadata. Everything else — the editor, the live preview, the dataset library, the chart builder — exists to author, organize, and reuse snippets. Astrolabe does not abstract Vega-Lite away; a snippet is a Vega-Lite spec. The chart builder offers a no-JSON on-ramp, but the JSON is always the source of truth and always editable.
Reusable datasets are stored once and referenced by name from many snippets, so the data lives in one place and the specs stay lean.
Core Values
1. Local-Only by Default
Everything runs in the browser. Snippets, datasets, and settings never leave the machine. No accounts, no uploads, no tracking, and the app contacts no third party on its own — including an AI model. The only outbound requests are user-created URL-dataset fetches. Because your work stays on the machine, confidential and work data are safe in Astrolabe from the first chart.
2. Vega-Lite Native, Not Vega-Lite Hidden
The product domain is Vega-Lite. We validate, render, and reason about specs as Vega-Lite, and we surface its real vocabulary (marks, encodings, field types). We don't invent a parallel chart abstraction. The chart builder is an on-ramp, not a replacement for the spec.
3. Experiment Safely
A snippet carries a stable published spec and an editable draft. You can tinker freely without losing a known-good version. Auto-save protects in-progress work; publish promotes it deliberately.
4. Beginner On-Ramp, Power-User Ceiling
The chart builder lets someone produce a chart without writing JSON. The editor — with schema-aware autocomplete and live validation — lets a power user do anything Vega-Lite can. Neither caps the other.
5. Own Your Data
Fully local and offline-capable, with import/export for backup and transfer. Your library is a file you control, not a row in someone's database.
6. Predictable, Not Clever
When a behavior could go several ways, pick the one closest to the user's existing mental model (the Vega-Lite editor, JSON tooling, file-based apps). Least surprise beats most clever.
What We're Not
- Not a BI/dashboarding tool. A snippet is one visualization, not a composed report with cross-filters and layout. Dashboards are a different product.
- Not a data-wrangling tool. Datasets are stored and referenced, not cleaned or transformed. (That's Syto territory — Astrolabe's sibling in architecture and quality bar, but a separate product with separate goals.)
- Not a collaboration platform. No multi-user, no sync, no comments. Import/export moves data between machines.
- Not a server app. No backend, no rendering service, no account system.
- Not an AI tool. No model authors, edits, or critiques charts, and nothing is sent to one. The chart builder's recommendations are deterministic and rule-based, computed locally — chosen over an LLM so results are explainable and nothing leaves the machine.
Technical Philosophy
Spec-Recorded, Clean Implementation
The behavioral record lives in docs/spec/. Astrolabe is a deliberate rebuild on a
robust architecture (adapted from Syto): behavior is designed deliberately and recorded
in the spec, not ported from old code. The code leads; the spec is rewritten to match
what ships — never silent drift.
Portable Core, Thin Browser Shell
src/core/ is pure and portable — no browser APIs, no UI framework. Spec operations
(detection, profiling, reference resolution, fit transforms, validation, import
normalization) live there and are tested hardest. The UI is a thin, replaceable shell over
that core.
Leverage Existing Libraries
Vega-Lite renders. Monaco edits. vega-embed mounts charts. React + Zustand drive the UI. We wrap these with thin integration layers rather than reinventing them. Custom code focuses on what's unique to Astrolabe: the snippet/dataset model, the rendering contract, and the workspace that ties it together.
No Parallel Systems
Each fact lives in one place. A snippet↔dataset link, a setting, a schema — one source of truth, others derived. If you're writing the same logic twice, one should import or be generated from the other.
Test the Core, Trust the UI
High coverage on the portable engine (where a bug corrupts data or breaks rendering); lighter coverage on components (where a bug is a cosmetic annoyance).
The Name
An astrolabe is an ancient instrument for locating and predicting the positions of stars — a tool for finding your way by the sky. The app helps you find your way through a library of visualizations: keep them, locate them, and see where each one points.