# Balinyaar — Server (ASP.NET Core, Clean Architecture)

Backend API for the Balinyaar application. It is an **ASP.NET Core (.NET 10)** solution organized around **Clean Architecture**, with:

- **CQRS** via MediatR (source-generated)
- **ASP.NET Core Identity** with **JWE** (signed + encrypted JWT) and **OTP** authentication
- **Dynamic, permission-based authorization**
- **EF Core** persistence (SQL Server) with the Repository + Unit of Work patterns
- A modular **gRPC plugin** mounted via Application Parts
- Observability out of the box: Serilog, OpenTelemetry, Prometheus metrics, health checks

> Looking for an architecture/file map to navigate the code? See [AGENTS.md](AGENTS.md).

## Requirements

- [.NET 10 SDK](https://dotnet.microsoft.com/)
- SQL Server (local instance, or the containerized one from `docker-compose.yml`)

## Running locally

From the `server/` folder:

```bash
dotnet restore CleanArcTemplate.sln
dotnet build CleanArcTemplate.sln
dotnet run --project src/API/CleanArc.Web.Api/CleanArc.Web.Api.csproj
```

By default the API listens on **https://localhost:5002** and serves Swagger UI at **/swagger**.

On startup the app **applies EF Core migrations** and **seeds default users** automatically, so a reachable database (see `appsettings.json` → `ConnectionStrings`) is required.

### Configuration

Settings live in `src/API/CleanArc.Web.Api/appsettings.json` (+ `appsettings.Development.json`):

- `ConnectionStrings:SqlServer` — main application database
- `ConnectionStrings:logDb` — Serilog SQL sink database
- `IdentitySettings` — `SecretKey` (signing), `Encryptkey` (AES-128 encryption, exactly 16 chars), `Issuer`, `Audience`, token lifetimes

## Running with Docker

Generate a development HTTPS certificate (used by the container):

```bash
dotnet dev-certs https -ep $env:USERPROFILE/.aspnet/https/cleanarc.pfx -p Strong@Password
dotnet dev-certs https --trust
```

Build and start the API together with SQL Server 2022:

```bash
docker build -t balinyaar-server -f Dockerfile .
docker-compose up -d
```

The compose stack exposes the API on `http://localhost:5000` / `https://localhost:5001` and SQL Server on `localhost:1435`.

## Solution layout

```
src/
├── Core/
│   ├── CleanArc.Domain          Entities + domain primitives (the core / "brain")
│   └── CleanArc.Application      CQRS features, contracts (interfaces), MediatR pipeline
├── Infrastructure/
│   ├── CleanArc.Infrastructure.Persistence    EF Core DbContext, configs, repositories, UoW, migrations
│   ├── CleanArc.Infrastructure.Identity        Identity, JWE/JWT, OTP, dynamic permissions
│   ├── CleanArc.Infrastructure.CrossCutting    Cross-cutting concerns (logging)
│   └── CleanArc.Infrastructure.Monitoring      Health checks, OpenTelemetry, Prometheus
├── API/
│   ├── CleanArc.Web.Api          Presentation: REST controllers, Program.cs (startup)
│   ├── CleanArc.WebFramework     Reusable web config: base controller, filters, middleware, Swagger
│   └── Plugins/CleanArc.Web.Plugins.Grpc   Self-contained gRPC plugin
├── Shared/
│   └── CleanArc.SharedKernel     Shared extensions/helpers referenced by every layer
└── Tests/                        xUnit test setup + Identity tests
```

## The layers (why they exist)

### Domain

The core of the project. Each entity may carry its own behavior. Entities derive from a common `BaseEntity`, which lets the persistence layer discover models via reflection to register them and drive migrations.

### Application

Routes requests and defines the **contracts** (interfaces) the system depends on, without knowing their implementations. This is where **CQRS** lives: Commands and Queries are kept separate and dispatched to their handlers by **MediatR**. Cross-cutting concerns (validation, metrics) are applied as MediatR pipeline behaviors.

### Infrastructure

Implements the contracts the Application layer declares — the parts needed to run in the real world:

- **Persistence** — the chosen database (SQL Server via EF Core). Repositories give self-describing, persistence-agnostic data access; Unit of Work keeps multi-step writes atomic and consistent.
- **Identity** — registration, authentication and authorization using ASP.NET Core Identity, with JWE tokens, OTP login, and a dynamic access-control system.
- **CrossCutting** — services used across the whole app, such as logging.
- **Monitoring** — health checks, distributed tracing/metrics, and Prometheus.

### WebFramework

Keeps `Program.cs` thin by moving each piece of configuration into its own reusable class (filters, middleware, Swagger, API versioning, the base controller, etc.).

### Web.Api

The presentation layer — an ASP.NET Core Web API exposing versioned REST controllers under `Controllers/V1`.

### Web.Plugins.Grpc

A standalone module that adds gRPC endpoints to the same host via **Application Parts**, giving modularity (the "plugin" middle ground between a monolith and microservices) without a separate deployment. It registers its services and pipeline through extension methods called from `Program.cs`.

## Tests

```bash
dotnet test CleanArcTemplate.sln
```

Each layer is designed to be testable in isolation; `CleanArc.Tests.Setup` provides the shared test scaffolding.

## License

See [LICENSE.md](LICENSE.md).