staccato-spec

Practical architecture specifications for the Staccato model.

This repository stores normative specifications under spec/. The docs/ path is intentionally reserved for GitHub Pages and non-normative content.

Reading Order

1. Architecture Principles
2. Map Intent vNext
3. Catalog Integration
4. Background
5. Use Cases

Repository Structure

• spec/: normative specifications (MUST/SHOULD/MAY)
• spec/adr/: architecture decision records
• docs/: reserved for GitHub Pages and explanatory materials

Scope

The current baseline defines a four-party model:

• User
• Staff
• Cartographer
• Library

It also defines a faceless Cartographer pattern where URL sharing is intentionally de-emphasized and Map Intent is the primary shareable artifact.

Staccato Architecture

The Staccato architecture separates responsibilities between an internal Staff component (enterprise-side) and an external Cartographer component (internet-side).

• Staff (internal): runs inside an organization's secure environment, interprets natural-language queries from users, and produces a structured Map Intent (YAML). Staff resolves layers only from catalogs configured at startup and records catalog_context and lightweight provenance in the intent.
• Cartographer (external): runs in an internet-accessible environment and consumes posted Map Intent to render browser maps (MapLibre GL JS). Cartographer is designed to be faceless: a single / endpoint where GET / presents an input form and POST / accepts Map Intent. It intentionally avoids encoding map state in URLs and minimizes payload persistence and logging to reduce leakage risk.

Key principles:

• Human-mediated handoff: a human copies the Map Intent from Staff to Cartographer, which clarifies accountability.
• Data model: TileJSON 3.0 (collection) is the recommended canonical consumption model for tile-centric catalogs; STAC is supported as a discovery/source model and materialized into TileJSON when PMTiles or tile assets are present.
• Minimal provenance: Map Intent should include catalog_context and a generated_at/generated_by provenance snapshot to aid reproducibility.

Purpose: the Staccato architecture aims to provide reproducible, auditable map generation while reducing the risk of accidental leakage from URL sharing or server-side persistence.

Reference Implementations

Working, publicly deployed reference implementations exist for two of the four roles:

• Library: hfu/layers-martin — converts GSI's layers.txt into a Martin-compatible static TileJSON catalog (/catalog + /{source_id}), published via GitHub Pages. Curates ~12,600 raw candidate layers down to a usable ~1,861-entry catalog (suppressing satellite-snapshot noise, deduplicating repeated tile URLs), and extends TileJSON with a legend_image_url field. Design decisions are recorded as ADRs in its own DECISIONS.md.
• Cartographer: hfu/faceless-cartographer — a static single-page app (no server, no LLM this generation) deployed at https://hfu.github.io/faceless-cartographer/. Implements the faceless pattern (ADR 0001) as a client-side view transition rather than a literal GET / / POST / HTTP split, since no page ever actually reloads or changes URL. This was originally a deliberate, recorded deviation from the ADR's literal wording (see its DECISIONS.md); ADR 0003 now proposes clarifying ADR 0001 to formally accommodate this interpretation, using this implementation as evidence.

Both are wired together end-to-end: a Staff system-prompt addendum lives in layers-martin's STAFF_PROMPT.md (iterated against real enterprise-AI role-play), and faceless-cartographer fetches and displays it so a compatible Staff agent can be set up without leaving the page.

A notable finding from combining a second, independently-operated Library (a live Martin server at stars.optgeo.org, publishing GSI's optimized vector-tile basemap) alongside layers-martin in one Map Intent: no catalog-aggregator component was needed. catalog_context.active_catalogs being an array already supports listing multiple, unrelated Library catalogs side by side, and Cartographer resolves and renders both without any merging step. See UNopenGIS/7#936 and #938 for the fuller writeup.

That same stars.optgeo.org Martin server also publishes complete MapLibre styles (GET /style/{style_id}), not just tile sources — faceless-cartographer added required_styles/optional_styles (Map Intent fields referencing a whole published style rather than individual source_ids) to let a user ask for a complete, pre-designed thematic map (e.g. "show me the volcanic land condition map") without Staff having to reconstruct it from raw layers. ADR 0007 proposes formalizing this; two thematic-only styles (extracted from hfu/kitavolca) are live at https://stars.optgeo.org/style/vlcm and /style/vbm as concrete evidence.

Related Work

yuiseki/TRIDENT is an earlier, independently-developed project in the same broad space — an AI assistant that turns natural-language requests into an interactive MapLibre GL JS map, backed by OpenStreetMap/Overpass data. It predates this repository by several years and was developed without knowledge of it (no shared code, terminology, or contributors between the two projects).

Its architecture differs from Staccato's in ways that reflect a different operating context: TRIDENT runs as a single application with no enterprise/internet trust boundary, and its LLM layer generates Overpass QL queries directly rather than selecting source_ids from a pre-published catalog. Staccato's separation of Staff/Cartographer across a human-mediated handoff, and its insistence that Staff only select from catalog-resolved source_ids rather than generate identifiers itself, stem from the enterprise network-separation constraints in the CONOPS this repository originates from (see Background) rather than from TRIDENT. It's referenced here as related prior art in the "AI + natural language + web map" space, not as a source this specification derives from.

Repository Guide — Quick Start

• What to read first: spec/architecture-principles.md, spec/map-intent-vnext.md, spec/catalog-integration.md, then spec/background.md and spec/usecase.md for context and examples.
• Normative vs informative: spec/ contains normative specifications (MUST/SHOULD language), ADRs (spec/adr/) record decisions; other files provide background and examples.
• Cartographer consumption model: TileJSON 3.0 (collection) is the recommended canonical model; STAC is supported for discovery and should be materialized to TileJSON for rendering where PMTiles/tile assets exist.
• Contribution flow: propose changes via PR; record important architecture or policy changes as an ADR in spec/adr/000N-*.md and reference it from the PR.

If you plan to commit changes, use a clear message such as: "spec: add repository guide; standardize ingestion model to TileJSON 3.0".