Ocean System Design Model

1. Overview

Ocean is a DSL-first system design platform.

Its DSL describes the intent and structure of a software system independently from the technologies used to implement it.

Rather than directly describing frameworks, libraries, infrastructure, or programming-language constructs, Ocean models concerns such as:

• data;
• public interfaces;
• persistence;
• messaging;
• shared execution context;
• reusable logic;
• stateful behavior;
• behavioral composition;
• service orchestration;
• configuration;
• deployment.

Generators and engines translate these technology-independent definitions into concrete implementations.

Conceptually:

Ocean DSL
    ↓
System Model
    ↓
Validation and Resolution
    ↓
Technology-Specific Generation
    ↓
Applications, Services, Infrastructure, Documentation

---

2. Core Design Principle

Ocean separates what a system means from how it is implemented.

For example, an API may be modeled as:

API
    style: REST

without coupling the system model to a particular REST framework.

The same principle applies to databases, brokers, deployment technologies, and other implementation concerns.

This allows the DSL model to remain stable while implementation technologies evolve.

---

3. System Model

Ocean systems are composed from multiple complementary DSL concerns.

They should not be understood as a strict inheritance hierarchy.

Instead, each DSL area contributes a specific responsibility to the complete system model.

                    Service
                       │
        ┌──────────────┼──────────────┐
        │              │              │
       API         Behavior        Messaging
                                    / Integration
        │              │              │
        │        ┌─────┼─────┐       │
        │        │     │     │       │
        │   Expression FSM Component  Broker
        │              │
        │           Context
        │
     Datatypes
        │
     Database

          + Configuration
          + Deployment
          + Other supporting DSL concerns

The exact composition depends on the system being modeled.

A service does not need to use every DSL construct.

---

4. Datatypes

@datatype defines the technology-independent data model used throughout Ocean.

Datatypes provide shared contracts for:

• API inputs and outputs;
• database entities;
• broker messages;
• expression inputs and outputs;
• context fields;
• FSM events;
• service interactions.

Example conceptually:

@datatype

TodoItem
    id       : String
    title    : String
    priority : Priority

Datatypes establish a common type system across otherwise independent DSL areas.

Canonical reference:

dsl.datatype

---

5. APIs

@api defines externally accessible service interfaces.

An API describes:

• operations;
• typed inputs;
• typed outputs;
• interaction style;
• transport-related configuration.

Ocean APIs are technology-independent at the model level.

Different API styles may define different operation syntax, including:

• REST;
• gRPC;
• GraphQL;
• WebSocket;
• SOAP.

The selected style describes the interaction model, while generators determine the concrete implementation technology.

Canonical reference:

dsl.api

---

6. Databases

@database defines persistence behavior for Ocean datatypes.

It describes concerns such as:

• database type;
• database engine;
• entity mappings;
• relationships;
• keys;
• indexes;
• encryption;
• queries;
• commands.

The datatype remains responsible for defining data structure.

The database definition adds persistence semantics to that structure.

Conceptually:

Datatype
    ↓
Database Entity
    ↓
Persistence Implementation

Canonical reference:

dsl.database

---

7. Brokers

@broker defines asynchronous messaging boundaries.

A broker contains topics with typed message payloads and may describe messaging behavior such as:

• events;
• requests;
• responses;
• request-response interactions;
• delivery configuration;
• timeout behavior.

Broker topics use Ocean datatypes as their message contracts.

Conceptually:

Publisher
    ↓
Broker Topic
    ↓
Consumer

The broker DSL describes messaging intent independently from technologies such as NATS, Kafka, or other messaging engines.

Canonical reference:

dsl.broker

---

8. Context

@context defines volatile shared execution state.

Contexts provide typed data that can be shared explicitly between cooperating parts of service logic.

Unlike database state, context data is not persistent.

Typical uses include:

• request state;
• temporary workflow data;
• orchestration state;
• execution metadata.

Conceptually:

Service Logic
    ↕
Context

Access remains explicit through DSL connections and orchestration.

Canonical reference:

dsl.context

---

9. Expressions

@expression defines reusable stateless logic.

Expressions may represent:

• conditions;
• calculations;
• validation;
• mapping;
• transformations;
• derived values;
• decision logic.

Expressions operate on typed inputs and produce typed outputs.

They are designed to remain:

• stateless;
• side-effect-free;
• reusable;
• composable.

Conceptually:

Input
   ↓
Expression
   ↓
Output

Expressions may be used by higher-level behavioral constructs such as FSMs, Components, and Services.

Canonical reference:

dsl.expression

---

10. Finite-State Machines

@fsm models behavior that evolves over time through states and transitions.

FSMs define:

• states;
• events;
• triggers;
• transitions;
• actions;
• reusable logic.

Ocean supports both:

• entity-controlled FSMs, where state is represented by persisted entity data;
• in-memory FSMs, where state exists temporarily during execution.

Conceptually:

Current State
     +
    Event
     ↓
    FSM
     ↓
Actions + Next State

FSMs provide explicit and deterministic modeling of lifecycle-oriented behavior.

Canonical reference:

dsl.fsm

---

11. Components

@component is intended to provide reusable behavioral composition.

A Component groups and connects behavioral elements such as:

• FSMs;
• nested Components;
• expressions;
• typed inputs and outputs.

Conceptually:

Component Input
      ↓
  ┌─────────────┐
  │ FSM         │
  │ Expression  │
  │ Component   │
  └─────────────┘
      ↓
Component Output

Components themselves are intended to remain stateless. State belongs to the stateful elements they contain.

@component is currently a work-in-progress capability and may evolve during implementation.

Canonical reference:

dsl.component

---

12. Services

@service represents an independently orchestrated service boundary.

A service brings together the DSL capabilities required to implement a deployable system capability.

Depending on its responsibilities, a service may use:

• APIs;
• databases;
• brokers;
• contexts;
• expressions;
• FSMs;
• Components;
• configuration;
• other services or reusable Ocean definitions.

A service is responsible for connecting these capabilities into an executable model.

Conceptually:

                 Service
                    │
       ┌────────────┼────────────┐
       │            │            │
      API        Behavior      Broker
       │            │            │
       └──────── Connections ─────┘
                    │
                Database
                    │
                Context

Not every service requires every capability.

Canonical reference:

dsl.service

---

13. Explicit Composition

A key Ocean principle is that relationships between system elements should be explicit.

Rather than hiding orchestration inside generated or handwritten code, Ocean models connections directly.

Conceptually:

API operation
      ↓
Expression
      ↓
FSM
      ↓
Database command
      ↓
Broker topic

The actual flow may vary significantly between services.

The important principle is:

System behavior should be visible in the system model rather than reconstructed from implementation code.

---

14. Technology Independence

Ocean DSL constructs describe logical capabilities rather than concrete implementation technologies.

For example:

API
    ↓
REST
    ↓
Gin / Spring / another implementation

Broker
    ↓
Messaging semantics
    ↓
NATS / Kafka / another engine

Database
    ↓
Persistence model
    ↓
PostgreSQL / MongoDB / another engine

The DSL may expose technology-selection fields such as engine, but technology-specific behavior belongs to the corresponding generator or engine implementation.

This separation enables the same logical system design to target different technology stacks.

---

15. Declarative System Design

Ocean favors declarative definitions.

The DSL primarily describes:

• structures;
• contracts;
• relationships;
• state transitions;
• orchestration;
• policies;
• implementation intent.

Generators then produce the required implementation artifacts.

This reduces the amount of infrastructure and integration behavior that must be expressed repeatedly in handwritten code.

---

16. Reuse and Composition

Ocean encourages reusable system definitions.

Reusable knowledge and DSL definitions may be:

• imported from the Ocean Repository;
• included from reusable Ocean definitions;
• composed into larger services and systems.

This enables common capabilities to be modeled once and reused across multiple systems.

Reuse is based on explicit contracts and dependencies rather than copying implementation code.

---

17. Example System Model

A simplified order-processing system may conceptually contain:

OrderService
│
├── OrderAPI
│      └── createOrder
│
├── OrderDatabase
│      ├── Order
│      └── createOrder command
│
├── OrderBroker
│      └── orderCreated
│
├── OrderLifecycleFSM
│      ├── Created
│      ├── Processing
│      ├── Confirmed
│      └── Cancelled
│
└── Expressions
       ├── ValidateOrder
       └── CalculateOrderTotal

The service connects these elements into an executable behavior.

A request might conceptually flow as:

OrderAPI.createOrder
        ↓
ValidateOrder
        ↓
OrderDatabase.createOrder
        ↓
OrderLifecycleFSM
        ↓
OrderBroker.orderCreated

The exact orchestration is defined through the relevant Ocean DSL constructs.

---

18. Benefits

The Ocean system model provides several architectural benefits.

Capability	Benefit
Technology-independent modeling	System intent survives changes in implementation technology.
Explicit contracts	Interfaces and data dependencies are visible and typed.
Explicit behavior	State transitions and orchestration can be inspected directly.
Reuse	Common definitions can be shared through the Ocean Repository.
Code generation	Repetitive implementation and infrastructure code can be generated.
Consistency	Shared DSL semantics produce consistent implementations.
Validation	System-design errors can be detected before generation or deployment.
Multiple targets	The same logical model can support different implementation technologies.
Machine-readable design	Ocean models can be consumed by tooling, documentation, validation, and AI systems.

---

19. Evolving Model

Ocean is designed to evolve through additional DSL capabilities without changing its foundational model.

New capabilities may introduce concerns such as:

• integration;
• packaging and reuse;
• security;
• deployment;
• UI;
• dashboards;
• observability;
• additional API styles;
• additional persistence and messaging technologies.

These capabilities should remain aligned with the core principle:

Ocean describes system intent independently from the technologies used to realize it.

---

20. Related Knowledge

This concept is related to:

• dsl.datatype — defines shared data contracts.
• dsl.api — defines external service interfaces.
• dsl.database — defines persistence behavior.
• dsl.broker — defines messaging capabilities.
• dsl.context — defines volatile shared execution state.
• dsl.expression — defines reusable stateless logic.
• dsl.fsm — defines stateful behavior.
• dsl.component — defines behavioral composition.
• dsl.service — defines service orchestration and service boundaries.

These semantic relationships are declared in the document metadata.