Kodevy.Templates.Microservice.Init 9.1.4

ORG.SYSTEM Microservice Solution (Monorepo)

A .NET 8 monorepo microservice solution using Clean Architecture with Kodevy Platform NuGet packages (Kodevy.Platform.* 4.3.*).

Documentation (read this first)

Use the per-service README for day-to-day configuration; use the template README for scaffolding workflow.

Project Structure

.
├── services/
│   └── __ORG__.__SYSTEM__.__SERVICE__/
│       ├── __ORG__.__SYSTEM__.__SERVICE__.sln
│       ├── nuget.config
│       ├── Dockerfile
│       ├── azure-pipelines.service.yml
│       ├── add-migration.sh / add-migration.ps1
│       ├── db-init/
│       │   ├── database-setup.sql
│       │   ├── database-setup.postgresql.sql
│       │   ├── database-setup.sqlserver.sql
│       │   ├── database-setup.mysql.sql
│       │   └── bootstrap-db.sh / bootstrap-db.ps1
│       ├── tests/
│       │   └── __ORG__.__SYSTEM__.__SERVICE__.Tests/
│       └── src/
│           ├── __ORG__.__SYSTEM__.__SERVICE__.API/
│           ├── __ORG__.__SYSTEM__.__SERVICE__.Application/
│           ├── __ORG__.__SYSTEM__.__SERVICE__.Domain/
│           └── __ORG__.__SYSTEM__.__SERVICE__.Infra/
│               └── Migrations/
├── nuget.config
└── Directory.Build.props

Architecture

Each microservice follows Clean Architecture with four layers:

• API - Controllers, middleware, configuration, startup
• Application - Use cases, DTOs, services, contracts
• Domain - Entities, domain logic
• Infrastructure - Data access, repositories, external services

Platform Packages

Base functionality is provided via NuGet packages from Kodevy Platform:

• Kodevy.Platform.API - API plumbing (middleware, auth, swagger, health checks)
• Kodevy.Platform.Application - Application layer primitives and clients
• Kodevy.Platform.Domain - Domain abstractions
• Kodevy.Platform.Infra - Infrastructure components (EF Core, Serilog sinks)

Generated services reference Kodevy.Platform.* version 4.3.*.

These packages are configured in nuget.config and referenced in each project.

Getting Started

Run Your First Microservice

cd services/__ORG__.__SYSTEM__.__SERVICE__/src/__ORG__.__SYSTEM__.__SERVICE__.API
dotnet run

Add a New Microservice

Navigate to the services/ directory and run:

cd services
dotnet new kodevy-microservice-add \
  --organization __ORG__ \
  --system __SYSTEM__ \
  --microservice <NewServiceName>

Database Migrations

Each microservice ships with a User model in the Domain layer, but no migration has been created. If you want to use the model that shipped with the microservice, you need to create a migration or create the table manually.

Linux/Mac:

cd services/__ORG__.__SYSTEM__.__SERVICE__
chmod +x add-migration.sh  # First time only
./add-migration.sh AddUserTable

Windows (PowerShell):

cd services\__ORG__.__SYSTEM__.__SERVICE__
.\add-migration.ps1 -Name AddUserTable

Migration Behavior:

• Development: Migrations are automatically applied on application startup
• Production: Migrations are not applied automatically. To run migrations in production, set the RUN_MIGRATIONS_ONLY=true environment variable. When this flag is set, the application will apply all pending migrations and then exit (migration-only mode)

Docker

Each microservice includes a Dockerfile for containerization. The Dockerfile uses multi-stage builds for optimal image size and includes all necessary project references.

Build Docker image:

cd services/__ORG__.__SYSTEM__.__SERVICE__
docker build -t __ORG__.__SYSTEM__.__SERVICE__:latest .

Run container:

docker run -p 8080:8080 __ORG__.__SYSTEM__.__SERVICE__:latest

Run migrations in production container:

docker run -e RUN_MIGRATIONS_ONLY=true __ORG__.__SYSTEM__.__SERVICE__:latest

Provider-Agnostic DB Bootstrap

Use db-init/database-setup.postgresql.sql, db-init/database-setup.sqlserver.sql, or db-init/database-setup.mysql.sql based on DatabaseConfiguration.Provider. Helper runners are included as db-init/bootstrap-db.sh and db-init/bootstrap-db.ps1.

Testing

Each generated microservice includes a test project with starter tests:

• tests/__ORG__.__SYSTEM__.__SERVICE__.Tests/Domain/UserTests.cs
• tests/__ORG__.__SYSTEM__.__SERVICE__.Tests/Application/UserServiceTests.cs

Run from service root:

cd services/__ORG__.__SYSTEM__.__SERVICE__
dotnet test

Configuration

Authentication & Authorization

Each microservice supports configurable authentication and authorization strategies:

AuthenticationStrategy (available options):

• Jwt - JWT token-based authentication

AuthorizationStrategy (available options):

• Claims - Authorization based on JWT claims

API Versioning & Swagger

Generated APIs follow URL-segment versioning conventions:

• Controller route pattern: api/v{version:apiVersion}/[controller]
• Controller version attribute: [ApiVersion("1.0")]

Swagger is configured through Platform with versioned documents (for example /swagger/v1/swagger.json) and automatic support for additional API versions.

JWT Settings

JwtSettings supports two validation modes:

• HS256 (default):

  • SigningAlgorithm = HS256 (or omitted)
  • Secret, Issuer, Audience
  • if issuing tokens, add AccessTokenExpirationMinutes and RefreshTokenExpirationMinutes

• RS256 (opt-in):

  • SigningAlgorithm = RS256
  • Issuer, Audience
  • configure one of Authority or JwksUri
  • Secret is not required in RS256 mode

Optional controls:

• RequireHttpsMetadata (default true)
• RefreshOnIssuerKeyNotFound (default true)
• ValidAlgorithms (defaults to mode-appropriate values)
• issuer-only: PrivateKeyPem, KeyId (for services that issue RS256 tokens)

OpenTelemetry

OpenTelemetry settings are scaffolded by default. When enabled, Platform AddBaseOpenTelemetry captures traces and metrics (ASP.NET Core, HTTP client, runtime) and can export via OTLP.

OAuth redirect allowlist (OAuthRedirect)

Scaffolded for services that implement OAuth-style redirects back to a SPA. Configure AllowedOrigins, AllowedPathPrefixes, FrontendBaseUrl, and RequireHttps per environment. See the microservice README.md for field-by-field details.

Platform 4.3 middleware

Generated APIs include security headers (UseSecurityHeaders) and rate limiting (UseBaseRateLimiting) in the pipeline after HSTS. Optional SecurityHeaders / AuthRateLimit sections in appsettings can override defaults — see the microservice README.md.

Other Configuration

• Database: Edit appsettings.json in the API project for database configuration. When running through Docker locally, use host.docker.internal as the database host.
• NuGet Packages: The nuget.config file is pre-configured with the NuGet.org feed
• Build Settings: Directory.Build.props contains shared build configuration