hamid
192 lines
8.9 KiB
Markdown
192 lines
8.9 KiB
Markdown
# Balinyaar Server — Claude Code Guidelines
|
|
|
|
The backend API of **Balinyaar**, a trust-first home-nursing marketplace in Iran.
|
|
|
|
- **Coding rules** (the full rule set you must follow) → [CONVENTIONS.md](CONVENTIONS.md). Read it
|
|
before writing any server code.
|
|
- Repo-wide context and the frontend → root [CLAUDE.md](../CLAUDE.md).
|
|
- Product/domain rules (business logic, schema, payments, escrow, verification) → [`product/`](../product/).
|
|
Read the relevant doc before designing an entity, feature, or endpoint — don't infer business rules
|
|
from code.
|
|
|
|
---
|
|
|
|
## Role
|
|
|
|
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 touches a
|
|
contract other layers depend on, think about downstream impact.
|
|
- You prefer simplicity and clarity over cleverness. The next engineer (or agent) should read your
|
|
code without a guide.
|
|
- You never leave the codebase in a worse state than you found it.
|
|
|
|
---
|
|
|
|
## 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 are centrally pinned in `Directory.Packages.props`
|
|
|
|
> Note: some prose elsewhere may say "MediatR" — the actual dispatcher is `martinothamar/Mediator`.
|
|
> Use `ISender`/`ICommand`/`IQuery` from that package, not MediatR types.
|
|
|
|
---
|
|
|
|
## 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 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: would a senior engineer approve it 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(...)`. Full conventions are in [CONVENTIONS.md](CONVENTIONS.md) §5.
|
|
|
|
---
|
|
|
|
## 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>`.
|
|
- Soft delete is enforced via a global query filter per entity (see [CONVENTIONS.md](CONVENTIONS.md) §6).
|
|
|
|
---
|
|
|
|
## 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. Always use `[controller]`/`[action]` tokens so the keys stay
|
|
consistent (see CONVENTIONS.md §1 Routing).
|
|
- Settings bound from `appsettings.json` → `IdentitySettings`.
|
|
- Auth and OTP endpoints must be rate-limited (CONVENTIONS.md §11).
|
|
|
|
---
|
|
|
|
## Conventions — quick reference
|
|
|
|
Full rules in [CONVENTIONS.md](CONVENTIONS.md). The essentials:
|
|
|
|
- All URL segments are `snake_case` via `SnakeCaseParameterTransformer` — use `[controller]`/`[action]` tokens.
|
|
- Controllers are `sealed`, inherit `BaseController`, inject `ISender`, return `base.OperationResult(result)`.
|
|
Never call `Ok()` / `BadRequest()` / `NotFound()` directly.
|
|
- Handlers are `internal sealed`; never throw for expected failures — return `OperationResult`.
|
|
- `record` for requests/DTOs, `class` for entities (no public setters), `sealed class` for handlers/services.
|
|
- `async`/`await` all the way; pass `CancellationToken` through every async call; never `.Result`/`.Wait()`/`async void`.
|
|
- Mapster for mapping; FluentValidation for validation (validate at the boundary).
|
|
- Package versions live **only** in `Directory.Packages.props` — never `Version=` in a `.csproj`.
|
|
- 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 |
|