Make samples and layout more polyglot

[davidfowl]

Problem

The samples repo still reads and behaves as primarily .NET-solution-centric, even though Aspire is increasingly useful for orchestrating applications across JavaScript/TypeScript, Python, Go, C#, containers, databases, queues, and AI services.

We should make the samples and repo layout communicate that Aspire is a polyglot app orchestration tool, not just a .NET hosting model with occasional non-.NET sidecars.

Proposed changes

1. Rework the root README around a scenario/language matrix with columns for sample, workload languages, AppHost language, deploy target, and description.
2. Make TypeScript/file-based AppHosts first-class in the layout and CI, especially samples using apphost.ts, aspire.config.json, and root package.json scripts.
3. Standardize newer polyglot samples around clear workload folders such as frontend, api, worker-python, worker-csharp, and worker-go.
4. Keep C# solution-style samples where they are intentionally .NET-focused, but avoid making that the default visual model for every sample.
5. Promote or add representative polyglot samples, including:
   • Node + Redis + Vite
   • Vite + React + FastAPI
   • Python FastAPI + PostgreSQL
   • Go API
   • C# API + JavaScript frontend + PostgreSQL
   • Polyglot task queue with Node, Python, C#, and RabbitMQ
   • RAG sample with Python API and JavaScript/Svelte frontend
6. Extend build/test coverage so file-based TypeScript AppHosts are validated alongside *.AppHost.csproj samples.
7. Consider adding per-sample metadata for languages, AppHost runtime, deployment support, and backing services so the README table can be generated or validated.

Desired outcome

A new visitor should be able to quickly see that Aspire supports real apps composed from multiple languages and runtimes. The repository should make polyglot workflows feel first-class in both documentation and validation, while still preserving strong .NET-focused samples where appropriate.

Layout proposal

For approachability, avoid deeply nested language folders. Keep samples/ mostly flat, and use README sections, sample.json metadata, and the aspire.dev sample browser for grouping/filtering.

samples/
  node-express-redis/
  vite-yarp-static/
  vite-react-fastapi/
  vite-csharp-postgres/
  polyglot-task-queue/
  python-fastapi-postgres/
  python-openai-agent/
  python-script/
  golang-api/
  container-build/
  rag-document-qa-svelte/
  image-gallery/
  aspire-shop/
  database-containers/
  database-migrations/
  health-checks-ui/
  orleans-voting/
  client-apps-integration/
  custom-resources/
  volume-mount/

Inside each sample, standardize around app roles rather than language-specific conventions:

sample-name/
  README.md
  sample.json
  apphost.ts | apphost.cs | Sample.AppHost/
  aspire.config.json
  package.json

  frontend/
  api/
  worker/
  worker-python/
  worker-csharp/
  infra/
  images/

Why this layout

• Flat samples/ stays approachable: users do not have to guess whether a React + FastAPI sample belongs under full-stack, python, or polyglot.
• Grouping moves to metadata/browser/README: the same sample can appear under Python, full-stack, AI, and Docker Compose without duplicating folders.
• Sample internals become predictable: frontend/, api/, worker-*, infra/, and images/ mean the same thing across languages.
• Renames are minimized: fewer broken links, easier migration, and less churn.

Only introduce top-level folders if the repo grows much larger. Even then, prefer shallow buckets such as:

samples/
  apps/
  integrations/
  platform/

For now, flat samples plus consistent internal conventions is the most approachable polyglot layout.

README approachability proposal

The repo README should be approachable first and exhaustive second. It should not start with taxonomy or a full catalog. Start with "What should I try?" and guide users to a few representative samples.

Suggested opening shape:

## Start here

New to Aspire? Try one of these first:

| I want to... | Try this sample | What it shows |
| --- | --- | --- |
| Run a JavaScript full-stack app | Node + Redis + Vite | React/Vite frontend, Node API, Redis, Docker Compose |
| Connect a Python API to a frontend | Vite + React + FastAPI | React frontend, FastAPI backend, YARP |
| See multiple languages working together | Polyglot Task Queue | Node API, Python worker, C# worker, RabbitMQ |
| Learn a .NET reference app | Aspire Shop | C# services, PostgreSQL, Redis |
| Explore AI app patterns | RAG Document Q&A | Svelte, FastAPI, Qdrant, OpenAI |

Then link to the Aspire sample browser for deeper discovery:

Looking for more? Use the Aspire sample browser to filter by language, service, scenario, and deployment target.

After that, include compact scenario sections or tables for repo navigation. The principle is: do not make a new visitor understand the whole repo structure before they can choose a sample.