75 lines
2.7 KiB
Markdown
75 lines
2.7 KiB
Markdown
# 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.
|