TutorialIntroduction

Tutorial: Build a transactional integration

In this tutorial you build a complete transactional integration and the System that runs it: order files land in a source folder, travel through a receive pipeline, a component-owned internal queue, and a send pipeline, and come out the other side as transformed order documents in a destination folder. One Component, one system host, observable end to end.

You scaffold the Component with empty pipeline steps and implement them yourself, chapter by chapter. The scaffold compiles from the first minute and ships its own test suite; each chapter turns one more piece from stub to working code, and the tests tell you how far you’ve come.

You do not need to read the concept pages before starting. The tutorial introduces the model where it appears: Component at scaffold time, pipeline when the send steps open, System when the host is created, and platform services when idempotency and business incidents are wired.

Before you begin

Tools installed: .NET SDK 10, Docker Desktop, Dapr CLI 1.16+ (initialized with dapr init), Task
The Intropy CLI installed and on your PATH (intropy --help prints the verbs)
A scratch directory you don’t mind throwing away

Docker and Dapr are only exercised from chapter 4 onward, when the system host runs the Component locally. If you want to see the local run before writing pipeline code, do the Quick start first and come back here.

What you’ll build

A Transactional Integration: an edge Component that moves transaction data (orders) from a source system to a destination system as one flow. Locally, two folders stand in for the real systems; swapping them for SFTP or an ERP API later is deployment configuration, not a code change, because the Component only ever knows its two Ports by name. Build, connect, deploy explains that boundary after you have seen it in code.

FIG T1Zoomed out: the System is one Component and the pub/sub it owns. The source and destination systems sit outside the boundary, reached through the Component's two Ports.

Zooming into the component, the two pipelines appear — the receive pipeline feeding the queue, the send pipeline draining it:

FIG T2Zoomed in: the same component's two pipelines and the internal queue between them. The folders outside the dashed boundary stand in for the source and destination systems.

Your code External touchpoint Infrastructure, not your code

The two pipelines have different jobs. The receive pipeline moves each source file onto the internal queue and cleans up: transport, not business logic. The send pipeline does the business work, one message at a time: deserialize, extract, validate, transform, serialize, send. The scaffold ships the receive pipeline fully implemented; the send pipeline steps are yours to write.

The internal queue is the Component’s own plumbing. It is minted as internal-order-sync, scoped to this Component alone, and never appears as a System Topic; Systems and topology explains why the boundary is drawn there.

What you learn

How a scaffolded Component is laid out.
How a typed pipeline turns raw bytes into a destination document.
Where the context carries values that later steps must not recompute.
How unit tests cover pure steps and integration tests pin the full pipeline.
How idempotency and business incidents sit around the Component.

The chapters

Each chapter introduces one thing, ends in a runnable command, and leaves you with working code. You can stop after any of them.

Scaffold the component — render the transactional template with empty step bodies and tour what you got, failing tests included
The model and the Deserializer — define the message and get impure values into the context
Extract, validate, transform — the business steps, pure and unit-testable
Serialize, send, and run — finish the pipeline, create the system host, and watch an order travel end to end
Idempotency and business incidents — wire the platform services: deduplication keyed on a business identifier, incident routing for failures a person must resolve