The Everyday Workflow

This is the loop you just ran in Make the First Change — the same one you’ll run for ordinary Ocean development from here on.

1. The Ocean App Loop

flowchart TD
    M["Edit the model in Ocean App"] --> V[Validate]
    V --> G[Generate]
    G --> R["Run in Ocean App"]
    R --> O[Observe]
    O --> F["Refine the model"]
    F --> M

• Edit — create or change Ocean DSL in the Bundle. The model is where you author the system’s structure and intent.
• Validate — Ocean checks that references resolve, types match, and the Bundle is structurally consistent.
• Generate — Ocean translates the validated model into a concrete implementation for its selected engines and targets.
• Run — launch the generated application inside Ocean App, without installing its target-specific dependencies locally.
• Observe — exercise the application and compare its behavior with what the Bundle describes.
• Refine — put what you learned back into the model, regenerate, and repeat.

This browser-based loop is the normal starting point. Ocean App manages validation, generation, and the first execution experience; the user remains responsible for the model.

2. Working With the Model

• Resolve references deliberately. Every reference — for example, a datatype used by an API or an expression connected by a service — must resolve to a local or explicitly reused definition.
• Select technologies through the model. Attributes such as engine = postgres or engine = gin select concrete technologies without changing the technology-independent purpose of the construct.
• Regenerate after model changes. The implementation is derived from the current Bundle. A model change does not reach the application until it is regenerated.
• Reuse before rebuilding. Check the Ocean Repository before recreating a datatype, expression, service, or other reusable definition.
• Use canonical semantics. When behavior is unclear, the relevant DSL reference is authoritative; concepts and patterns explain how the constructs fit together.

3. When You Download the Generated Project

Downloading is optional. Do it when you want to inspect, extend, build, test, or deploy the implementation outside Ocean App.

The generated project’s README is authoritative for its local workflow, including:

• required runtimes and tools;
• dependencies such as databases or brokers;
• configuration and secrets;
• build and test commands;
• startup and shutdown;
• ports and service endpoints;
• deployment instructions;
• supported extension points.

Generated code should be built and tested like any other implementation before it is deployed. Custom logic belongs in extension points or files the generator does not own—not in output that regeneration may replace. Whether a team commits generated output is a project policy; whatever the choice, keep the model and generator version traceable.

4. Who Owns What

Artifact	Typical owner
Ocean DSL	User/team
Generator configuration	User/team
Generated files	Generator
Extension/custom code	User/team
Canonical language semantics	Ocean DSL reference

The rule underneath the table is simple: if regeneration can overwrite a file, do not hand-edit it. User-owned implementation belongs in a supported extension point or outside the generator’s output boundary.

5. Generated Code, Answered Directly

• Is generated code committed? That is a project decision. Some teams commit it for auditability or deployment; others reproduce it from the model and pinned generator version. Be consistent and keep the inputs traceable.
• Can generated code be edited? Not safely. An edit made directly to generated output is silently at risk the next time someone regenerates.
• What happens when I regenerate? The generator re-derives its output from the current model. Anything the generator owns should end up correct again; anything you hand-edited inside generated files is at risk of being overwritten.
• Where should custom logic live? Outside files the generator writes — in extension points the generator provides, or in code that calls into generated output rather than living inside it.
• How do I switch target language or engine? Change the relevant technology-selection field in the model (an engine = value, a generator target) and regenerate. The model’s meaning doesn’t change; its translation does.
• How does Ocean preserve architecture across targets? The model is technology-independent by construction — see Ocean System Design Model. Switching targets changes the implementation, not the described architecture.
• What is deterministic generation? The same model, generator, and configuration should produce equivalent output every time — generation is a translation, not a one-off creative decision.
• Which parts remain target-specific? Anything the DSL doesn’t model — low-level performance tuning, target-specific idioms, infrastructure details outside @deploy’s scope — stays in the generator’s domain, not the model’s.

6. Essential Terms

Enough vocabulary to keep reading comfortably — full definitions live in the Glossary:

Ocean · Ocean DSL · Bundle · Section · Definition · Datatype · Expression · FSM · Component · Service · Generator · Engine · Artifact · Ocean Repository · Horizon · Voyage · Implementation

7. Errors You’re Likely to Meet Early

Exact compiler wording isn’t catalogued here yet — treat the messages you actually see as more precise than this table. What’s stable is the category and the fix:

Scope	You’ll likely see something about…	It usually means	Start by checking
Ocean App	An unknown section	A typo in a @section name, or a section not yet supported	Ocean DSL section list
Ocean App	Invalid syntax	A malformed declaration inside a section	The syntax in that section’s DSL reference
Ocean App	An unresolved reference	A definition does not exist locally or has not been reused correctly	Spelling and the relevant @import or @include declaration
Ocean App	A duplicate definition	The same name appears twice in a scope that requires uniqueness	Search the Bundle for the name
Ocean App	An incompatible type	A value or reference does not match the expected datatype	The datatype’s declared shape
Ocean App	A missing generator or engine	The selected target is unavailable or unsupported for a construct	The model’s engine selection and available generation target
Downloaded project	Missing environment configuration	A runtime configuration or secret value is absent	The generated README, Config, and Vault
Downloaded project	An unavailable port	Another process is using a port required by the generated application	The generated README and local processes
Downloaded project	A dependency startup failure	A required database, broker, or service is unavailable or not ready	The generated README and dependency logs
Downloaded project	A regeneration conflict	Generated output was edited or overlaps user-owned code	Section 5 and the generator’s extension guidance

For anything not covered by this table, or a full diagnostic walkthrough, go to Troubleshooting.

What’s Next

You now have the whole loop, not just one pass through it. Next Steps points you toward whichever part of Ocean-Atlas matches what you want to do next.