Architecture Decision Records

1. Overview

An ADR answers one question:

What important architectural choice did we make, why did we make it, and what consequences must future contributors understand?

An ADR is not general documentation — that belongs in Concepts or Architecture — and it is not a roadmap or implementation task list. It records a decision with meaningful alternatives and long-term consequences, so a future contributor does not accidentally reverse it without understanding why it was made.

2. Status Lifecycle

Status	Meaning
Proposed	Under discussion; not yet decided.
Accepted	The decision is made and governs current work.
Superseded	Replaced by a later ADR, linked via supersedes / superseded-by.
Deprecated	No longer recommended, without a direct replacement.
Rejected	Considered and explicitly not selected.

3. Index

ADR	Status	Decision
Atlas Builder Boundary	Accepted	A technology-independent Builder Core sits between canonical knowledge and presentation adapters such as Astro/Starlight.
Canonical Markdown and Structured Build Model	Accepted	Canonical knowledge is plain Markdown with a structured ## Metadata block, discovered and validated by a build-time pipeline.
External Examples Repository Integration	Accepted	Runnable examples live in the separate ocean-examples repository, consumed as a git submodule.
Example Knowledge Facets: Horizon, Voyage, and Implementation	Accepted	Every example exposes three modeled facets backed by its descriptor, shared explanation, and runnable project files.
Stable Knowledge Identity Independent of Filesystem Layout	Accepted	Every knowledge item carries an author-assigned, immutable ID, distinct from its file path and derived route.
Search Today and Structured Retrieval Tomorrow	Accepted	Site search enhances Starlight’s Pagefind foundation; future retrieval or RAG must consume Core’s structured model, not rendered HTML.
Knowledge API Service	Accepted	A private, read-only runtime HTTP API over Core’s AtlasModel, reachable only from other Ocean services over Fly’s private network.
Vector Storage and Embedding Provider	Accepted	Knowledge embeddings live in pgvector on the existing shared Fly Postgres cluster, generated by Voyage AI’s voyage-4 behind a provider-independent interface.
Knowledge Chunking and Indexing Pipeline	Accepted	Heading-based chunking with stable-ID-derived chunk identity, kept current by a versioned, lock-safe background reconciliation that adds and removes chunks incrementally.

4. Contributing an ADR

Create an ADR when a decision has meaningful alternatives, long-term consequences, or constraints future contributors might otherwise accidentally reverse — not to retroactively document routine work. Give it a stable ID of the form adr.<identifier>, a dedicated decisions/adrs/adr-<identifier>.md file, and add it to the table in Section 3.