KV.Backend.Archetype 0.1.1

KV Backend Archetype

Backend archetype for .NET 10 based on Clean Architecture and Modular Monolith.

Provides a ready-to-use foundation for building APIs without having to configure the basic architecture and infrastructure from scratch.

Stack

• .NET 10
• ASP.NET Core
• PostgreSQL
• Entity Framework Core
• FluentValidation
• JWT Authentication
• Serilog
• OpenTelemetry
• xUnit
• Docker

Architecture

src/
├── KV.Backend.Api/
├── KV.Backend.BuildingBlocks/
│
└── Modules/
    └── Sample/
        ├── KV.Backend.Modules.Sample.Domain/
        ├── KV.Backend.Modules.Sample.Application/
        ├── KV.Backend.Modules.Sample.Infrastructure/
        └── KV.Backend.Modules.Sample.Contracts/

tests/
├── KV.Backend.UnitTests/
└── KV.Backend.IntegrationTests/

Each module follows:

Domain
   ↑
Application
   ↑
Infrastructure
   ↑
API

The Sample module is included as a reference implementation.

Requirements

• .NET 10 SDK
• PostgreSQL
• Docker (optional)

Installation

Install the archetype:

dotnet new install KV.Backend.Archetype

Create a new project:

dotnet new kv-backend -n MyBackend

Enter the project:

cd MyBackend

Restore and build:

dotnet restore
dotnet build

Run:

dotnet run --project src/MyBackend.Api

Database

The Sample module uses PostgreSQL.

Configure the connection string:

{
  "ConnectionStrings": {
    "SampleDatabase": "Host=localhost;Port=5432;Database=kv_backend;Username=postgres;Password=YOUR_PASSWORD"
  }
}

Apply the included migrations:

dotnet ef database update \
  --project src/Modules/Sample/MyBackend.Modules.Sample.Infrastructure \
  --startup-project src/MyBackend.Api \
  --context SampleDbContext

This creates the Sample persistence structure:

sample_records
├── id
└── name

Authentication

Protected endpoints require a JWT:

Authorization: Bearer <token>

Configure JWT using appsettings.json or environment variables.

{
  "Jwt": {
    "Issuer": "MyBackend",
    "Audience": "MyBackend.Client",
    "Key": "CHANGE-THIS-KEY-IN-REAL-ENVIRONMENTS",
    "ExpirationMinutes": 60
  }
}

Sample Endpoints

The Sample module contains endpoints that demonstrate the main features of the archetype.

Hello

GET /api/sample/hello

Expected:

200 OK

Calculate

POST /api/sample/calculate
Authorization: Bearer <token>
Content-Type: application/json

Addition

{
  "firstValue": 15,
  "secondValue": 25,
  "operation": "add"
}

Subtraction

{
  "firstValue": 25,
  "secondValue": 10,
  "operation": "subtract"
}

Supported operations:

add
subtract

Validation test

{
  "firstValue": 15,
  "secondValue": 25,
  "operation": "invalid"
}

Expected:

422 Unprocessable Entity

Example:

{
  "title": "Validation error",
  "status": 422,
  "detail": "One or more validation errors occurred.",
  "errors": {
    "Operation": [
      "Operation must be 'add' or 'subtract'."
    ]
  },
  "traceId": "...",
  "correlationId": "..."
}

Without JWT:

401 Unauthorized

Create Sample Record

POST /api/sample/records
Authorization: Bearer <token>
Content-Type: application/json

Body:

{
  "name": "Sample record"
}

Get Sample Records

Using EF Core + LINQ:

GET /api/sample/records
Authorization: Bearer <token>

Example response:

[
  {
    "id": 1,
    "name": "Sample record"
  }
]

Get Sample Records - Native SQL

GET /api/sample/records/native
Authorization: Bearer <token>

Demonstrates native SQL queries using EF Core.

Tests

Run:

dotnet test

The archetype includes:

Unit Tests
├── Add
└── Subtract

Integration Tests
├── Hello → 200
└── Calculate without JWT → 401

Docker

Build:

docker build -t kv-backend .

Run:

docker run --rm -p 8080:8080 kv-backend

Version

0.1.0