astrolabe/docs/spec/00-product-overview.md

# 00 · Product Overview

This document set is a UX/behavioral specification for **Astrolabe**, a browser-based snippet manager for [Vega-Lite](https://vega.github.io/vega-lite/) visualizations. It describes _what the app does_ from the user's perspective — its capabilities, workflows, and structural layout — so the app can be recreated on any web/HTML/TS stack. It deliberately avoids prescribing _how_ anything is built: no frameworks, libraries, storage technologies, code structure, or concrete visual styling are mandated. Implementers are free to choose those.

## What Astrolabe Is

Astrolabe is a local-first tool for authoring, organizing, and previewing Vega-Lite charts. A user keeps a personal library of **snippets** (saved chart specifications), edits each one as JSON with live validation, and sees the result render in real time beside the editor. Reusable **datasets** can be stored once and referenced by many snippets. Everything lives in the user's browser — there is no account, no server, and no network dependency after first load.

## Who It Is For

People who work with Vega-Lite directly and want a fast, private workspace to draft, iterate on, and keep many visualizations: data practitioners, analysts, educators, and chart authors. Familiarity with Vega-Lite's JSON spec format is assumed; the app does not abstract Vega-Lite away (though the _Chart Builder_ offers a no-JSON starting point).

## Core Value

- **Iterate quickly** — edit JSON and watch the chart update live, with schema-aware assistance and instant error feedback.
- **Stay organized** — a searchable, sortable library of named, annotated snippets.
- **Experiment safely** — a draft/published model lets users tinker without losing a known-good version.
- **Reuse data** — datasets stored once, referenced anywhere, in multiple formats and from inline data or remote URLs.
- **Own your data** — fully local, private, and offline-capable, with import/export for backup and transfer.

## Scope & Principles

- **Local-first** — all data is stored in the browser and survives reload; the app works fully offline and is installable as a standalone app.
- **Single-screen workspace** — a three-pane layout (library · editor · preview) plus modals for cross-cutting tools (datasets, chart builder, settings, help).
- **Vega-Lite native** — snippets _are_ Vega-Lite specs; the app validates, renders, and reasons about them as such.
- **Keyboard-friendly and shareable** — common actions have shortcuts, and the current location is reflected in a shareable URL.

## Non-Goals

- No user accounts, authentication, or cross-device sync (use _Import & Export_ to move data).
- No server-side storage, rendering, or processing.
- No collaboration or multi-user features.
- No general BI/dashboarding — a snippet is a single Vega-Lite visualization, not a composed report.

## Key Concepts (Glossary)

- **Snippet** — a saved Vega-Lite specification plus metadata (name, comment, timestamps, tags, dataset references). The primary user-authored entity. See _Snippet Library_ and _Data Model & Persistence_.
- **Spec** — the Vega-Lite JSON specification that defines one visualization.
- **Draft vs Published** — each snippet holds a stable **published** spec and an editable **draft**; edits affect only the draft until the user publishes. See _Spec Editor & Draft/Published Workflow_.
- **Dataset** — a named, reusable data source (JSON/CSV/TSV/TopoJSON; inline or URL) that snippets reference by name. See _Datasets_.
- **Dataset reference** — a Vega-Lite named-data reference, e.g. `{ "data": { "name": "MyDataset" } }`, linking a spec to a stored dataset.
- **Live preview** — the rendered chart, updated automatically as the spec changes. See _Live Preview_.

## How This Specification Is Organized

| #   | Section                                | Covers                                                                                     |
| --- | -------------------------------------- | ------------------------------------------------------------------------------------------ |
| 00  | Product Overview                       | This document — purpose, scope, glossary.                                                  |
| 01  | Application Shell & Navigation         | Layout, panes, header, modals, keyboard shortcuts, URL state, toasts, offline/installable. |
| 02  | Snippet Library                        | Browsing, search, sort, metadata, create/duplicate/delete, storage monitor.                |
| 03  | Spec Editor & Draft/Published Workflow | Editing, auto-save, auto-render, draft/publish/revert, extract-to-dataset.                 |
| 04  | Live Preview                           | Rendering, reference resolution, fit modes, error display.                                 |
| 05  | Datasets                               | Dataset manager, formats, sources, profiling, references, linking.                         |
| 06  | Chart Builder                          | Visual no-JSON chart composition from a dataset.                                           |
| 07  | Settings                               | Appearance, editor, performance, and formatting preferences.                               |
| 08  | Import & Export                        | Backup/transfer file format, import normalization and merging.                             |
| 09  | Data Model & Persistence               | Entity field definitions, storage tiers, relationships.                                    |
| 10  | Non-Functional Requirements            | Platform, performance, accessibility, reliability, privacy.                                |

Read 00 first for orientation, then any section independently. Sections cross-reference one another by title where behavior spans more than one area.