Architecture content

docs/fundamentals/app-host-overview.md

@@ -1,7 +1,7 @@
 ---
 title: .NET Aspire orchestration overview
 description: Learn the fundamental concepts of .NET Aspire orchestration and explore the various APIs for adding resources and expressing dependencies.
-ms.date: 04/15/2025
+ms.date: 04/23/2025
 ms.topic: overview
 uid: dotnet/aspire/app-host
 ---
@@ -25,19 +25,22 @@ Before continuing, consider some common terminology used in .NET Aspire:
 
 ## Define the app model
 
-.NET Aspire empowers you to seamlessly build, provision, deploy, configure, test, run, and observe your distributed applications. All of these capabilities are achieved through the utilization of an _app model_ that outlines the resources in your .NET Aspire solution and their relationships. These resources encompass projects, executables, containers, and external services and cloud resources that your app depends on. Within every .NET Aspire solution, there's a designated [App host project](#app-host-project), where the app model is precisely defined using methods available on the <xref:Aspire.Hosting.IDistributedApplicationBuilder>. This builder is obtained by invoking <xref:Aspire.Hosting.DistributedApplication.CreateBuilder%2A?displayProperty=nameWithType>.
+.NET Aspire enables you to efficiently build, provision, deploy, configure, test, run, and monitor your distributed applications. These capabilities are powered by an _app model_, which defines the resources in your .NET Aspire solution and their interconnections.
+
+The app model is more than just a list of resources—it represents the complete topology of your application. This includes the relationships between resources, their dependencies, and their configurations. Resources can include projects, executables, containers, external services, and cloud resources that your application relies on.
+
+In your [.NET Aspire app host project](#app-host-project), your `Program` file defines your app model:
 
 ```csharp
-// Create a new app model builder
 var builder = DistributedApplication.CreateBuilder(args);
 
-// TODO:
-//   Add resources to the app model
-//   Express dependencies between resources
+// Add resources to the app model
 
 builder.Build().Run();
 ```
 
+When you call <xref:Aspire.Hosting.DistributedApplication.CreateBuilder*?displayProperty=nameWithType>, you get an instance of <xref:Aspire.Hosting.IDistributedApplicationBuilder>, which is used to configure your app model. This builder provides methods to add resources, define dependencies, and set up the overall structure of your application. After you've added resources, call `Build` to create the app model. The [templates](../fundamentals/aspire-sdk-templates.md) include code that chains a call to <xref:Aspire.Hosting.IDistributedApplicationBuilder.Build>—which returns an <xref:Aspire.Hosting.DistributedApplication> instance, and then calls <xref:Aspire.Hosting.DistributedApplication.Run>.
+
 ## App host project
 
 The app host project handles running all of the projects that are part of the .NET Aspire project. In other words, it's responsible for orchestrating all apps within the app model. The project itself is a .NET executable project that references the [📦 Aspire.Hosting.AppHost](https://www.nuget.org/packages/Aspire.Hosting.AppHost) NuGet package, and uses the [.NET Aspire SDK](dotnet-aspire-sdk.md):

docs/toc.yml

@@ -7,10 +7,10 @@ items:
   - name: .NET Aspire overview
     displayName: aspire overview,architecture,key concepts,Kubernetes,k8s
     href: get-started/aspire-overview.md
-  - name: Quickstart - Build your first .NET Aspire project
+  - name: Build your first .NET Aspire solution
     displayName: quickstart,first app,aspire app
     href: get-started/build-your-first-aspire-app.md
-  - name: Tutorial - Add .NET Aspire to an existing .NET app
+  - name: Add .NET Aspire to an existing solution
     href: get-started/add-aspire-existing-app.md
   - name: Setup and tooling
     items:
@@ -29,9 +29,12 @@ items:
   - name: Upgrade to .NET Aspire 9.0
     href: get-started/upgrade-to-aspire-9.md
 
-- name: App Host (Dev-time orchestration)
+- name: Dev-time orchestration
   items:
-  - name: Overview
+  - name: Architecture overview
+    displayName: aspire architecture,aspire app,aspire apphost,aspire app model
+    href: architecture/overview.md
+  - name: App host overview
     displayName: orchestration,aspire apphost,aspire app,dev-time,inner-loop
     href: fundamentals/app-host-overview.md
   - name: Locally orchestrate
@@ -45,7 +48,7 @@ items:
     - name: Python apps in .NET Aspire
       displayName: python,flask,fastapi
       href: get-started/build-aspire-apps-with-python.md
-  - name: Configuration
+  - name: App host configuration
     href: app-host/configuration.md
   - name: Customize resources
     items:
@@ -115,13 +118,13 @@ items:
     href: service-discovery/overview.md
   - name: Service defaults
     href: fundamentals/service-defaults.md
-  - name: .NET Aspire and launch profiles
+  - name: Launch profiles
     href: fundamentals/launch-profiles.md
-  - name: Health checks
-    href: fundamentals/health-checks.md
   - name: Telemetry
     displayName: otel,otlp,telemetry,grpc,opentelemetry,protobuf,traceparent
     href: fundamentals/telemetry.md
+  - name: Health checks
+    href: fundamentals/health-checks.md
 
 - name: Integrations
   items:
@@ -371,7 +374,7 @@ items:
   - name: Secure communication between integrations
     href: extensibility/secure-communication-between-integrations.md
 
-- name: Deployment
+- name: Deploy
   items:
   - name: Overview
     displayName: azure deployment,deployment,Kubernetes,k8s
@@ -399,7 +402,8 @@ items:
   - name: Tool-builder manifest schemas
     href: deployment/manifest-format.md
 
-- name: Troubleshooting
+- name: Troubleshoot
+  displayName: troubleshooting
   items:
   - name: Allow unsecure transport
     displayName: unsecure transport,http,non-tls
@@ -500,15 +504,6 @@ items:
   - name: .NET Aspire NuGet profile
     href: https://www.nuget.org/profiles/aspire
 
-- name: Training
-  items:
-  - name: Introduction to .NET Aspire
-    href: /training/modules/introduction-dotnet-aspire
-  - name: Create a .NET Aspire project
-    href: /training/modules/create-aspire-applications
-  - name: Use telemetry in a .NET Aspire project
-    href: /training/modules/use-telemetry-dotnet-aspire
-
 - name: Resources
   items:
   - name: .NET Aspire