# 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.