fleshout backend

AGENTS.md

@@ -0,0 +1,74 @@
+# 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:
+
+```bash
+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.