mirror of
https://github.com/olehomelchenko/astrolabe.git
synced 2026-08-08 02:02:33 +00:00
oleh
094e5f6e4e
Defines the visual contract before the design-application work, so M2+ build on settled tokens. - docs/architecture/09-visual-design.md: principles + deliberate divergences (square chrome, free color/theming), token system (IBM Plex type, 8px spacing, role-based color, motion), component conventions, and a source-repo map for extending the research - docs/architecture/visual-specimen.html: standalone kitchen-sink specimen with a live theme x accent switcher; doubles as the tokens.css sandbox - IMPLEMENTATION-PLAN: new M1.5 'Visual design foundation' milestone, plus ground-rule/cross-cutting/reference wiring - index links: 00-overview, CLAUDE.md, AGENTS.md (architecture playbook now 00-09) Applying the design to the M1 surfaces is deferred to a separate session.
52 lines
4.3 KiB
Markdown
52 lines
4.3 KiB
Markdown
# Astrolabe — Architecture Playbook
|
|
|
|
> These documents capture the **architectural patterns** Astrolabe is built on. They are
|
|
> self-contained: everything needed to implement a pattern lives here, in Astrolabe's own
|
|
> domain terms (snippets, datasets, settings, Vega-Lite specs). You do not need any other
|
|
> repository to work from them.
|
|
>
|
|
> They are the architectural counterpart to [`docs/spec/`](../spec/): the **spec** says
|
|
> *what the app does* (behavior, acceptance points); this **playbook** says *how we build
|
|
> it* (state, persistence, modals, routing, rendering, inference, relationships).
|
|
|
|
## How to use this playbook
|
|
|
|
- Building a feature? Read the relevant spec section first (the *what*), then the matching
|
|
playbook doc (the *how*), then implement core-first per [`../IMPLEMENTATION-PLAN.md`](../IMPLEMENTATION-PLAN.md).
|
|
- Each doc states the pattern, the **rationale** (what problem it solves, what it prevents),
|
|
TypeScript sketches in Astrolabe terms, and Do/Don't rules.
|
|
- The sketches are *illustrative*, not finished code. Adapt them; keep the principles.
|
|
|
|
## The documents
|
|
|
|
| # | Doc | Covers |
|
|
|---|-----|--------|
|
|
| 01 | [State & Stores](01-state-and-stores.md) | Zustand stores; one source of truth; selector derivations; central `useAppStore` vs per-feature stores; testable action functions; debounced auto-save. |
|
|
| 02 | [Persistence](02-persistence.md) | The infrastructure-adapter boundary; promise-wrapped IndexedDB wrapper; lazy data loading; per-record schema versioning + migration; localStorage prefs with fallback; storage tiers + quota monitoring. |
|
|
| 03 | [Modal System](03-modal-system.md) | Registry + coordinator + shell; one modal at a time; unsaved-change detection via snapshot; focus trap; backdrop/Escape/close dismissal. |
|
|
| 04 | [Routing & Events](04-routing-and-events.md) | URL hash as view-state (restore/sync, Back/Forward); global keyboard routing; Escape priority chain; the single-source `isInInteractiveContext()` helper (Monaco-aware). |
|
|
| 05 | [Rendering, Theming & Preview](05-rendering-theming-preview.md) | vega-embed integration (`actions:false`, `view.finalize()`); field-name escaping; theme→config mapping; debounced non-blocking renderer; resilient error display. |
|
|
| 06 | [Type Inference & Profiling](06-type-inference.md) | Pure, portable column-type inference (number/text/date/boolean) and the dataset profile shape. |
|
|
| 07 | [Naming & Relationships](07-naming-and-relationships.md) | Unique-name enforcement + import auto-suffix; the bidirectional snippet↔dataset name link; rename propagation into specs. |
|
|
| 08 | [vega/editor Techniques](08-vega-editor-techniques.md) | Reference brief: borrowable Monaco-schema wiring, vega-embed lifecycle, two-tier validation, and data-flow/debounce techniques distilled from the official Vega-Lite editor — plus where we do better. |
|
|
| 09 | [Visual Design Language](09-visual-design.md) | The *visual* contract: principles inspired by IBM/Carbon, deliberate divergences (square chrome, free color/theming), the token system (Plex type, 8px spacing, role-based color, motion), component conventions, and where to mine the Carbon/IBM source repos for more. Companion: [`visual-specimen.html`](visual-specimen.html). |
|
|
|
|
## The non-negotiable layering (every doc assumes this)
|
|
|
|
- **`src/core/`** — portable, pure logic. No browser APIs, no React, no Monaco. Spec
|
|
operations live here and are unit-tested hardest. (Docs 06, 07, parts of 05 land here.)
|
|
- **`src/app/stores/`** — Zustand stores. (Doc 01.)
|
|
- **`src/app/infrastructure/`** — the *only* place that touches `indexedDB`, `localStorage`,
|
|
or `window.location`. Everything else goes through these typed adapters. (Docs 02, 04.)
|
|
- **`src/app/services/` & `orchestration/`** — coordination that composes stores +
|
|
infrastructure + core (lifecycle, routing sync, dependency upkeep). (Docs 03, 04, 07.)
|
|
- **`src/app/components/`** — React + CSS Modules. Thin; pushes logic down into stores/core
|
|
so it stays testable. (Docs 03, 05.)
|
|
|
|
## Why a playbook at all
|
|
|
|
Patterns written down once, in one place, stop two classes of problem: drift (the same
|
|
decision re-litigated inconsistently across features) and rediscovery (re-deriving why
|
|
something is the way it is). When a pattern here proves wrong, change the doc — don't fork
|
|
the convention silently. This is the same discipline `docs/spec/` applies to behavior.
|