Skip to content
Ocean-Atlasv0.1.0Canonical Knowledge

Architecture

1. Overview

Section titled “1. Overview”

This section describes Ocean’s platform architecture: its system boundaries, major components, and how those components relate to one another.

It is a landing page, not a specification. It exists to help a reader:

  • understand what belongs in Ocean architecture documentation;
  • see how Ocean’s major architectural layers relate;
  • find where to continue for a specific concern;
  • distinguish authoritative canonical knowledge from explanatory material.

Detailed, normative behavior is defined by the canonical documents this page links to. Where a dedicated architecture document does not yet exist, this page links to the closest current canonical source instead of restating it.

2. Architecture at a Glance

Section titled “2. Architecture at a Glance”
Ocean Ecosystem
├── Ocean DSL                        (technology-independent system model)
├── Application Generators and Engine (turn validated models into runtime outputs)
├── Ocean Repository                 (versioned, reusable definitions)
├── Ocean-Atlas                      (canonical knowledge platform, this site)
├── Ocean-Lab                        (the broader Ocean application environment)
└── Generated applications and infrastructure

Ocean-Atlas documents the DSL, the reuse model, and the platform’s knowledge architecture. It does not implement the Ocean application generators, execution engine, or generated runtimes. Ocean-Atlas has a separate publishing pipeline that derives documentation views from canonical knowledge.

3. Architectural Principles

Section titled “3. Architectural Principles”
  • DSL-first system modeling — a system is described through Ocean DSL constructs before any implementation exists.
  • Technology-independent canonical models — the DSL models intent and structure, not frameworks, libraries, or language constructs.
  • Separation of model and generated implementation — generators and engines translate validated models into concrete outputs; the technology-independent DSL model remains the design source of truth.
  • Stable identities and versioned reuse — reusable definitions are identified and versioned through the Ocean Repository and local Pre-baked Registry.
  • Canonical knowledge as source, generated views as projections — Ocean-Atlas publishes one canonical knowledge base; presentation-specific builders (such as the Astro/Starlight site) generate views from it rather than owning content.
  • Explicit boundaries between Atlas, repositories, tools, and runtimes — each part of the ecosystem has a defined responsibility and does not silently absorb another’s.

These principles are established in more detail by the documents linked in Section 4.

4. Architecture Areas

Section titled “4. Architecture Areas”

4.1 System Design

Section titled “4.1 System Design”

How Ocean DSL constructs combine to model a system.

4.2 Knowledge Architecture

Section titled “4.2 Knowledge Architecture”

How Ocean knowledge is structured, governed, and published.

4.3 Reuse and Distribution

Section titled “4.3 Reuse and Distribution”

How definitions are published, versioned, resolved, and consumed.

4.4 Runtime and Generation

Section titled “4.4 Runtime and Generation”

How validated models become applications, services, infrastructure, documentation, and other generated outputs.

A dedicated runtime and generation architecture document does not yet exist. Until it does, the closest canonical sources are:

  • Ocean DSL — the source-file structure the model and generation pipeline consumes.
  • Service DSL Reference — how domain behavior and infrastructure compose into deployable units.
  • Deploy DSL Reference — how services, UIs, and brokers are materialized into runtime environments.

4.5 Decisions

Section titled “4.5 Decisions”

Architectural decisions and open proposals.

4.6 Knowledge APIs

Section titled “4.6 Knowledge APIs”

How Ocean components and external tools read Ocean-Atlas knowledge programmatically, without depending on the website.

5. System Context

Section titled “5. System Context”
flowchart LR
    Author([Author]) --> DSL[Ocean DSL]
    Repo[(Ocean Repository)] --> Model
    DSL --> Model[Model and Validation]
    Model --> Gen[Application Generators and Engine]
    Gen --> Out["Applications, Services,<br/>and Infrastructure"]


    Atlas[[Ocean-Atlas]] -.-> Humans([Humans])
    Atlas -.-> Tools([Tools])
    Atlas --> Search["Website and Keyword Search"]
    Atlas --> API["Knowledge API<br/>(private, Ocean services only)"]
    Atlas -.-> Future["Semantic Retrieval and RAG — planned"]

An author writes Ocean DSL, optionally reusing definitions resolved from the Ocean Repository. The model is validated and then translated by generators and the engine into applications, services, and infrastructure.

Ocean-Atlas is a separate, parallel system: the canonical knowledge platform that documents the DSL, the reuse model, and the platform architecture itself, consumed today through the website, keyword search, build tooling, and the Knowledge API (reachable only from other Ocean services over Fly’s private network, not the public internet). Semantic retrieval and RAG integration remain documented future capabilities (see atlas.knowledge-architecture).

6. Reading Paths

Section titled “6. Reading Paths”