## 1. Project Overview & Quickstart (fullstackhero/dotnet-starter-kit)

## File: README.md

---

## 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.

```bash
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 + MinIO
```

> 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. `admin@acme.com` / `Password123!`).

---

## ✨ What's inside

### Backend — modular monolith, vertical slices
- **.NET 10 · C# latest · Minimal APIs · [Mediator](https://github.com/martinothamar/Mediator) (source-generated CQRS) · FluentValidation**
- **EF Core 10** on **PostgreSQL** (Npgsql), with domain events, the specification pattern, soft-delete + audit interceptors, and tenant-isolated `DbContext`s.
- **JWT auth + ASP.NET Identity** — issuance/refresh, roles & fine-grained permissions, rate-limited auth, password policies, sessions, impersonation.
- **Multitenancy** via [Finbuckle](https://www.finbuckle.com/) — tenant resolution, provisioning, per-tenant migrations & seeding, isolation enforced by default.
- **Cross-cutting**: HybridCache on **Valkey** (Redis-compatible), **Hangfire** jobs, presigned S3/**MinIO** storage, 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 7 + TypeScript**, **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, MinIO, 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)

```bash
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:

```bash
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

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

### Option 3 — clone the repo

```bash
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](https://dotnet.microsoft.com/download) · [Docker](https://www.docker.com/) (Postgres/Valkey/MinIO via Aspire) · [Node 20+](https://nodejs.org/) (for the React apps).

**`fsh` commands:** `new` · `doctor` · `info` · `update` · `--version`. Full reference → [fullstackhero.net/docs/cli](https://fullstackhero.net/docs/cli/).

---

## 🧱 Tech stack

| Backend | | Frontend | |
|---|---|---|---|
| Runtime | .NET 10 / C# latest | Framework | React 19 + Vite 7 + TS 5 |
| API | Minimal APIs + Mediator (CQRS) | Data | TanStack Query v5 |
| Validation | FluentValidation | Routing | React Router 7 |
| ORM / DB | EF Core 10 / PostgreSQL | UI | Radix + Tailwind v4 (shadcn) |
| Auth | JWT + ASP.NET Identity | Realtime | SignalR · SSE |
| Multitenancy | Finbuckle 10 | Tests | Playwright |
| Cache / Jobs | Valkey · Hangfire | | |
| Storage | S3 / MinIO (presigned) | **Infra** | |
| Docs | OpenAPI + Scalar | Orchestration | .NET Aspire |
| Observability | Serilog + OpenTelemetry | Deploy | Docker Compose · Terraform |
| Testing | xUnit · Testcontainers · NetArchTest | | |

---

## 🗺️ Repository layout

| Path | What |
|---|---|
| `src/BuildingBlocks/` | Shared framework libraries (Core, Persistence, Web, Caching, Eventing, Storage, Quota…) |
| `src/Modules/{Name}/` | Bounded contexts — each with a runtime project + a `.Contracts` project (its public API) |
| `src/Host/FSH.Starter.Api` | Composition-root Web API host |
| `src/Host/FSH.Starter.AppHost` | .NET Aspire orchestrator (Postgres, Valkey, MinIO, migrator, API, both React apps) |
| `src/Host/FSH.Starter.DbMigrator` | One-shot migrate/seed runner (DB is **not** migrated at API startup) |
| `src/Tools/CLI` | The `fsh` CLI (Spectre.Console) |
| `clients/admin`, `clients/dashboard` | The two React apps |
| `deploy/` | Docker Compose, Terraform (AWS), Dokploy |
| `src/Tests/` | Unit, Architecture (NetArchTest), Integration (Testcontainers) |

Architecture deep-dive → [fullstackhero.net/docs/architecture](https://fullstackhero.net/docs/architecture/).

---

## ☁️ Deploy

**Single-host via Docker Compose:**

```bash
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](https://fullstackhero.net/docs/deployment/aspire/) · [Docker](https://fullstackhero.net/docs/deployment/) · [AWS / Terraform](https://fullstackhero.net/docs/deployment/aws-terraform/) · [Database migrations](https://fullstackhero.net/docs/deployment/database-migrations/).

---

## 🧪 Testing

```bash
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](https://fullstackhero.net)**:

- [Getting started](https://fullstackhero.net/docs/getting-started/introduction/) — scaffold, run, and the default credentials
- [Architecture](https://fullstackhero.net/docs/architecture/) — modular monolith + vertical slices, multitenancy deep-dive
- [Modules](https://fullstackhero.net/docs/modules/) — Identity, Catalog, Tickets, Chat, and more
- [Local orchestration with Aspire](https://fullstackhero.net/docs/deployment/aspire/)
- [CLI reference](https://fullstackhero.net/docs/cli/) · [Changelog](https://fullstackhero.net/docs/changelog/)

---

## 🤝 Contributing

Issues and PRs are welcome — see [`CONTRIBUTING.md`](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`](LICENSE). Built and maintained by [**Mukesh Murugan**](https://codewithmukesh.com) and the FullStackHero community, for teams that want to ship fast without sacrificing architectural discipline.

---

## File: README-template.md

# FSH.Starter

Your application, generated from the **FSH .NET Starter Kit** — a production-ready modular
.NET 10 monolith with two React 19 apps, multitenancy, identity, background jobs, and
cloud-native deploy.

You **own all of this source**. There are no framework NuGet packages to track or upgrade —
the shared code lives in `src/BuildingBlocks` and is yours to change.

## Prerequisites

- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
- [Node.js 20+](https://nodejs.org) — for the React apps
- [Docker](https://www.docker.com/) — Postgres, Redis, MinIO (orchestrated by Aspire)

## Quick start

### Everything at once (recommended) — .NET Aspire

```bash
dotnet run --project src/Host/FSH.Starter.AppHost
```

Aspire starts Postgres, Redis, and MinIO, runs database migrations, then launches the API
**and both React apps**.

| Surface | URL |
|---|---|
| Aspire dashboard | https://localhost:15888 |
| API + Scalar docs | https://localhost:7030/scalar |
| Admin console | http://localhost:5173 |
| Tenant dashboard | http://localhost:5174 |

### Backend only

```bash
dotnet run --project src/Host/FSH.Starter.Api      # needs external Postgres + Redis
```

### Frontend only (against a running API)

```bash
cd clients/admin     && npm install && npm run dev   # → http://localhost:5173
cd clients/dashboard && npm install && npm run dev   # → http://localhost:5174
```

The React apps read their API URL at runtime from `public/config.json` — no rebuild to repoint.

## Project structure

```
src/
  BuildingBlocks/      Shared framework libraries — yours to modify
  Modules/             Bounded contexts: Identity, Multitenancy, Auditing, Billing,
                       Catalog, Chat, Files, Notifications, Tickets, Webhooks
  Host/
    FSH.Starter.Api/                    API composition root
    FSH.Starter.AppHost/                .NET Aspire orchestrator
    FSH.Starter.DbMigrator/             One-shot migrate / seed runner
    FSH.Starter.Migrations.PostgreSQL/  EF Core migrations
  Tests/               Unit, integration (Testcontainers), and architecture tests
clients/
  admin/               Operator console (React 19 + Vite + Tailwind)
  dashboard/           Tenant app (React 19 + Vite + Tailwind, SSE live feed)
deploy/
  docker/              Production docker-compose + .env
  terraform/           AWS infrastructure (ECS, RDS, ElastiCache, S3)
```

## Database

Migrations run automatically under Aspire. To apply them yourself:

```bash
dotnet run --project src/Host/FSH.Starter.DbMigrator -- apply --seed
```

## Make it yours — first-run checklist

This project shipped with sensible defaults. Before production:

- [ ] **Secrets** — set strong values in `deploy/docker/.env` (the `fsh` CLI generates these
      for you; otherwise `cp deploy/docker/.env.example deploy/docker/.env` and fill them in).
      Never commit `.env`.
- [ ] **Logo** — replace `clients/admin/public/logo-fullstackhero.png` and
      `clients/dashboard/public/logo-fullstackhero.png` with your own.
- [ ] **Mail** — configure SMTP / SendGrid under `MailOptions` in
      `src/Host/FSH.Starter.Api/appsettings.json`.
- [ ] **OpenAPI contact** — update `OpenApiOptions.Contact` in `appsettings.json`.
- [ ] **Container registry & infra** — set your registry and review bucket / database names
      in `deploy/terraform/apps/starter/**/variables.tf` and `terraform.tfvars`.

## Production (Docker Compose)

```bash
cd deploy/docker
# .env is generated for you by the fsh CLI; otherwise: cp .env.example .env && edit
docker compose up -d --build
```

Sign in to the admin console as `admin@root.com` using the `SEED_ADMIN_PASSWORD` from your
`.env`, then rotate it from Settings → Security.

## Adding a feature

1. Contracts command/query in `src/Modules/{Module}.Contracts/v1/{Area}/{Feature}/`
2. Handler + FluentValidation validator in `src/Modules/{Module}/Features/...`
3. Endpoint, wired into the module's `MapEndpoints()`
4. Tests

## Running tests

```bash
dotnet test src/FSH.Starter.slnx       # integration tests require Docker
```

## Learn more

- [FSH Documentation](https://fullstackhero.net)
- [Source & issues](https://github.com/fullstackhero/dotnet-starter-kit)

## 2. Official Technical Reference & Guides (fullstackhero/docs)

# FullStackHero Docs

Documentation site for the FullStackHero .NET starter kit. Built with Astro 6 and Tailwind 4.

## Local development

```bash
cd docs
npm install
npm run dev
```

The site runs on `http://localhost:4321`. Edit MDX files under `src/content/docs/` and the dev server hot-reloads. Note that pagefind search is built only by `npm run build`, so the search modal will report "index not available" during `dev`.

## Build

```bash
npm run build      # astro build && pagefind --site dist
npm run preview    # serves dist/ on a local port
```

## Deploy

Cloudflare Pages, configured by `wrangler.toml`. Production branch: `main`. Build command for the Pages dashboard:

```
npm ci && npm run build
```

Output directory: `dist`.

## Content authoring

Add a new doc page by creating an MDX file under `src/content/docs/<section>/`. Frontmatter shape is defined by `src/content.config.ts`:

```yaml
---
title: Page title
sidebar:
  label: Optional override of title in sidebar
  order: 10                    # lower = higher in section
  hidden: false                # exclude from sidebar but still routable
pageType: guide                # guide | reference | concept | recipe
---
```

The sidebar tree is derived from file structure. Section labels and order live in `src/content/docs/_sections.ts`.

## Design system

Tokens, prose styles, and code-block themes are forked verbatim from `codewithmukesh/blog` (see provenance comments in `src/styles/*.css`). Brand primary is `#15803d` (green-700); the user-facing brand green `#16a34a` lives in `--primary-soft` so it surfaces in accent text, tinted backgrounds, and the gradient mid-stop.

## Search

[Pagefind](https://pagefind.app/). Index is generated as a post-build step over the `dist/` HTML. Only `/docs/*` pages are indexed (scoped via `data-pagefind-body` on the docs `<article>`). Trigger via Ctrl/Cmd+K.