dotnet-starter-kit

Why FullStackHero?

Most starter kits give you a login page and a TODO list. This one gives you the boring, hard parts already done right — multitenancy, auth, billing, auditing, background jobs, real-time, file storage, observability — across a clean Vertical Slice backend and two polished React 19 front-ends, orchestrated locally with one command via .NET Aspire, and deployable to Docker or AWS.

You scaffold with the fsh CLI and get the complete, detached source — every BuildingBlock, Module, and Host project with real project references. No hidden NuGet runtime, nothing to “eject” later. Own it, read it, change it.

dotnet tool install -g FullStackHero.CLI
fsh new MyApp
cd MyApp
dotnet run --project src/Host/MyApp.AppHost   # 🎉 whole stack up: API + 2 React apps + Postgres + Valkey + RustFS

Then open the Aspire dashboard at https://localhost:15888, the API + Scalar docs at https://localhost:7030/scalar, the admin app at http://localhost:5173, and the dashboard app at http://localhost:5174. Sign in with a seeded demo account (e.g. [email protected] / Password123!).

✨ What’s inside

Backend — modular monolith, vertical slices

• .NET 10 · C# latest · Minimal APIs · Mediator (source-generated CQRS) · FluentValidation
• EF Core 10 on PostgreSQL (Npgsql), with domain events, the specification pattern, soft-delete + audit interceptors, and tenant-isolated DbContexts.
• JWT auth + ASP.NET Identity — issuance/refresh, roles & fine-grained permissions, rate-limited auth, password policies, sessions, impersonation.
• Multitenancy via Finbuckle — tenant resolution, provisioning, per-tenant migrations & seeding, isolation enforced by default.
• Cross-cutting: HybridCache on Valkey (Redis-compatible), Hangfire jobs, presigned S3 storage (RustFS locally), mailing, idempotency, quotas, rate limiting, API versioning, RFC 9457 ProblemDetails.
• Observability: Serilog structured logging + OpenTelemetry traces/metrics/logs, health probes, security/exception auditing.
• Docs: OpenAPI + the Scalar API reference UI.

Front-ends — two React 19 apps

• clients/admin (operator console) and clients/dashboard (tenant app): React 19 + Vite 8 + TypeScript 6, TanStack Query v5, React Router 7, Radix + Tailwind v4 (shadcn-style), real-time via SignalR/SSE.
• Runtime config (/config.json, no rebuild per environment), hand-written typed API client, and Playwright E2E suites.

Modules (bounded contexts)

Identity · Multitenancy · Billing · Catalog · Tickets · Chat · Files · Webhooks · Auditing · Notifications — each a runtime project plus a .Contracts project (its only public surface), boundaries enforced by architecture tests.

Cloud-native & DevOps

• .NET Aspire orchestrates the entire stack locally with one command (Postgres + pgAdmin, Valkey + RedisInsight, RustFS, migrator, demo-seeder, API, and both React apps).
• Docker Compose production stack (deploy/docker) and Terraform for AWS (deploy/terraform); API image published to GHCR.
• A one-shot DbMigrator (migrations are never run at API startup), and the fsh CLI + dotnet new template for distribution.

Quality

1,600+ backend tests (xUnit, Shouldly, NSubstitute, AutoFixture, NetArchTest boundaries, Testcontainers integration) and 200+ front-end E2E tests (Playwright). Path-scoped CI for backend and frontend; warnings-as-errors.

🚀 Getting started

Option 1 — the fsh CLI (recommended)

dotnet tool install -g FullStackHero.CLI
fsh doctor          # verify your environment (SDK, Docker, Aspire, ports)
fsh new MyApp       # interactive wizard

The wizard asks what to include (Aspire AppHost, the React apps). Non-interactive:

fsh new MyApp --non-interactive          # full stack, Postgres
fsh new MyApp --no-frontend              # backend-only
fsh new MyApp --no-aspire --no-frontend  # minimal API + migrator

Option 2 — the dotnet new template

dotnet new install FullStackHero.NET.StarterKit
dotnet new fsh -n MyApp

Option 3 — clone the repo

git clone https://github.com/fullstackhero/dotnet-starter-kit.git MyApp && cd MyApp
dotnet run --project src/Host/FSH.Starter.AppHost

Prerequisites: .NET 10 SDK · Docker (Postgres/Valkey/RustFS via Aspire) · Node 20.19+ or 22.13+ (for the React apps).

fsh commands: new · doctor · info · update · --version. Full reference → fullstackhero.net/docs/cli.

🧱 Tech stack

🗺️ Repository layout

Architecture deep-dive → fullstackhero.net/docs/architecture.

☁️ Deploy

Single-host via Docker Compose:

cd deploy/docker
cp .env.example .env   # fsh new pre-generates this with strong secrets
docker compose up -d --build

AWS via Terraform (ECS Fargate + RDS + ElastiCache + S3/CloudFront) lives in deploy/terraform.

Guides → Local orchestration · Docker · AWS / Terraform · Database migrations.

🧪 Testing

dotnet test src/FSH.Starter.slnx        # backend: unit + architecture + Testcontainers integration
cd clients/admin     && npm run test:e2e # Playwright (operator app)
cd clients/dashboard && npm run test:e2e # Playwright (tenant app)

Integration tests require Docker (Testcontainers spins real Postgres). Architecture tests enforce module boundaries.

📖 Documentation

Full guides, module references, and architecture decisions live at fullstackhero.net:

• Getting started — scaffold, run, and the default credentials
• Architecture — modular monolith + vertical slices, multitenancy deep-dive
• Modules — Identity, Catalog, Tickets, Chat, and more
• Local orchestration with Aspire
• CLI reference · Changelog

🤝 Contributing

Issues and PRs are welcome — see CONTRIBUTING.md. Branch from and target main; CI runs path-scoped backend + frontend pipelines, and stable releases are cut from v* tags.

📄 License

MIT — see LICENSE. Built and maintained by Mukesh Murugan and the FullStackHero community, for teams that want to ship fast without sacrificing architectural discipline.