Atlas Builder Boundary

1. Decision

Ocean-Atlas will use a one-directional build architecture consisting of three layers:

Canonical Ocean-Atlas Knowledge
            │
            ▼
      builders/core/
  technology-independent
            │
      normalized contract
            ▼
 builders/astro-starlight/
  presentation adapter
            │
            ▼
      Astro + Starlight
            │
            ▼
        static dist/

Canonical knowledge is the source of truth.

builders/core discovers, validates, and normalizes that knowledge into a stable build-time model.

builders/astro-starlight consumes the Core model and adapts it to Astro and Starlight conventions.

Generated website content and dist/ are disposable outputs and never become canonical knowledge.

2. Status

This decision is Accepted.

It governs the implementation of the first Ocean-Atlas website builder and establishes the dependency boundary for future builders.

3. Context

Ocean-Atlas can contain canonical knowledge about Ocean, including:

DSL references;
concepts;
architecture documents;
guides;
tutorials;
patterns;
examples;
decisions;
related assets.

This knowledge must remain valid independently of the technology used to present it.

The first website will be built with Astro and Starlight. However, making canonical documents directly conform to Astro or Starlight would couple the knowledge model to one presentation implementation.

Such coupling would make future changes more difficult. Replacing the website technology, producing another output format, or introducing a second builder could require rewriting canonical knowledge or duplicating its interpretation rules.

Ocean-Atlas therefore requires an explicit boundary between canonical knowledge and presentation technology.

4. Problem

A direct pipeline such as:

Canonical Markdown
        │
        ▼
Astro- or Starlight-specific interpretation
        │
        ▼
Website

would create several architectural problems:

canonical documents could become dependent on framework-specific frontmatter;
routing could become coupled to source-directory conventions;
navigation rules could become embedded in Starlight configuration;
validation could be duplicated across presentation builders;
relationships could be interpreted differently by different consumers;
replacing Astro or Starlight could require changing canonical content;
generated presentation files could be mistaken for authoritative knowledge.

The system needs one canonical interpretation of Ocean-Atlas knowledge without prematurely building a large generic publishing framework.

5. Decision Drivers

The decision is guided by the following requirements:

canonical knowledge must remain technology-independent;
presentation technology must be replaceable;
validation and normalization rules must have one owner;
the website must be statically buildable;
generated output must be reproducible and disposable;
the first implementation must remain small;
future builders must not be prevented;
Astro and Starlight must remain implementation details of one adapter;
no generated artifact may flow back into the knowledge layer.

6. Architectural Layers

6.1 Canonical Knowledge Layer

The knowledge layer contains authored Ocean-Atlas content.

Example structure:

ocean-atlas/
├── index.md
├── atlas/
├── concepts/
├── dsl/
├── architecture/
├── guides/
├── tutorials/
├── patterns/
├── examples/
├── decisions/
│   └── adrs/
└── assets/

The knowledge layer:

is authoritative;
is manually maintained unless a document explicitly declares another origin;
uses Ocean-Atlas metadata and document conventions;
does not depend on Astro, Starlight, React, Vue, or another presentation framework;
does not contain generated website files;
remains valid if all builders and generated output are deleted.

6.2 Builder Core Layer

builders/core is a build-time TypeScript package.

It:

discovers canonical knowledge files;
parses document metadata and content;
validates required fields and identities;
validates supported relationships;
normalizes source documents into a stable model;
derives presentation-neutral routes and navigation inputs;
resolves assets required by documents;
exposes a stable TypeScript API to builders.

It does not know about Astro or Starlight.

6.3 Presentation Adapter Layer

builders/astro-starlight is the first presentation adapter.

It:

depends on builders/core;
consumes the normalized Core model;
maps normalized documents to Starlight-compatible content;
maps normalized navigation to Starlight navigation;
applies Astro and Starlight presentation conventions;
copies or transforms presentation assets as required;
invokes the static website build.

It must not independently redefine canonical parsing or validation rules.

6.4 Generated Output Layer

Generated content and dist/ are derived artifacts.

They:

may be deleted at any time;
are recreated entirely from canonical knowledge and builder code;
are excluded from canonical discovery;
are not manually maintained;
must not be referenced as the source of authoritative knowledge;
must not be copied back into canonical folders.

7. Dependency Direction

The dependency direction is strict:

astro-starlight  ──depends on──▶  core

core             ──X──────────▶  astro-starlight

More completely:

Canonical Knowledge
        │
        ▼
Builder Core
        │
        ▼
Astro/Starlight Adapter
        │
        ▼
Generated Content and dist/

Dependencies and data flow must not point upward.

In particular:

canonical knowledge does not import builder code;
Core does not import Astro or Starlight packages;
the adapter does not modify canonical knowledge;
generated output does not become Core input;
generated output does not become canonical knowledge.

8. Repository Structure

The builder implementation will use:

ocean-atlas/
├── index.md
├── atlas/
├── concepts/
├── dsl/
├── architecture/
├── guides/
├── tutorials/
├── patterns/
├── examples/
├── decisions/
│   └── adrs/
├── assets/
│
├── builders/
│   ├── core/
│   └── astro-starlight/
│
└── dist/                      # generated and ignored

builders/ is preferred over website/ because Astro and Starlight are one builder implementation, not the identity of Ocean-Atlas itself.

9. Core V1 Contract

Core V1 will expose the smallest contract required by the first adapter.

Conceptually:

KnowledgeSource
      │
      ▼
NormalizedDocument[]
Navigation
Assets
      │
      ▼
Renderer Adapter

The initial normalized model should contain only proven requirements.

The following TypeScript is an illustrative V1 shape, not a permanently frozen public API. The implementation may refine field names and supporting types without changing the architectural boundary established by this decision:

export interface NormalizedRelationship {
  type: string;
  target: string;
}

export interface NormalizedDocument {
  id: string;
  title: string;
  type: string;
  area: string;
  status: string;
  authority: string;
  summary: string;
  sourcePath: string;
  route: string;
  content: string; // authored Markdown body, excluding the Metadata section
  relationships: NormalizedRelationship[];
}

export interface NavigationItem {
  label: string;
  documentId: string;
  route: string;
}

export interface NavigationGroup {
  label: string;
  items: NavigationItem[];
}

export interface NormalizedAsset {
  sourcePath: string;
  reference: string;
  mediaType?: string;
}

export interface AtlasModel {
  schemaVersion: 1;
  documents: NormalizedDocument[];
  navigation: NavigationGroup[];
  assets: NormalizedAsset[];
}

Core owns canonical asset identity and source resolution. It does not assign an adapter output path; output placement belongs to the presentation adapter.

The normalized model must carry a schema version so adapters can reject incompatible Core output explicitly. The types may evolve through normal versioned change when actual consumers demonstrate additional shared requirements.

10. Core Responsibilities

Core V1 owns:

Discovery

find canonical Ocean-Atlas documents;
identify supported knowledge directories;
exclude builders, generated content, dist/, dependencies, and caches;
produce deterministic source ordering;

Parsing

read document titles;
read the canonical ## Metadata block;
read relationships;
preserve the authored Markdown body without converting it to HTML;
separate the canonical Metadata section from the presentation body;
retain the canonical source path.

Validation

require supported metadata fields;
require unique document IDs;
detect malformed metadata;
validate canonical relationship target existence;
detect route collisions;
reject canonical input from excluded generated directories;
report actionable source locations.

Normalization

normalize metadata into stable TypeScript types;
derive stable technology-independent routes;
normalize relationships;
build navigation inputs;
resolve referenced assets;
ensure discovered documents and assets remain inside approved canonical roots after path normalization and symbolic-link resolution;
return deterministic output.

11. Core Non-responsibilities

Core V1 does not own:

Astro content collections;
Starlight frontmatter;
Starlight sidebar configuration;
Astro routes or components;
HTML rendering;
CSS themes;
client-side JavaScript;
framework-specific navigation structures;
deployment of the static website;
search indexing;
embeddings;
RAG;
a vector database;
a runtime Atlas API;
an AI assistant;
a general-purpose knowledge graph implementation.

These concerns either belong to presentation adapters, deployment, or future stories.

12. Astro/Starlight Adapter Responsibilities

The first adapter owns:

Starlight-compatible generated content;
Starlight-specific frontmatter;
sidebar and navigation mapping;
Astro configuration;
Starlight configuration;
presentation components and overrides;
theme and styling;
static asset placement;
invoking the Astro static build;
producing dist/.

The adapter consumes Core output. It must not scan canonical folders and establish a second interpretation of their semantics.

13. Generated Content Strategy

Starlight may require generated Markdown, MDX, frontmatter, or configuration files.

Such files must be written to an adapter-owned generated directory, for example:

builders/astro-starlight/generated/

The directory must be ignored by version control. Test fixtures belong in dedicated test-fixture directories, not in generated output.

Generated Starlight content is an adapter artifact. It is not canonical Ocean-Atlas content.

14. Routing

Canonical document identity and public route are related but distinct.

Document ID  → stable semantic identity
Source path  → canonical repository location
Route        → normalized presentation location

Core derives or validates a presentation-neutral route. The adapter maps that route to the selected framework without making file-based routing part of the canonical knowledge contract.

Route derivation must be:

deterministic;
collision-free;
independent of generated file placement;
stable unless the canonical route policy changes explicitly.

Navigation is derived from canonical knowledge and explicit, technology-independent Atlas organization rules.

Core provides presentation-neutral navigation groups and items.

The Astro/Starlight adapter maps those groups to Starlight’s navigation or sidebar model.

Starlight configuration must not become the authoritative definition of the Ocean-Atlas information architecture. Source-directory order alone must not silently become canonical navigation order.

16. Validation Boundary

Core validates knowledge semantics required by all builders.

The adapter validates presentation-specific constraints.

Core validation
    ├── metadata
    ├── IDs
    ├── relationships
    ├── routes
    └── canonical assets

Adapter validation
    ├── Starlight mapping
    ├── generated frontmatter
    ├── component availability
    └── presentation build requirements

The same rule must not be implemented independently in both layers unless the adapter is enforcing a stricter presentation-specific constraint.

17. Determinism and Reproducibility

Given identical:

canonical knowledge;
builder source;
dependency versions;
builder configuration;
build environment inputs;

the build should produce equivalent normalized models and static output.

Generated timestamps, random identifiers, absolute machine paths, and other volatile values must not enter normalized or published output unless a separate requirement explicitly declares them and provides a reproducibility policy.

The following workflow must be valid:

delete generated content and dist/
                │
                ▼
          run the build
                │
                ▼
      recreate the complete site

No manually maintained information may exist only in generated output.

18. Failure Behavior

The build must fail before presentation generation when canonical knowledge cannot be normalized safely.

Examples include:

duplicate IDs;
missing required metadata;
malformed relationships;
unresolved canonical relationship targets;
duplicate routes;
unsupported canonical file structure;
invalid asset references.

Canonical paths that escape approved knowledge roots through traversal or symbolic links are invalid.

Errors should identify:

the source file;
the affected field or relationship;
the violated rule;
enough context to correct the canonical document.

The builder must not silently omit invalid canonical documents.

19. Initial Vertical Slice

Implementation will begin with one end-to-end slice:

Canonical index.md and dsl/service.md
                │
                ▼
Core discovery, parsing, and validation
                │
                ▼
Normalized AtlasModel
                │
                ▼
Astro/Starlight generated content
                │
                ▼
Static index and /dsl/service page

After the boundary is proven, discovery expands to the complete canonical knowledge set.

20. Alternatives Considered

Direct Astro/Starlight ownership of canonical content

Rejected because it couples canonical knowledge, routing, metadata, and navigation to one presentation framework.

A generic website directory

Rejected in favor of builders/astro-starlight because website/ implies that one implementation is the permanent identity of the Ocean-Atlas presentation layer.

Building a runtime knowledge service first

Rejected for this story. A runtime API, search/indexing pipeline, knowledge graph, embeddings, and RAG are unnecessary for static-site generation.

Building a large universal publishing framework

Rejected for now. The architecture permits future builders, but Core V1 will implement only abstractions proven necessary by the Astro/Starlight adapter.

Using another documentation framework for Builder V1

Deferred. Astro and Starlight are selected for the first adapter, but this decision deliberately prevents their conventions from becoming the canonical architecture.

21. Consequences

Positive

canonical knowledge survives presentation-technology replacement;
validation and normalization have one owner;
future builders can consume one stable model;
generated output is clearly disposable;
Astro and Starlight remain isolated;
routes and navigation do not depend fundamentally on generated file placement;
the static website can be rebuilt deterministically;
testing Core does not require the presentation framework.

Negative

the first website requires an additional package boundary;
normalized types must be maintained carefully;
the adapter may need generated intermediate content for Starlight;
some information is transformed twice: canonical to normalized, then normalized to presentation-specific;
developers must understand which layer owns each rule.

Risks

Core could be over-generalized before a second consumer exists;
presentation-specific requirements could leak into normalized types;
the adapter could bypass Core and read canonical files directly;
generated files could accidentally be committed or manually edited;
duplicated validation could cause inconsistent behavior.

These risks are controlled through the explicit responsibilities and constraints in this decision.

22. Constraints

The following constraints are mandatory:

canonical knowledge is the only source of truth;
Core is technology-independent;
Core has no Astro or Starlight dependencies;
Astro/Starlight depends on Core;
the adapter consumes the Core model rather than independently interpreting canonical files;
generated content and dist/ are ignored and disposable;
generated output never flows back into canonical knowledge;
canonical files contain no required Astro- or Starlight-specific metadata;
Core V1 remains limited to requirements demonstrated by the first adapter;
future builders may be added without changing the dependency direction.

23. Acceptance Criteria

This decision is implemented when:

builders/core exists as an independent TypeScript package;
builders/astro-starlight exists as a separate TypeScript package;
the adapter depends on Core;
Core has no Astro or Starlight dependency;
the Core model exposes an explicit schema version;
Core discovers and normalizes canonical index.md and at least one DSL document;
duplicate IDs fail the build;
malformed required metadata fails the build;
unresolved canonical relationship targets fail the build;
route collisions fail the build;
the adapter generates a working Atlas index page;
the adapter generates at least one complete DSL page;
Astro produces static dist/ output;
canonical files remain unchanged after the build;
deleting generated content and dist/ followed by rebuilding recreates the website;
generated directories and dist/ are excluded from canonical discovery and version control;
normalized document and asset paths cannot escape approved canonical roots;
an automated dependency-boundary test prevents Astro or Starlight packages from entering Core.

24. Future Evolution

Potential future consumers include:

builders/
├── core/
├── astro-starlight/
├── pdf/
├── offline-docs/
└── another-web-stack/

No future builder is required by this decision.

When a second consumer appears, Core may generalize only the capabilities that have proven reusable across consumers.

Possible later capabilities include:

richer navigation policies;
heading extraction;
document graph projections;
search-index generation;
PDF-oriented normalization;
additional asset transforms;
localization support.

Such capabilities require separate scope and must preserve the dependency boundary established here.

25. Review Triggers

This decision should be reviewed when:

a second builder is implemented;
canonical content requires presentation-specific metadata;
route derivation cannot remain technology-independent;
Core begins accumulating framework-specific dependencies;
generated output is proposed as an input to another canonical process;
runtime knowledge services become part of Ocean-Atlas;
the static-site requirement changes materially.

Review does not imply reversal. Any change must explicitly address technology independence and one-directional data flow.

This decision is related to:

atlas.index — defines the canonical entry point and knowledge inventory;
the canonical documents under dsl/ and concepts/ consumed by Builder Core;
adr.canonical-markdown-build-model — the canonical Markdown format and metadata block Core parses, validates, and normalizes;
adr.external-examples-repository — how the ocean-examples submodule respects this same Core/adapter boundary;
adr.stable-knowledge-identity — the ID, source-path, and route distinction Core is responsible for deriving and validating;
adr.search-today-structured-retrieval-tomorrow — why future search and retrieval must consume Core’s normalized model rather than generated presentation output.

These semantic relationships are declared in the document metadata.