aspire-orchestration

name: aspire-orchestration description: "Use when touching AllProjects.AppHost/Program.cs, debugging service startup, or onboarding a new dependency. Knows GA's Aspire AppHost topology (MongoDB, Redis, FalkorDB, GaApi, microservices, ga-client, MCP, Python sidecars), how connection strings flow via WithReference, and how to add new .NET projects, Python containers, or infrastructure resources. Invoke for Aspire, AppHost, DistributedApplication, AddProject, AddRedis, AddMongoDB, WithReference, start-all.ps1, Aspire dashboard." license: MIT metadata: version: "1.0.0" domain: orchestration triggers: Aspire, AppHost, AllProjects.AppHost, DistributedApplication, AddProject, AddRedis, AddMongoDB, WithReference, start-all.ps1, Aspire dashboard role: specialist last_verified: 2026-05-06 verified_against: "AllProjects.AppHost/Program.cs (.NET 10, Aspire 9.x)"

Aspire Orchestration

Use this skill when you need to add a service to the AppHost, debug why something fails to start, understand how connection strings flow, or explain the topology to someone new.

What Aspire owns in this repo

AllProjects.AppHost/Program.cs is the single source of truth for how the GA backend stack runs locally. Aspire builds a DistributedApplication that orchestrates every service Guitar Alchemist needs — infrastructure containers, .NET projects, the React frontend, the MCP server, and Python sidecars — and exposes the Aspire dashboard at https://localhost:15001 for live status, logs, traces, and resource URLs.

The dashboard is the canonical place to discover ports, follow logs, and trigger restarts. Don't hardcode service URLs in client code or skill docs — read them from the dashboard or the configuration injected at runtime.

Service inventory (current)

Several other microservices (bsp-service, ai-service, knowledge-service, fretboard-service, analytics-service) are scaffolded but commented out in Program.cs until their implementations land. If you uncomment one, also add it to GaApi's .WithReference(...) chain so the gateway can route to it.

How to start everything

# Build + start all services (default)
pwsh Scripts/start-all.ps1 -Dashboard

# Start without rebuilding (daily dev)
pwsh Scripts/start-all.ps1 -NoBuild -Dashboard

The -Dashboard switch opens the Aspire dashboard in your browser. Without it, services still start; you'd just open https://localhost:15001 manually.

How connection strings flow

Aspire injects connection strings as environment variables of the form ConnectionStrings__<resource-name>:

• A reference to mongodb's database (AddDatabase("guitar-alchemist")) becomes ConnectionStrings__guitar-alchemist
• A reference to redis becomes ConnectionStrings__redis

Inside a referenced project, read them via IConfiguration.GetConnectionString("guitar-alchemist") or DI'd IOptions<...>. Never hardcode the MongoDB URL, port, or database name — Aspire chooses dynamic ports for the underlying container, and hardcoded values will randomly break across restarts.

Adding a new service

The dispatch to use depends on what kind of service you're adding:

A new .NET project

var newService = builder.AddProject("my-service", @"..\Apps\ga-server\My.Service\My.Service.csproj")
    .WithReference(mongoDatabase)        // any infra it needs
    .WithReference(redis)
    .WithExternalHttpEndpoints();        // makes its URL discoverable from the dashboard

Then if other services need to call it, add .WithReference(newService) to their AddProject calls. Almost always gaapi needs the new reference if the service is user-facing (gateway routes through it).

A new Python container

builder.AddContainer("my-py-service", "my-py-service")
    .WithDockerfile("../Apps/my-py-service")           // path relative to AppHost
    .WithHttpEndpoint(8083, 8080, "http")              // host port 8083, container port 8080
    .WithEnvironment("PORT", "8080")
    .WithReference(mongoDatabase)                       // injects ConnectionStrings__guitar-alchemist
    .WithExternalHttpEndpoints();

Pick a host port that doesn't collide with existing ones (8000 graphiti, 8081 hand-pose, 8082 sound-bank).

A new infrastructure container

Use the Aspire Add* extensions where one exists (AddRedis, AddMongoDB, AddPostgres, etc.). For anything else, fall back to AddContainer with an explicit image name + port mapping, like falkordb.

Common failure modes

What NOT to do

• Don't add Aspire references in service code. A service should not import the AppHost project. Cross-service contracts are HTTP/gRPC, not in-process.
• Don't run GaApi from a Docker image when developing locally. GaApi is a .NET project Aspire orchestrates as a process. Containerized GaApi belongs in the production deployment story, not the dev loop.
• Don't put Ollama in the AppHost. Ollama runs natively at localhost:11434 per the chat skill — it's not Aspire-orchestrated.
• Don't hardcode dynamic ports in tests, frontend code, or skill docs. Read them from the dashboard or environment.

Pointers

• AppHost: AllProjects.AppHost/Program.cs
• Startup script: Scripts/start-all.ps1
• Aspire docs: learn.microsoft.com/dotnet/aspire
• Related skills: chat (uses Aspire to start the chatbot), dotnet-core-expert (broader .NET guidance), optic-k-rebuild (touches the data layer Aspire orchestrates)