# System Architecture & Invariants: .NET 10 & C# 14 Minimal APIs Specialist

## 1. System Overview
Production guidelines for .NET 10 (LTS) and C# 14. Enforces Minimal APIs, primary constructors, collection expressions, file-scoped namespaces, and EF Core 10 query optimization.
All AI agents operating within this repository must adhere strictly to these architectural boundaries.

### Technology Stack
- **Framework**: ASP.NET Core 10 Minimal APIs
- **Language Standard**: C# 14 (.NET 10 SDK)
- **UI & Styling**: None / API Service
- **Data Persistence**: PostgreSQL / SQL Server / EF Core 10
- **Engineering Philosophy**: modern

## 2. Core Architectural Invariants
- **Clean Layered Architecture**: Decouple presentation, business logic, and data access layers via interfaces.
- **Guard Clauses & Early Returns**: Exit early from functions to eliminate deeply nested if-else pyramids.
- **Schema-Driven Boundaries**: Validate all external data (API, forms, env) with Zod or Pydantic schemas; on failure, reject with a typed error and never pass unvalidated data onward.

## 3. Data Flow & State Management Principles
1. **Unidirectional Data Flow**: State flows top-down; mutations flow through explicit, typed handlers.
2. **Boundary Validation**: External inputs (API payloads, query parameters, environment variables) must be parsed with strict schemas before reaching domain logic.
3. **Surgical Precision**: Diffs must remain minimal and scoped exclusively to the objective. Do not reformat unrelated code.

## 4. Forbidden Anti-Patterns & Operational Guardrails
- **Inspect Before Acting**: Always read and understand existing code and imports before suggesting changes.
- **Minimal Surgical Diffs**: Touch only lines relevant to prompt. Preserve existing comments and formatting.
- **Propose Verification Steps**: With every modification, specify concrete commands or tests to verify correctness.

## 5. Domain-Specific Invariants
- Enable '#nullable enable' across all C# project files.
- Return explicit IResult types (TypedResults.Ok, TypedResults.NotFound) rather than untyped object responses.

## 6. Implementation Reference Patterns

### Preferred Pattern
```ts
namespace App.Features.Users;

using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.EntityFrameworkCore;

public record UserDto(Guid Id, string Email, string FullName);

public static class UserEndpoints
{
    public static RouteGroupBuilder MapUserEndpoints(this RouteGroupBuilder group)
    {
        group.MapGet("/{id:guid}", async Task<Results<Ok<UserDto>, NotFound>> (Guid id, AppDbContext db) =>
        {
            var user = await db.Users
                .AsNoTracking()
                .Where(u => u.Id == id)
                .Select(u => new UserDto(u.Id, u.Email, u.FullName))
                .FirstOrDefaultAsync();

            return user is not null ? TypedResults.Ok(user) : TypedResults.NotFound();
        });
        return group;
    }
}
```

### Forbidden Anti-Pattern
```ts
namespace App.Controllers
{
    public class UsersController : Controller
    {
        [HttpGet]
        public IActionResult GetUser(Guid id)
        {
            var user = _context.Users.Find(id); // Untracked query loading full entity graph into tracker
            return Ok(user);
        }
    }
}
```

## 7. Verification Protocol
Before finalizing any implementation:
1. Use current C# features where they make code clearer: primary constructors, collection expressions, file-scoped namespaces, and C# 14's field keyword, extension members and null-conditional assignment (customer?.Order = ...).
2. Structure high-performance microservices using ASP.NET Core Minimal APIs with TypedResults.
3. Enforce AsNoTracking() on read-only EF Core queries to eliminate change tracking memory overhead.
4. Validate incoming request payloads with FluentValidation or MiniValidation before executing queries.
5. Configure resilient outgoing HTTP requests via IHttpClientFactory and Polly pipelines.