# AGENTS.md — Balinyaar Server

Agent-oriented guide to the backend. For human setup/run instructions see [README.md](README.md).

## Stack

- **ASP.NET Core / .NET 10** (`net10.0`), Web API
- **Clean Architecture** (Domain → Application → Infrastructure → API)
- **CQRS** with **MediatR** (source-generated `Mediator`)
- **EF Core 10** + **SQL Server** (Repository + Unit of Work)
- **ASP.NET Core Identity** with **JWE** (signed + AES-encrypted JWT), **OTP**, and **dynamic permission** authorization
- **Mapster** (mapping), **FluentValidation** (validation), **Serilog** (logging), **OpenTelemetry** + **prometheus-net** (observability), **NSwag/Swagger** (OpenAPI), **Asp.Versioning** (API versioning)
- **xUnit** + **NSubstitute** (tests)
- Centralized NuGet versions in `Directory.Packages.props`

## Commands (run from `server/`)

| Task       | Command                                                                            |
| ---------- | --------------------------------------------------------------------------------- |
| Restore    | `dotnet restore CleanArcTemplate.sln`                                              |
| Build      | `dotnet build CleanArcTemplate.sln`                                                |
| Run API    | `dotnet run --project src/API/CleanArc.Web.Api/CleanArc.Web.Api.csproj`            |
| Test       | `dotnet test CleanArcTemplate.sln`                                                 |
| Add migration | `dotnet ef migrations add <Name> --project src/Infrastructure/CleanArc.Infrastructure.Persistence --startup-project src/API/CleanArc.Web.Api` |

**Startup project:** `src/API/CleanArc.Web.Api`. Default URL `https://localhost:5002`, Swagger at `/swagger`. On boot the app applies EF migrations and seeds default users (`Program.cs` → `ApplyMigrationsAsync()` / `SeedDefaultUsersAsync()`), so a reachable DB is required.

## Projects by layer

```
src/
├── Core/
│   ├── CleanArc.Domain                          Entities (User, Order, Role...), BaseEntity, IEntity, ITimeModification
│   └── CleanArc.Application                      CQRS Features/, Contracts/ (interfaces), Models/, MediatR pipeline (Common/)
├── Infrastructure/
│   ├── CleanArc.Infrastructure.Persistence      ApplicationDbContext, Configuration/, Repositories/, Migrations/
│   ├── CleanArc.Infrastructure.Identity         Jwt/, Identity/ (Managers, Stores, PermissionManager, Seed), ServiceConfiguration/
│   ├── CleanArc.Infrastructure.CrossCutting     Logging (Serilog)
│   └── CleanArc.Infrastructure.Monitoring       HealthCheck / OpenTelemetry / Prometheus configs
├── API/
│   ├── CleanArc.Web.Api                         Program.cs, Controllers/V1/, appsettings*.json
│   ├── CleanArc.WebFramework                    BaseController, Filters/, Middlewares/, Swagger/, Attributes/
│   └── Plugins/CleanArc.Web.Plugins.Grpc        GrpcPluginStartup, Services/, ProtoModels/
├── Shared/CleanArc.SharedKernel                 Extensions + validation base used by all layers
└── Tests/                                       CleanArc.Tests.Setup + CleanArc.Test.Infrastructure.Identity
```

Dependency direction points **inward**: Domain depends on nothing; Application depends on Domain; Infrastructure and API implement/consume Application's contracts. Never make Domain or Application reference Infrastructure or the API.

## Startup wiring — `src/API/CleanArc.Web.Api/Program.cs`

Service registration is composed from per-layer extension methods (in each project's `ServiceConfiguration`):

```
ConfigureHealthChecks() · SetupOpenTelemetry()
AddApplicationServices()           // MediatR + validators + pipeline behaviors
RegisterIdentityServices(...)      // Identity, JWT/JWE, authorization policies
AddPersistenceServices(...)        // DbContext, UnitOfWork, repositories
AddWebFrameworkServices()          // API versioning
AddSwagger("v1","v1.1") · RegisterValidatorsAsServices() · AddMapster()
ConfigureGrpcPluginServices()      // gRPC plugin
```

Pipeline order: exception handling → Swagger → routing → **authentication → authorization** → controllers → metrics → health checks → `ConfigureGrpcPipeline()`.

When adding infrastructure, expose it as an extension method and call it here rather than inlining into `Program.cs`.

## CQRS — how a feature is shaped

Features live under `CleanArc.Application/Features/<Area>/{Commands|Queries}/<Name>/`. A query example (`Features/Order/Queries/GetAllOrders/`):

- `GetAllOrdersQuery.cs` — `record ... : IRequest<OperationResult<...>>`
- `GetAllOrdersQueryHandler.cs` — `internal` handler; depends on `IUnitOfWork`, `IMapper`; returns `OperationResult<T>`
- `GetAllOrdersQueryResult.cs` — the DTO returned

Commands additionally implement `IValidatableModel<T>` and declare FluentValidation rules; the `ValidateCommandBehavior` MediatR pipeline (`Application/Common/`) runs validators before the handler and surfaces errors in `OperationResult`.

**To add a feature:** create the folder with the request + handler (+ result/validator), then call it from a controller via `_sender.Send(...)`. Contracts the handler needs go in `Application/Contracts/` and are implemented in Infrastructure.

## Controllers & results

- Controllers live in `CleanArc.Web.Api/Controllers/V1/` and inherit `BaseController` (`CleanArc.WebFramework/BaseController/BaseController.cs`), which exposes `UserId`/`UserName`/etc. from claims and maps `OperationResult<T>` → `IActionResult`.
- All responses are wrapped in `OperationResult<T>` (`Application/Models/Common/`): `Result`, `IsSuccess`, `ErrorMessages`, `IsNotFound`, `IsException`. Use the factory methods (`SuccessResult`, `FailureResult`, `NotFoundResult`).
- Protected endpoints use `[Authorize(ConstantPolicies.DynamicPermission)]`.

## Persistence

- `ApplicationDbContext` (`CleanArc.Infrastructure.Persistence/ApplicationDbContext.cs`) extends `IdentityDbContext<...>`; it auto-registers `IEntity` types and applies all `IEntityTypeConfiguration` from the assembly.
- Per-entity config in `Configuration/<Area>Config/`. Repositories in `Repositories/` derive from `BaseAsyncRepository<T>`; expose them through `IUnitOfWork` (interface in `Application/Contracts/Persistence/`). Commit via `unitOfWork.CommitAsync()`.
- Migrations in `Migrations/`. Add new ones with the `dotnet ef` command above.

## Identity & auth

- Token service: `CleanArc.Infrastructure.Identity/Jwt/JwtService.cs` (`IJwtService`) — issues JWE (HMAC-SHA256 signed, AES-128 encrypted), refresh tokens, and OTP/phone-based tokens.
- Custom Identity managers/stores under `Identity/Manager/` and `Identity/Store/`.
- Dynamic permissions: `Identity/PermissionManager/` (`DynamicPermissionService`, `DynamicPermissionHandler`, `ConstantPolicies`).
- Settings from `appsettings.json` → `IdentitySettings` (`SecretKey`, `Encryptkey` = 16 chars, `Issuer`, `Audience`, lifetimes).

## gRPC plugin

`Plugins/CleanArc.Web.Plugins.Grpc` is a self-contained module mounted via Application Parts. `GrpcPluginStartup.cs` provides `ConfigureGrpcPluginServices()` / `ConfigureGrpcPipeline()` (called from `Program.cs`). Proto contracts in `ProtoModels/*.proto`, services in `Services/`. The host uses HTTP/2 (`Kestrel` config) for gRPC.

## Conventions

- Add cross-layer wiring as `ServiceConfiguration` extension methods, not inline in `Program.cs`.
- Keep handlers `internal`; return `OperationResult<T>`; don't throw for expected failures (use `FailureResult`/`NotFoundResult`).
- Use Mapster for entity↔DTO mapping; FluentValidation for input validation.
- Centralize package versions in `Directory.Packages.props` (no inline `Version=` in `.csproj`).
- The `CleanArc*` namespace/`.sln` naming is internal project naming, **not** template branding — don't rename it without an explicit request (it touches every file and the EF migrations).