Tutorial: Build your first app

This is the canonical “Day 1 to Day 30” tutorial. We build Acme.Store — a small e-commerce backend — together. By the end you’ll have:

• a modular monolith with Orders, Products, and Health modules.
• REST endpoints exposed via behaviors, documented via OpenAPI/Scalar.
• EF Core wired through Cephalon.Data.EntityFramework.
• structured logs, metrics, and traces flowing to an OTLP collector.
• composition smoke tests + per-feature behavior tests.
• a container image that boots in any of the seven supported deploy targets.

Total time: 3–4 hours if you read carefully, 6–8 hours if you also experiment.

The 8 steps

Step 1

Scaffold and run

cephalon new, run the host, hit /engine/manifest, understand the generated layout.

Start step 1 Step 2

Add a domain module

Create the Products module: descriptor, services, REST behaviors, OpenAPI surface.

Open step 2 Step 3

Wire EF Core

Plug in Cephalon.Data.EntityFramework, define the read/write DbContexts, run migrations.

Open step 3 Step 4

REST API + Scalar

Build a full CRUD REST surface with OpenAPI customization and Scalar as the docs UI.

Open step 4 Step 5

Eventing

Add the Orders module, integrate Wolverine, send and consume domain events with the outbox pattern.

Open step 5 Step 6

Observability

Wire OpenTelemetry, enrich logs, add dependency-health probes, plug into a local OTLP collector.

Open step 6 Step 7

Tests

Composition smoke tests, behavior specifications, integration tests against Postgres containers.

Open step 7 Step 8

Deploy

Build the container image, deploy with the included Azure Container Apps script, validate end-to-end.

Open step 8

Before you start

Make sure you’ve completed the Quickstart. You should have:

• dotnet --version showing 10.x.
• cephalon doctor reporting clean.
• A code editor (Visual Studio 2026, Rider 2026.1+, or VS Code with C# Dev Kit).
• A free local Postgres (we’ll use docker run -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres:16).
• Roughly 2 GB of free disk for packages and container images.

If you’re on a connection-limited or air-gapped network, follow Installation → CLI → Air-gapped install first.

Final shape

By the end of the tutorial, your Acme.Store directory will look like this:

Acme.Store/
├── src/
│   ├── Acme.Store.Host/
│   │   ├── Program.cs
│   │   ├── appsettings.json
│   │   ├── appsettings.Development.json
│   │   ├── Configurations/
│   │   └── Acme.Store.Host.csproj
│   ├── Acme.Store.Modules.Health/
│   ├── Acme.Store.Modules.Products/
│   │   ├── ProductsModule.cs
│   │   ├── Behaviors/
│   │   │   ├── CreateProductBehavior.cs
│   │   │   ├── ListProductsBehavior.cs
│   │   │   ├── GetProductBehavior.cs
│   │   │   ├── UpdateProductBehavior.cs
│   │   │   └── DeleteProductBehavior.cs
│   │   ├── Data/
│   │   │   ├── ProductsDbContext.cs
│   │   │   └── Migrations/
│   │   └── Domain/
│   └── Acme.Store.Modules.Orders/
│       ├── OrdersModule.cs
│       ├── Behaviors/
│       ├── Events/
│       └── ProcessManagers/
├── tests/
│   └── Acme.Store.Host.Tests/
│       ├── Architecture/CompositionSmokeTests.cs
│       └── Features/
└── deploy/

Ready? Step 1 → Scaffold and run.