slp-modular-cms/aidlc-docs/features/cms-frontend/construction/unit-0/nfr-requirements/tech-stack-decisions.md

Tech Stack Decisions — Unit 0: Backend Prerequisites

Existing Stack (no changes)

All existing technology choices are retained:

• .NET 10 / ASP.NET Core 10 — Web API framework
• Entity Framework Core 10 — ORM + migrations
• ASP.NET Core Identity — User/role management, password hashing
• SQL Server — Primary database

---

New/Updated: Rate Limiting

Decision	Choice	Rationale
Rate limiter	ASP.NET Core built-in RateLimiter (Microsoft.AspNetCore.RateLimiting)	No extra NuGet package needed — available in .NET 7+; production-ready
Login policy	Fixed window (5 req / 1 min / IP)	Predictable; blocks brute-force login attempts
Refresh policy	Sliding window (20 req / 1 min / IP)	More lenient for token rotation; prevents abuse
Configuration	appsettings.json → RateLimiting	Configurable without code recompile

---

New/Updated: CORS

Decision	Choice	Rationale
CORS implementation	ASP.NET Core built-in CORS middleware	No extra NuGet package; part of framework
Origins configuration	appsettings.json → Cors:AllowedOrigins[]	Environment-specific; follows dotnet-appsettings pattern
Credential support	AllowCredentials()	Required for httpOnly cookie to be sent cross-origin
Methods	AllowAnyMethod()	Avoids future CORS issues when new endpoints are added
Headers	AllowAnyHeader()	Standard approach; avoids pre-flight failures for custom headers

---

New/Updated: httpOnly Cookie

Decision	Choice	Rationale
Cookie implementation	ASP.NET Core Response.Cookies.Append()	Built-in, no extra library
Token read	Request.Cookies["refreshToken"]	Standard ASP.NET Core cookie reading
Secure flag	request.IsHttps	Adapts to environment; safe in production, usable in local HTTP dev
SameSite	Strict	Maximum CSRF protection

---

New/Updated: Error Responses

Decision	Choice	Rationale
Error format	RFC 9457 ProblemDetails	.NET standard; consistent with ASP.NET Core defaults; interoperable
Implementation	Microsoft.AspNetCore.Mvc.ProblemDetails (built-in)	No extra NuGet package needed
Global handler	Existing GlobalExceptionHandler extended	Avoids duplication; centralises error formatting

---

appsettings.json Additions

Following the dotnet-appsettings skill pattern:

// appsettings.json (production defaults — no real values)
{
  "Cors": {
    "AllowedOrigins": []
  },
  "RateLimiting": {
    "Login": {
      "PermitLimit": 5,
      "WindowSeconds": 60
    },
    "Refresh": {
      "PermitLimit": 20,
      "WindowSeconds": 60
    }
  }
}

// appsettings.Development.json (complete reference for developers)
{
  "Cors": {
    "AllowedOrigins": ["http://localhost:5173"]
  },
  "RateLimiting": {
    "Login": {
      "PermitLimit": 5,
      "WindowSeconds": 60
    },
    "Refresh": {
      "PermitLimit": 20,
      "WindowSeconds": 60
    }
  }
}

// appsettings.local.json (developer override — gitignored)
{
  "Cors": {
    "AllowedOrigins": ["http://localhost:5173"]
  }
}