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.
Engineering also carries a language-and-environment shelf - Python, uv, WSL, and the requirements documents - that sits outside these three layers. The Path index has those.
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 does Aspire do for us? LEVEL 101 - the seven pillars at a glance
- → 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
Then the deeper cuts - the app model and the AppHost internals, the container story, and two recipes you can follow end to end.
- → Managed vs referenced resources LEVEL 201 - the app model
- → Inside Aspire's AppHost LEVEL 301 - the internals
- → Aspire and containers LEVEL 201 - two kinds of container
- → Aspire with Docker or Podman LEVEL 201 - the engine underneath
- → How to add Azure SQL Database to an Aspire app LEVEL 201 - recipe
- → How to add Redis caching to an Aspire app LEVEL 201 - recipe
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
- What does Aspire do for us?
- What is Aspire?
- With and without Aspire
- What Aspire does and does not do
- What is Hybrid Aspire?
- Managed vs referenced resources
- Inside Aspire's AppHost
- Aspire and containers
- Aspire with Docker or Podman
- How to add Azure SQL Database to an Aspire app
- How to add Redis caching to an Aspire app
- What is observability?
- What is Scalar?
- Swagger UI and Scalar
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; the AppHost is the system doing it.
- 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 on the platform-craft surface, by category, with a one-line reason to read.
| Category | Article | Why read it |
|---|---|---|
| Orchestration | What does Aspire do for us? 101 | The orientation - the seven pillars Aspire gives a team, start here before the deep dives. |
| 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. |
| Orchestration | Managed vs referenced resources 201 | The one distinction in the app model - resources Aspire runs and owns versus ones it only wires in - and everything that distinction decides. |
| Orchestration | Inside Aspire's AppHost 301 | The teardown - how a graph of resources in code becomes running containers and processes, and the design decisions behind it. |
| Orchestration | Aspire and containers 201 | Two kinds of container in one app - the dependencies Aspire runs for you, and the packaging your own services ship in. |
| Orchestration | Aspire with Docker or Podman 201 | The engine underneath - how Aspire finds Docker or Podman, how to switch between them, and the differences that actually bite. |
| Orchestration | How to add Azure SQL Database to an Aspire app 201 | The recipe - declare an Azure SQL resource, run it as a local SQL Server container, no subscription and nothing to pay for. |
| Orchestration | How to add Redis caching to an Aspire app 201 | The recipe - provision Redis in the AppHost and read and write through it, with the connection wired in for you. |
| 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. |