What this is
This is the Engineering Path organized as a Map - sorted by layer rather than by reading order. Three layers cover the platform-craft surface in 2026: how you orchestrate your services during development, how you understand what they are doing once they are running, and how you document the contract they expose to other services.
It is not a tutorial and not a comparison. It is the page you bookmark, send to a teammate who is catching up, or come back to when you are not sure which article to read next.
Run it, watch it, document it. Three layers, in that order.- the platform craft, in one line
Orchestration
The layer that gets your local environment from "I have eight services" to "I run one command." In a polyglot stack this is where most of the friction lives, and where Aspire has done the most to remove it.
Aspire is the orchestration layer: an AppHost that defines your distributed application in code (C# or TypeScript), starts every service with one command, wires up service discovery and environment variables, and surfaces logs, traces, and metrics through a single dashboard. Read the overview first, then the framing pieces, then the cloud-connected configuration recipe.
- → What is Aspire? LEVEL 201
- → With and without Aspire LEVEL 201 - the visual framing
- → What Aspire does and does not do LEVEL 201 - scope and boundaries
- → What is Hybrid Aspire? LEVEL 201 - local containers + real Azure
Observability
The layer that tells you what is happening inside your services once they are running. The three pillars - logs, metrics, and traces - are the alphabet here; everything else is composition.
Observability is the ability to understand a running system by reading its external outputs. The pillars piece introduces the vocabulary - structured logs for forensic detail, metrics for aggregate health, traces for end-to-end request flow - and explains why a distributed system needs all three rather than picking one.
- → What is observability? LEVEL 101
API documentation
The contract layer. Once a service exposes an HTTP API, you need a way for humans and other services to know how to call it. In 2026 that means an OpenAPI spec and one of two UIs on top.
OpenAPI is the spec; Scalar and Swagger UI are the two renderers most projects ship. Scalar is the modern challenger and the new default in ASP.NET Core 9. Swagger UI is the established choice with a decade of ecosystem behind it. The side-by-side article is where to land if you are choosing between them.
- → What is Scalar? LEVEL 101
- → Swagger UI and Scalar LEVEL 101 - the side-by-side
Three reading orders
The map is sorted by layer, but most readers want a route. Three orders, depending on who you are.
Get your local env running first
Build the service, then the contract
Every article, in order
The map at a glance
If you read only this section, here is the modern Engineering stack from the bottom up:
- Orchestration: Aspire - one command starts your services, your database, and your supporting infrastructure together.
- Observability: Logs, metrics, traces - the three pillars that tell you what is happening inside.
- API documentation: Scalar or Swagger UI on top of an OpenAPI spec.
Across all three: the discipline of treating local development, runtime observability, and the API contract as deliberate, shared concerns rather than as private notebooks.
Every article in the map
Every Engineering Path article, by category, with a one-line reason to read.
| Category | Article | Why read it |
|---|---|---|
| Orchestration | What is Aspire? 201 | The AppHost model, the dashboard, the multi-language story - the full Aspire picture. |
| Orchestration | With and without Aspire 201 | The visual framing - three pain points without orchestration, three fixes Aspire ships. |
| Orchestration | What Aspire does and does not do 201 | The clarification piece - where the framework's responsibility ends and yours begins. |
| Orchestration | What is Hybrid Aspire? 201 | The configuration recipe - local containers, real Azure services, no friction. |
| Observability | What is observability? 101 | Logs, metrics, traces - the three pillars and why distributed systems need all three. |
| API docs | What is Scalar? 101 | The modern API reference UI - and the new default in ASP.NET Core 9. |
| API docs | Swagger UI and Scalar 101 | The side-by-side - two renderers of the same OpenAPI spec, with their tradeoffs. |