Initial scaffold: spec, architecture playbook, and M0 skeleton

2026-08-08 02:02:33 +00:00 · 2026-06-04 22:14:33 +03:00
commit 056644450c
51 changed files with 13754 additions and 0 deletions
@@ -0,0 +1,60 @@
+# 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.