CLAUDE.md

Instructions for Claude Code when working on this project.

Project Overview

Astrolabe is a lightweight, browser-based snippet manager for Vega-Lite visualizations. Pure vanilla JavaScript, no build tools, retro Windows 2000 aesthetic.

Architecture

Frontend-only: HTML/CSS/JavaScript with CDN dependencies (Monaco Editor, Vega-Embed)
Storage:
- Snippets: localStorage (id, name, created, modified, spec, draftSpec, comment, tags, datasetRefs, meta)
- Datasets: IndexedDB (unlimited size, multi-format: JSON/CSV/TSV/TopoJSON, inline & URL sources)
Structure: Three resizable panels (snippet library, Monaco editor, live preview) + Dataset Manager modal
Deployment: Root folder contains index.html and all app files; /project-docs folder contains development documentation
No build tools: Open index.html directly in browser (needs local server for service worker and IndexedDB)

Current Status

Version: 0.3.0 (Alpha - pre-1.0 development) Deployment: Live at astrolabe-viz.com Mode: Alpha testing and iterative improvements

Core Capabilities

Snippet management with draft/published workflow
Dataset library (IndexedDB) with multi-format support (JSON, CSV, TSV, TopoJSON)
Dataset reference resolution in Vega-Lite specs
Progressive Web App with offline functionality and installability
User settings and theme system (Light, Dark Experimental)
Import/export functionality for snippets and datasets
Real-time search and multi-field sorting
Cross-platform keyboard shortcuts
Toast notification system
Storage monitoring with visual warnings
URL state management (shareable links, browser navigation)
Bidirectional snippet ↔ dataset linking
Table preview with type detection
Extract inline data to datasets

See project-docs/architecture.md for complete technical details.

Development Mode

Development is iterative based on:

Bug reports and fixes
User feedback and feature requests
Performance optimization
Cross-browser compatibility improvements
Code quality enhancements

When implementing changes:

Treat each issue/enhancement as an independent task
Group related bugfixes in a single commit
Update CHANGELOG.md for user-facing changes
Test thoroughly across different browsers when possible
Maintain backward compatibility with existing data

Release Process

Astrolabe uses semantic versioning with alpha releases (0.x.y) until public launch. Each release requires version updates in four files: config.js (APP_VERSION), sw.js (CACHE_NAME), CLAUDE.md, and CHANGELOG.md. See project-docs/release-checklist.md for the complete workflow.

Development Principles

Lean: No frameworks, no build step, minimal dependencies
Maintainable: Clean code organization with logical separation of concerns
Simple: Favor code removal over addition; avoid over-engineering
Local-first: All data stored in browser, no server dependencies

General coding instructions (important)

Astrolabe is a project with minimalistic philosophy; it tries to avoid external dependencies and complexity, if possible. This means that whatever new feature, refactor, or bug fix is being considered, the solution should not be over-engineered unless absolutely necessary. The importance and complexity of a feature defines allowed number of lines of code dedicated to it.
Pay attention to the existing code base style and approaches and try to adhere to the existing style instead of bringing your own vision.
When updating documentation, do not record intermediate changes - write them always as a matter-of-fact information.
When working on the code, if you notice any opportunities to better bring the project to the state above - bring this to user's attention and ask for approval to implement the suggested changes.
When attempting to implement a new feature, research whether a similar method or fuction already exists elsewhere. Propose to either enhance existing one, or create a new method in such cases.
Testing: The user always tests changes manually. Do not start local servers or attempt to run the application.

Documentation guidelines

Conciseness: Keep documentation compact and practical. Avoid verbose explanations or unnecessary code examples in technical docs.
Code examples: Only include code examples in documentation when they genuinely clarify complex concepts. Omit examples for straightforward implementations.
User-facing content: When updating help/about sections in the UI (like index.html modals), keep additions brief and integrated with existing content style.
Technical docs: Focus on "what" and "why" rather than "how" - developers can read the actual code for implementation details.

4.7 KiB Raw Blame History