FullStackHero 10 .NET Starter Kit Release Merge

.agents/rules/api-conventions.md

@@ -0,0 +1,65 @@
+---
+paths:
+  - "src/Modules/**/Features/**/*"
+  - "src/Modules/**/*Endpoint*.cs"
+---
+
+# API Conventions
+
+Rules for API endpoints in FSH.
+
+## Endpoint Requirements
+
+Every endpoint MUST have:
+
+```csharp
+endpoints.MapPost("/", handler)
+    .WithName(nameof(CommandOrQuery))      // Required: Unique name
+    .WithSummary("Description")             // Required: OpenAPI description
+    .RequirePermission(Permission)          // Required: Or .AllowAnonymous()
+```
+
+## HTTP Method Mapping
+
+| Operation | Method | Return |
+|-----------|--------|--------|
+| Create | `MapPost` | `TypedResults.Created(...)` |
+| Read single | `MapGet` | `TypedResults.Ok(...)` |
+| Read list | `MapGet` | `TypedResults.Ok(...)` |
+| Update | `MapPut` | `TypedResults.Ok(...)` or `NoContent()` |
+| Delete | `MapDelete` | `TypedResults.NoContent()` |
+
+## Route Patterns
+
+```
+/api/v1/{module}/{entities}           # Collection
+/api/v1/{module}/{entities}/{id}      # Single item
+/api/v1/{module}/{entities}/{id}/sub  # Sub-resource
+```
+
+## Response Types
+
+Always use `TypedResults`:
+- `TypedResults.Ok(data)`
+- `TypedResults.Created($"/path/{id}", data)`
+- `TypedResults.NoContent()`
+- `TypedResults.NotFound()`
+- `TypedResults.BadRequest(errors)`
+
+Never return raw objects or use `Results.Ok()`.
+
+## Permission Format
+
+```csharp
+.RequirePermission({Module}Permissions.{Entity}.{Action})
+```
+
+Actions: `View`, `Create`, `Update`, `Delete`
+
+## Query Parameters
+
+Use `[AsParameters]` for complex queries:
+
+```csharp
+endpoints.MapGet("/", async ([AsParameters] GetProductsQuery query, ...) => ...)
+```

.agents/rules/architecture.md

@@ -0,0 +1,247 @@
+---
+paths:
+  - "src/**"
+---
+
+# Architecture Rules
+
+FSH is a **Modular Monolith** — NOT microservices, NOT a traditional layered architecture.
+
+## Core Principles
+
+### 1. Modular Monolith
+
+```
+Single deployment unit
+    ↓
+Multiple bounded contexts (modules)
+    ↓
+Each module is self-contained
+    ↓
+Communication via Contracts (interfaces/DTOs)
+```
+
+**Modules:**
+- Identity (users, roles, permissions)
+- Multitenancy (tenants, subscriptions)
+- Auditing (audit trails)
+- Your business modules (e.g., Catalog, Orders)
+
+**Rules:**
+- Modules CANNOT reference other module internals
+- Modules CAN reference other module Contracts
+- Modules share BuildingBlocks (framework code)
+
+### 2. CQRS (Mediator Library)
+
+**Commands** (write operations):
+```csharp
+public record CreateUserCommand(string Email) : ICommand<Guid>;
+
+public class CreateUserHandler : ICommandHandler<CreateUserCommand, Guid>
+{
+    public async ValueTask<Guid> Handle(CreateUserCommand cmd, CancellationToken ct)
+    {
+        // Write to database
+        return user.Id;
+    }
+}
+```
+
+**Queries** (read operations):
+```csharp
+public record GetUserQuery(Guid Id) : IQuery<UserDto>;
+
+public class GetUserHandler : IQueryHandler<GetUserQuery, UserDto>
+{
+    public async ValueTask<UserDto> Handle(GetUserQuery query, CancellationToken ct)
+    {
+        // Read from database
+        return userDto;
+    }
+}
+```
+
+⚠️ **NOT MediatR:** FSH uses `Mediator` library (different interfaces!)
+
+### 3. Domain-Driven Design
+
+**Entities** inherit `BaseEntity`:
+```csharp
+public class Product : BaseEntity, IAuditable
+{
+    public string Name { get; private set; } = default!;
+    public Money Price { get; private set; } = default!;
+
+    public static Product Create(string name, Money price)
+    {
+        // Factory method, enforce invariants
+        return new Product { Name = name, Price = price };
+    }
+}
+```
+
+**Value Objects** (immutable):
+```csharp
+public record Money(decimal Amount, string Currency);
+```
+
+**Aggregates:**
+- Root entity controls access to child entities
+- Enforce business rules
+- Transaction boundary
+
+### 4. Multi-Tenancy
+
+**Finbuckle.MultiTenant:**
+- Shared database, tenant isolation via TenantId
+- Automatic query filtering
+- Tenant resolution from HTTP header or claim
+
+```csharp
+// Tenant-aware entity
+public class Order : BaseEntity, IMustHaveTenant
+{
+    public Guid TenantId { get; set; }  // Auto-filtered
+}
+```
+
+**Tenant Resolution Order:**
+1. HTTP header: `X-Tenant`
+2. JWT claim: `tenant`
+3. Host/route strategy (optional)
+
+### 5. Vertical Slice Architecture
+
+Each feature = complete slice (command/handler/validator/endpoint in one folder).
+
+```
+Features/v1/CreateProduct/
+├── CreateProductCommand.cs
+├── CreateProductHandler.cs
+├── CreateProductValidator.cs
+└── CreateProductEndpoint.cs
+```
+
+**Benefits:**
+- High cohesion (related code together)
+- Low coupling (features don't depend on each other)
+- Easy to find/modify
+
+### 6. BuildingBlocks (Shared Kernel)
+
+11 packages providing cross-cutting concerns:
+
+| Package | Purpose |
+|---------|---------|
+| Core | Base entities, interfaces, exceptions |
+| Persistence | EF Core, repositories, specifications |
+| Caching | Redis/memory caching |
+| Mailing | Email templates, MailKit integration |
+| Jobs | Hangfire background jobs |
+| Storage | File storage (AWS S3, local) |
+| Web | API conventions, filters, middleware |
+| Eventing | Domain events, message bus |
+| Blazor.UI | UI components (optional) |
+| Shared | DTOs, constants |
+| Eventing.Abstractions | Event contracts |
+
+**Protected:** BuildingBlocks should NOT be modified without approval. See `.claude/rules/buildingblocks-protection.md`.
+
+### 7. Dependency Flow
+
+```
+API Layer (Minimal APIs)
+    ↓
+Application Layer (Commands/Queries/Handlers)
+    ↓
+Domain Layer (Entities/Value Objects)
+    ↓
+Infrastructure Layer (Persistence/External Services)
+```
+
+**Rules:**
+- Domain CANNOT depend on infrastructure
+- Application CANNOT depend on infrastructure directly
+- Infrastructure implements domain interfaces
+
+### 8. Persistence Strategy
+
+**DbContext per Module:**
+- IdentityDbContext
+- MultitenancyDbContext
+- AuditingDbContext
+- Your module DbContexts
+
+**Repository Pattern:**
+```csharp
+public interface IRepository<T> where T : BaseEntity
+{
+    Task<T?> GetByIdAsync(Guid id, CancellationToken ct);
+    Task<List<T>> ListAsync(Specification<T> spec, CancellationToken ct);
+    Task<T> AddAsync(T entity, CancellationToken ct);
+    Task UpdateAsync(T entity, CancellationToken ct);
+    Task DeleteAsync(T entity, CancellationToken ct);
+}
+```
+
+**Specification Pattern** (queries):
+```csharp
+public class ActiveProductsSpec : Specification<Product>
+{
+    public ActiveProductsSpec()
+    {
+        Query.Where(p => !p.IsDeleted && p.IsActive);
+    }
+}
+```
+
+## Architectural Tests
+
+`Architecture.Tests` project enforces rules:
+
+```csharp
+[Fact]
+public void Modules_Should_Not_Reference_Other_Modules()
+{
+    // Fails if Module A references Module B directly
+}
+
+[Fact]
+public void Domain_Should_Not_Depend_On_Infrastructure()
+{
+    // Fails if domain entities reference EF Core
+}
+```
+
+## Technology Stack
+
+- **.NET 10** (latest LTS)
+- **EF Core 10** (PostgreSQL provider)
+- **Mediator** (CQRS)
+- **FluentValidation** (input validation)
+- **Mapster** (object mapping)
+- **Hangfire** (background jobs)
+- **Finbuckle.MultiTenant** (multi-tenancy)
+- **MailKit** (email)
+- **Scalar** (OpenAPI docs)
+- **Serilog** (logging)
+- **OpenTelemetry** (observability)
+- **Aspire** (orchestration)
+
+## Key Takeaways
+
+1. **Modular Monolith** ≠ Microservices. Modules share process, database, infrastructure.
+2. **CQRS** separates reads/writes. Use `ICommand`/`IQuery`, not `IRequest`.
+3. **DDD** enforces business rules in domain. Entities control their state.
+4. **Multi-Tenancy** is built-in. Every entity is either tenant-aware or shared.
+5. **Vertical Slices** keep features independent. No shared "services" layer.
+6. **BuildingBlocks** provide infrastructure. Don't reinvent, reuse.
+7. **Tests enforce architecture**. Violate rules → build fails.
+
+---
+
+For implementation details, see:
+- `ARCHITECTURE_ANALYSIS.md` (deep dive)
+- `.claude/rules/modules.md` (module patterns)
+- `.claude/rules/persistence.md` (data access patterns)

.agents/rules/buildingblocks-protection.md

@@ -0,0 +1,36 @@
+---
+paths:
+  - "src/BuildingBlocks/**/*"
+---
+
+# ⚠️ BuildingBlocks Protection
+
+**STOP. You are modifying BuildingBlocks.**
+
+Changes to BuildingBlocks affect ALL modules across the entire framework. These are core abstractions that many projects depend on.
+
+## Before Proceeding
+
+1. **Confirm explicit approval** - Has the user specifically approved this change?
+2. **Consider alternatives** - Can this be done in the module instead?
+3. **Assess impact** - What modules will this affect?
+
+## If Approved
+
+- Make minimal, focused changes
+- Ensure backward compatibility
+- Update all affected modules
+- Run full test suite: `dotnet test src/FSH.Framework.slnx`
+- Document the change
+
+## Alternatives to Consider
+
+| Instead of... | Consider... |
+|---------------|-------------|
+| Modifying Core | Extension method in module |
+| Changing Persistence | Custom repository in module |
+| Updating Web | Module-specific middleware |
+
+## If Not Approved
+
+Do not proceed. Suggest alternatives that don't require BuildingBlocks modifications.