react-dotnet-framework/AGENTS.md

AGENTS.md

Skeleton monorepo for React + .NET projects. Clone it, then replace the placeholder User domain with the real one.

Layout

backend/    ASP.NET Core Web API (net10.0)
frontend/   Vite + React + TypeScript SPA

Running

Stack	Command	URL
Backend	cd backend && dotnet run	http://localhost:5231
Frontend	cd frontend && npm install && npm run dev	http://localhost:3000

Start them in separate terminals. Allowed CORS origins live in backend/appsettings.json under Cors:AllowedOrigins.

Verifying changes

Run these before considering a change done:

cd backend && dotnet build
cd frontend && npm run build && npm run lint

Backend conventions

• ImplicitUsings is enabled. Do not re-import Microsoft.AspNetCore.*, Microsoft.Extensions.DependencyInjection, System.Linq, and friends.
• Use file-scoped namespaces (namespace Backend.Data;).
• Repository methods are async, suffixed Async, and take a CancellationToken.
• Read configuration through the options pattern (IOptions<T> + Configure<T>), not Configuration["Some:Key"].
• Controllers stay thin: validate, delegate to a repository or service, map the result to an IActionResult. No data access in controllers.
• Route templates use ApiRoutes.V1 rather than a hardcoded "v1" string.
• Cross-cutting pipeline concerns (CORS, rate limiting) belong in backend/Gateway/ and are wired through AddApiGateway / UseApiGateway, not inline in Program.cs.
• Persistence implementations register through AddPersistence, selected by the Persistence:Provider setting. Swapping in EF Core or another store should not require touching controllers.

Frontend conventions

• All HTTP goes through src/api/. Components never call fetch directly.
• Configuration comes from VITE_* environment variables; VITE_API_BASE_URL points at the backend. Add new variables to .env.example and to the ImportMetaEnv interface in src/vite-env.d.ts.
• TypeScript is strict and unused locals are errors. The build runs tsc -b before Vite.

Endpoints

Method	Path	Purpose
GET	/health	Liveness check, unversioned for infrastructure
GET	/v1/info	App name, version, environment, server timestamp
GET	/v1/users	List users
GET	/v1/users/{id}	Fetch one user
POST	/v1/users	Create a user
PUT	/v1/users/{id}	Replace a user
DELETE	/v1/users/{id}	Delete a user

Sample requests live in backend/backend.http.

Not included on purpose

Authentication, a real database provider, tests, Docker, and structured logging are all left out. Add them when the project has requirements that justify a specific choice.