Concepts

1. Overview

Concepts explain the foundational ideas behind Ocean: what the platform models, how a complete project is bounded, how behavior is composed, and how definitions are reused. They provide the mental model needed before consulting precise DSL syntax or selecting a modeling pattern.

Start with the Ocean System Design Model for the broad view, then follow the concept that matches the question you are trying to answer.

2. Concept Map

flowchart TD
    Model["System Design Model<br/>What Ocean can describe"]
    Bundle["Ocean Bundle<br/>What forms one complete project"]
    Control["Control Structure<br/>How behavior is composed"]
    Repository["Ocean Repository<br/>How definitions are reused"]

    Model --> Bundle
    Model --> Control
    Bundle -- reuses --> Repository

The relationships are complementary:

• the System Design Model describes the complete technology-independent modeling space;
• a Bundle is one identifiable Ocean DSL project within that model;
• the Control Structure explains the behavioral layers inside a system;
• the Ocean Repository supplies versioned definitions a Bundle can reuse.

3. Concept Catalogue

Concept	Question it answers	Continue to
Ocean System Design Model	How do Ocean’s data, behavior, interfaces, persistence, messaging, configuration, and deployment constructs form one system model?	DSL overview
Ocean Bundle	What belongs to one complete Ocean DSL project, and how is that project identified?	@info, @import, @include
Control Structure	How do services, components, FSMs, and expressions divide and compose behavior?	Service, Component, FSM, Expression
Ocean Repository	How does a project identify and reuse versioned Ocean or local pre-baked definitions?	@import, @include

4. Suggested Reading Paths

New to Ocean

1. Read the System Design Model.
2. Understand the Bundle as the complete project boundary.
3. Open a working example and use its Horizon to see those ideas in a concrete system.

Modeling behavior

1. Read Control Structure.
2. Choose a reusable solution from Patterns.
3. Confirm the precise constructs in the linked DSL references.

Reusing definitions

1. Read Ocean Repository.
2. Review the canonical @import and @include semantics.
3. Apply those rules within the Bundle that consumes the reusable definitions.

5. Knowledge Boundaries

Knowledge area	Purpose
Concepts	Explain the foundational model and why its parts relate.
DSL Reference	Defines exact syntax, semantics, and constraints.
Architecture	Explains major platform components and their boundaries.
Patterns	Recommends reusable solutions to recurring modeling problems.
Examples	Demonstrates the model in validated, runnable projects.
Glossary	Provides concise canonical definitions and aliases.

Concept pages should link to authoritative DSL references instead of redefining syntax, and examples should demonstrate concepts without becoming their normative source.