another step just a little remaining
This commit is contained in:
hamid
+8
-156
@@ -1,161 +1,13 @@
|
||||
# AGENTS.md — Balinyaar Server
|
||||
|
||||
> **Coding rules** are in [CONVENTIONS.md](CONVENTIONS.md) — read it before writing any server code.
|
||||
The canonical agent guide for the backend is **[CLAUDE.md](CLAUDE.md)** (same folder): role, stack,
|
||||
commands, architecture, project map, and a conventions quick-reference.
|
||||
|
||||
---
|
||||
The **full coding rule set** is in **[CONVENTIONS.md](CONVENTIONS.md)** — read it before writing any
|
||||
server code.
|
||||
|
||||
## Role
|
||||
- Repo-wide context → [../CLAUDE.md](../CLAUDE.md)
|
||||
- Human setup/run instructions → [README.md](README.md)
|
||||
|
||||
You are a **senior .NET software engineer** working on this codebase. That means:
|
||||
|
||||
- You write production-quality code, not demo code. Every file you touch should look like it was written by someone who has shipped .NET APIs at scale.
|
||||
- You understand the architecture and work _with_ it, not around it. Clean Architecture boundaries are non-negotiable.
|
||||
- You think before you write. If a task is ambiguous, reason through the design first. If it requires touching a contract that other layers depend on, think about the downstream impact.
|
||||
- You prefer simplicity and clarity over cleverness. The next engineer (or agent) should be able to read your code without a guide.
|
||||
- You never leave the codebase in a worse state than you found it. If you touch a file, leave it at least as clean as it was.
|
||||
|
||||
---
|
||||
|
||||
## Stack
|
||||
|
||||
- **ASP.NET Core / .NET 10** (`net10.0`), Web API
|
||||
- **Clean Architecture** (Domain → Application → Infrastructure → API)
|
||||
- **CQRS** with **Mediator** (`martinothamar/Mediator` — source-generator based, not MediatR)
|
||||
- **EF Core 10** + **SQL Server** (Repository + Unit of Work pattern)
|
||||
- **ASP.NET Core Identity** with **JWE** (signed + AES-128-encrypted JWT), OTP, and dynamic permission authorization
|
||||
- **Mapster** for mapping, **FluentValidation** for validation, **Serilog** for structured logging
|
||||
- **OpenTelemetry** + **prometheus-net** for observability, **NSwag** for OpenAPI, **Asp.Versioning** for versioning
|
||||
- **xUnit** + **NSubstitute** for tests
|
||||
- All NuGet versions centrally pinned in `Directory.Packages.props`
|
||||
|
||||
---
|
||||
|
||||
## Commands (run from `server/`)
|
||||
|
||||
| Task | Command |
|
||||
| ----------------- | ------- |
|
||||
| Restore | `dotnet restore Baya.sln` |
|
||||
| Build | `dotnet build Baya.sln` |
|
||||
| Run API | `dotnet run --project src/API/Baya.Web.Api/Baya.Web.Api.csproj` |
|
||||
| Test | `dotnet test Baya.sln` |
|
||||
| Add migration | `dotnet ef migrations add <Name> --project src/Infrastructure/Baya.Infrastructure.Persistence --startup-project src/API/Baya.Web.Api` |
|
||||
| Update DB | `dotnet ef database update --project src/Infrastructure/Baya.Infrastructure.Persistence --startup-project src/API/Baya.Web.Api` |
|
||||
|
||||
**Default URL:** `https://localhost:5002` — Swagger at `/swagger`.
|
||||
On boot, `Program.cs` calls `ApplyMigrationsAsync()` and `SeedDefaultUsersAsync()` — a reachable SQL Server is required to start.
|
||||
|
||||
---
|
||||
|
||||
## Quality gates — run these before declaring work done
|
||||
|
||||
1. `dotnet build Baya.sln` — zero new warnings introduced.
|
||||
2. `dotnet test Baya.sln` — all tests pass.
|
||||
3. Read your own diff as if reviewing a PR. Ask: would a senior engineer approve this without comment?
|
||||
|
||||
---
|
||||
|
||||
## Project map
|
||||
|
||||
```
|
||||
src/
|
||||
├── Core/
|
||||
│ ├── Baya.Domain Entities (User, Order, Role…), BaseEntity, IEntity, ITimeModification
|
||||
│ └── Baya.Application Features/ (Commands & Queries), Contracts/, Models/, pipeline behaviors (Common/)
|
||||
├── Infrastructure/
|
||||
│ ├── Baya.Infrastructure.Persistence ApplicationDbContext, Repositories/, Configuration/, Migrations/
|
||||
│ ├── Baya.Infrastructure.Identity Jwt/, Identity/ (Managers, Stores, PermissionManager, Seed)
|
||||
│ ├── Baya.Infrastructure.CrossCutting Serilog wiring
|
||||
│ └── Baya.Infrastructure.Monitoring HealthChecks, OpenTelemetry, prometheus-net
|
||||
├── API/
|
||||
│ ├── Baya.Web.Api Program.cs, Controllers/V1/, appsettings*.json
|
||||
│ ├── Baya.WebFramework BaseController, Filters/, Middlewares/, Swagger/, Routing/
|
||||
│ └── Plugins/Baya.Web.Plugins.Grpc gRPC services + .proto models
|
||||
├── Shared/Baya.SharedKernel Extensions + validation base
|
||||
└── Tests/
|
||||
├── Baya.Tests.Setup Shared test infrastructure (SQLite, NSubstitute setup)
|
||||
└── Baya.Test.Infrastructure.Identity xUnit identity tests
|
||||
```
|
||||
|
||||
**Dependency direction points inward.** Domain has no dependencies. Application depends only on Domain. Infrastructure and API implement/consume Application contracts. Never make Domain or Application reference Infrastructure or the API — this is a hard rule.
|
||||
|
||||
---
|
||||
|
||||
## Startup wiring
|
||||
|
||||
Service registration is composed from per-layer extension methods (each project's `ServiceConfiguration/`):
|
||||
|
||||
```
|
||||
ConfigureHealthChecks() · SetupOpenTelemetry()
|
||||
AddApplicationServices() // Mediator + validators + pipeline behaviors
|
||||
RegisterIdentityServices(...) // Identity, JWT/JWE, authorization policies
|
||||
AddPersistenceServices(...) // DbContext, UnitOfWork, repositories
|
||||
AddWebFrameworkServices() // API versioning + snake_case routing
|
||||
AddSwagger("v1", "v1.1") · RegisterValidatorsAsServices() · AddMapster()
|
||||
ConfigureGrpcPluginServices()
|
||||
```
|
||||
|
||||
Pipeline order: exception handler → Swagger → routing → **authentication → authorization** → controllers → metrics → health checks → gRPC.
|
||||
|
||||
When adding new infrastructure, expose it as an extension method and call it from `Program.cs` — never inline registrations there directly.
|
||||
|
||||
---
|
||||
|
||||
## CQRS — how a feature is shaped
|
||||
|
||||
Features live under `Baya.Application/Features/<Area>/{Commands|Queries}/<Name>/`:
|
||||
|
||||
```
|
||||
Features/Order/
|
||||
├── Commands/CreateOrderCommand/
|
||||
│ ├── CreateOrderCommand.cs record : ICommand<OperationResult<T>>
|
||||
│ ├── CreateOrderCommand.Handler.cs internal sealed class : ICommandHandler<...>
|
||||
│ └── CreateOrderCommand.Validator.cs
|
||||
└── Queries/GetUserOrdersQuery/
|
||||
├── GetUserOrdersQuery.cs
|
||||
├── GetUserOrdersQuery.Handler.cs
|
||||
└── GetUserOrdersQuery.Result.cs
|
||||
```
|
||||
|
||||
Handlers are `internal sealed`. Requests are `record` types. Validators use FluentValidation and are picked up automatically by the `ValidateCommandBehavior` pipeline behavior. Never throw for expected failures — use `OperationResult` factory methods.
|
||||
|
||||
**To add a feature:** create the folder, implement request + handler + (optional) validator, add any new contracts to `Application/Contracts/` and implement them in Infrastructure, then wire a controller action to `sender.Send(...)`.
|
||||
|
||||
---
|
||||
|
||||
## Persistence
|
||||
|
||||
- Access the DB through `IUnitOfWork` — not `ApplicationDbContext` directly outside Infrastructure.
|
||||
- Commit once per command via `unitOfWork.CommitAsync()`.
|
||||
- Use `AsNoTracking()` on all read-only queries.
|
||||
- Always project to a DTO in queries — never return entity objects from handlers.
|
||||
- Add entity config in `Persistence/Configuration/<Area>Config/` implementing `IEntityTypeConfiguration<T>`.
|
||||
|
||||
---
|
||||
|
||||
## Identity & auth
|
||||
|
||||
- JWT/JWE issued by `IJwtService` (`Baya.Infrastructure.Identity/Jwt/JwtService.cs`).
|
||||
- Dynamic permission system: `DynamicPermissionHandler` reads `[controller]` + `[action]` route values and checks role claims. The key format is set at runtime — always use `[controller]`/`[action]` tokens (see CONVENTIONS.md Routing rule) so the keys are consistent.
|
||||
- Settings bound from `appsettings.json` → `IdentitySettings`.
|
||||
|
||||
---
|
||||
|
||||
## Conventions (see [CONVENTIONS.md](CONVENTIONS.md) for the full rule set)
|
||||
|
||||
Quick reference:
|
||||
- All URL segments are `snake_case` via `SnakeCaseParameterTransformer` — use `[controller]`/`[action]` tokens.
|
||||
- Controllers inherit `BaseController`, inject `ISender`, return `base.OperationResult(result)`.
|
||||
- Never call `Ok()` / `BadRequest()` directly in controllers.
|
||||
- Handlers are `internal sealed`; never throw for expected failures.
|
||||
- Mapster for mapping; FluentValidation for validation.
|
||||
- Package versions only in `Directory.Packages.props`.
|
||||
- The `Baya.*` namespace is project naming — do not rename without explicit instruction.
|
||||
|
||||
---
|
||||
|
||||
## Known build warnings (pre-existing — do not fix unless tasked)
|
||||
|
||||
| Warning | Project | Note |
|
||||
| ------- | ------- | ---- |
|
||||
| `NU1510` on `Microsoft.Extensions.Logging.Debug` | `Baya.Web.Api` | Redundant transitive reference, harmless |
|
||||
| `NETSDK1057` (preview SDK) | all | .NET 10 SDK is preview on this machine |
|
||||
`CLAUDE.md` is the single source of truth; this file is just a pointer so the convention is
|
||||
discoverable under the `AGENTS.md` name too.
|
||||
|
||||
Reference in New Issue
Block a user