Home

cpnucleo

Cpnucleo is a project management and task tracking system built with .NET 10, demonstrating Clean Architecture, Domain-Driven Design, and a CQRS-like dual data access strategy with REST (FastEndpoints + EF Core) and gRPC (FastEndpoints Remote Messaging + Dapper) against the same PostgreSQL database.

Quick Links

Key Features

• Clean Architecture with strict layer dependency enforcement validated by 25+ architecture tests
• Dual data access: EF Core for the REST API, Dapper with Unit of Work for the gRPC server
• FastEndpoints for both REST endpoints and gRPC-style remote command handling
• JWT authentication via the dedicated Identity API with PBKDF2-hashed credentials
• Rate limiting with fixed-window partitioning per IP (50/min WebApi, 10/min IdentityApi)
• OpenTelemetry observability with OTLP export and optional Grafana LGTM stack
• NGINX reverse proxy with least-connection load balancing across multiple WebApi instances
• Docker Compose configurations for development, default, and production environments
• AOT, Trim, and ExtraOptimize build options for production-optimized containers
• Blazor Server + WebAssembly frontend with MudBlazor UI components
• Automated CI/CD with GitHub Actions deploying to Azure Web Apps via GHCR

Repository

github.com/jonathanperis/cpnucleo

Api Reference

API Reference

Cpnucleo exposes three API services: the WebApi (REST), the IdentityApi (authentication), and the GrpcServer (gRPC command handling).

WebApi -- REST Endpoints

The WebApi uses FastEndpoints to define REST endpoints with Swagger/OpenAPI documentation. Each entity has 5 standard CRUD endpoints.

Base URL

• Direct: http://localhost:5100
• Via NGINX load balancer: http://localhost:9999

Swagger

Available in Development mode at /swagger.

Endpoint Pattern

Every entity follows this consistent pattern:

Available Entities

Example: Create Appointment

Request:

POST /api/appointment
Content-Type: application/json

{
  "id": "00000000-0000-0000-0000-000000000000",
  "description": "Sprint planning meeting",
  "keepDate": "2025-03-01T10:00:00Z",
  "amountHours": 2,
  "assignmentId": "...",
  "userId": "..."
}

Response (200 OK):

{
  "appointment": {
    "id": "...",
    "description": "Sprint planning meeting",
    "keepDate": "2025-03-01T10:00:00Z",
    "amountHours": 2,
    "assignmentId": "...",
    "userId": "...",
    "createdAt": "...",
    "active": true
  }
}

Data Access

All WebApi endpoints use EF Core via IApplicationDbContext for database operations. Endpoints inject the context directly:

public class Endpoint(IApplicationDbContext dbContext) : Endpoint<Request, Response>

Rate Limiting

• 50 requests per minute per IP address
• Fixed-window partitioning
• Queue limit: 10 additional requests
• Returns 429 Too Many Requests with Retry-After: 60 header when exceeded

API Client Generation

The WebApi generates downloadable API clients via Kiota:

• C# client: Available at /cs-client
• TypeScript client: Generated during build

IdentityApi -- Authentication

Base URL

http://localhost:5200

Swagger

Available in Development mode at /swagger.

Login Endpoint

Request:

POST /api/login
Content-Type: application/json

{
  "login": "user@example.com",
  "password": "password123"
}

Response (200 OK):

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Response (404 Not Found):

Returned when credentials are invalid.

JWT Configuration

Rate Limiting

• 10 requests per minute per IP address
• Queue limit: 3 additional requests
• Stricter than WebApi to protect against brute-force attacks

Output Caching

• Base policy: 10-second cache expiration
• All responses are cached by default

GrpcServer -- Remote Command Handling

The GrpcServer uses FastEndpoints.Messaging.Remote to handle commands over HTTP/2 gRPC transport.

Ports

• Health check: http://localhost:5300/healthz (HTTP/1.1)
• gRPC transport: http://localhost:5301 (HTTP/2)

Command Pattern

Each operation is a command/result pair defined in GrpcServer.Contracts:

Command -> Handler -> Result

Available Commands (per entity)

Each of the 11 entities has these 5 commands:

Total: 55 registered command handlers.

Data Access

All gRPC handlers use Dapper via IUnitOfWork for database operations, providing transactional support with explicit BeginTransactionAsync, CommitAsync, and RollbackAsync.

Handler Registration

Handlers are registered in Program.cs:

app.MapHandlers(h =>
{
    h.Register<CreateAppointmentCommand, CreateAppointmentHandler, CreateAppointmentResult>();
    h.Register<GetAppointmentByIdCommand, GetAppointmentByIdHandler, GetAppointmentByIdResult>();
    // ... 53 more handlers
});

Health Checks

All three APIs expose health check endpoints:

Root Endpoint

All services also respond to GET / with "Hello World!".

Authentication Flow

JWT authentication is configured but currently commented out in WebApi and GrpcServer. The IdentityApi is fully functional for token generation. When enabled:

1. Client authenticates via POST /api/login on IdentityApi
2. Receives JWT token
3. Includes token in Authorization: Bearer {token} header for WebApi/GrpcServer requests
4. Token validation checks issuer, audience, signing key, and expiration

Architecture

Architecture

Cpnucleo follows Clean Architecture principles with strict layer separation enforced by automated architecture tests (NetArchTest). The system implements a CQRS-like dual strategy where the REST API and gRPC server use different data access technologies against the same PostgreSQL database.

Layer Overview

+-------------------------------------------------------------+
|                    Presentation Layer                         |
|  WebApi (REST)  |  GrpcServer (gRPC)  |  IdentityApi (Auth) |
|                 |                      |  WebClient (Blazor)  |
+-------------------------------------------------------------+
|                   Infrastructure Layer                        |
|  EF Core (ApplicationDbContext)  |  Dapper (UnitOfWork)      |
|  NpgsqlConnection  |  Mappings  |  Migrations                |
+-------------------------------------------------------------+
|                     Domain Layer                              |
|  Entities  |  Repositories (Interfaces)  |  UoW (Interface)  |
|  Models  |  Common (Security)                                 |
+-------------------------------------------------------------+

Domain Layer (src/Domain)

The innermost layer with zero external dependencies. Architecture tests verify that Domain does not depend on EF Core, Dapper, Npgsql, or any presentation project.

Entities

All entities inherit from BaseEntity, which provides:

public abstract class BaseEntity
{
    public Guid Id { get; protected init; }
    public DateTime CreatedAt { get; protected init; }
    public DateTime? UpdatedAt { get; protected set; }
    public DateTime? DeletedAt { get; protected set; }
    public bool Active { get; protected set; }
}

Each entity is sealed and uses static factory methods for creation, updates, and soft deletes:

• Create(...) -- initializes a new entity with Active = true
• Update(...) -- modifies fields and sets UpdatedAt
• Remove(...) -- sets Active = false and DeletedAt (soft delete)

Entities are annotated with [Table("...")] for Dapper's advanced repository to resolve table names.

Domain Entities

Repository Interfaces

• IRepository<T> -- generic CRUD: GetByIdAsync, GetAllAsync (paginated), AddAsync, UpdateAsync, DeleteAsync, ExistsAsync
• IProjectRepository -- specialized repository for Project-specific queries
• IUnitOfWork -- transaction management: BeginTransactionAsync, CommitAsync, RollbackAsync, GetRepository<T>

Infrastructure Layer (src/Infrastructure)

Implements data access with two strategies side by side:

EF Core (used by WebApi and IdentityApi)

• ApplicationDbContext with IApplicationDbContext interface
• DbSet properties for all entities
• Migrations generated from EF Core, applied via SQL init scripts in Docker
• Delta middleware for HTTP conditional requests based on database timestamps

Dapper (used by GrpcServer)

• DapperRepository<T> -- generic repository using raw SQL with reflection-based column mapping
• Caches PropertyInfo[] via Lazy<> for performance
• Supports paginated queries with configurable sort column/order and SQL injection protection
• UnitOfWork wraps NpgsqlConnection + NpgsqlTransaction for transactional operations
• Dapper.AOT enabled for compile-time SQL interception

Dependency Injection

DependencyInjection.AddInfrastructure() registers:

• IApplicationDbContext as ApplicationDbContext (EF Core, scoped)
• NpgsqlConnection (Dapper basic, scoped)
• IProjectRepository as ProjectRepository (Dapper specialized, scoped)
• IUnitOfWork as UnitOfWork (Dapper advanced with transactions, scoped)
• Optional fake data generation via Bogus when CreateFakeData is configured

Presentation Layer

WebApi (src/WebApi)

• FastEndpoints for REST API with Swagger/OpenAPI documentation
• Uses EF Core via IApplicationDbContext for data access
• Rate limiting: 50 requests/minute per IP with fixed-window partitioning
• Kiota-based API client generation (C# and TypeScript)
• Middleware: ElapsedTimeMiddleware, ErrorHandlingMiddleware
• Riok.Mapperly for compile-time DTO mapping

GrpcServer (src/GrpcServer)

• FastEndpoints.Messaging.Remote for gRPC-style command/handler pattern
• Uses Dapper via IUnitOfWork for data access
• HTTP/2 on port 5021 for gRPC transport
• Command/Result pattern via GrpcServer.Contracts
• All 11 entities have 5 handlers each: Create, GetById, List, Remove, Update (55 handlers total)

IdentityApi (src/IdentityApi)

• JWT token generation via FastEndpoints.Security
• Login endpoint authenticating against User credentials in the database
• Output caching with 10-second base policy
• Rate limiting: 10 requests/minute per IP
• Swagger/OpenAPI documentation

WebClient (src/WebClient)

• Blazor Server + WebAssembly hybrid rendering
• MudBlazor UI component library with translations
• Interactive server and WebAssembly render modes
• Static asset serving

CQRS Dual Implementation

The system demonstrates two parallel approaches to the same domain:

Both implementations share the same Domain entities and PostgreSQL database.

Dependency Rules (Enforced by Architecture Tests)

• Domain depends on nothing (no EF Core, no Dapper, no Npgsql)
• Infrastructure depends only on Domain
• GrpcServer.Contracts depends only on Domain
• WebApi does not depend on GrpcServer
• IdentityApi does not depend on GrpcServer
• All entities must inherit from BaseEntity and be sealed
• All repository interfaces must start with I
• All endpoints must be named Endpoint
• All gRPC handlers must end with Handler
• All commands must end with Command
• All DTOs must end with Dto

Database

Database

Cpnucleo uses PostgreSQL 16.7 as its primary database, accessed via two parallel data access strategies: EF Core (for the REST API) and Dapper (for the gRPC server).

Database Setup

Docker (Automatic)

The database is automatically provisioned when running with Docker Compose. The db service:

1. Starts PostgreSQL 16.7
2. Creates the database using credentials from .env
3. Runs SQL scripts from docker-entrypoint-initdb.d/ in alphabetical order

Docker Configuration

db:
  image: postgres:16.7
  environment:
    POSTGRES_USER: ${POSTGRES_USER}
    POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    POSTGRES_DB: ${POSTGRES_DB}
  volumes:
    - db_data:/var/lib/postgresql/data
    - ./docker-entrypoint-initdb.d:/docker-entrypoint-initdb.d
  command: >
    postgres
    -c checkpoint_timeout=600
    -c max_wal_size=4096
    -c synchronous_commit=0
    -c fsync=0
    -c full_page_writes=0

Performance flags (optimized for development speed over durability):

• checkpoint_timeout=600 -- less frequent checkpoints
• max_wal_size=4096 -- larger WAL before checkpoint
• synchronous_commit=0 -- async commits
• fsync=0 -- skip fsync (data loss risk, faster writes)
• full_page_writes=0 -- skip full-page writes

Manual Setup

psql -U postgres -f docker-entrypoint-initdb.d/001-track-commit-timestamp.sql
psql -U postgres -d cpnucleo -f docker-entrypoint-initdb.d/002-database-dump-ddl.sql

Initialization Scripts

001-track-commit-timestamp.sql

Enables commit timestamp tracking for the Delta middleware:

ALTER SYSTEM SET track_commit_timestamp = on;

This allows the Delta library to implement HTTP conditional requests based on when data was last modified.

002-database-dump-ddl.sql

Contains the full DDL schema generated from EF Core migrations. Creates all tables, constraints, and indexes idempotently (using IF NOT EXISTS checks).

Schema

Tables

Common Columns (all tables)

Indexes

All tables have indexes on:

• CreatedAt -- for Delta middleware timestamp queries
• Foreign key columns -- for join performance

Connection Configuration

Connection String

Configured via the DB_CONNECTION_STRING environment variable:

Host=db;Username=postgres;Password=postgres;Database=cpnucleo;Minimum Pool Size=10;Maximum Pool Size=10;Multiplexing=true

EF Core (WebApi + IdentityApi)

ApplicationDbContext

The ApplicationDbContext implements IApplicationDbContext and provides DbSet properties for all 11 entities. It is registered as a scoped service.

Migrations

EF Core migrations are maintained in src/Infrastructure/Migrations/. The initial migration 20250219224724_InitiaDblMigration creates the full schema.

For production, migrations are exported as SQL and placed in docker-entrypoint-initdb.d/ rather than running EF Core migrations at startup.

Delta Middleware

The Delta library is integrated for HTTP conditional requests:

app.UseDelta(
    getConnection: httpContext => httpContext.RequestServices.GetRequiredService<NpgsqlConnection>());

This enables If-Modified-Since / 304 Not Modified responses using PostgreSQL's commit timestamps.

Dapper (GrpcServer)

Generic Repository

DapperRepository<T> provides CRUD operations via raw SQL:

• GetByIdAsync -- SELECT * FROM "Table" WHERE "Id" = @Id AND "Active" = true
• GetAllAsync -- Paginated query with OFFSET/LIMIT, configurable sort column with SQL injection protection
• AddAsync -- INSERT INTO ... RETURNING "Id" with reflection-based column mapping
• UpdateAsync -- UPDATE ... SET ... WHERE "Id" = @Id
• DeleteAsync -- Hard delete (for gRPC operations)
• ExistsAsync -- SELECT EXISTS(...) check

Performance Optimizations

• PropertyInfo[] cached via Lazy<> to avoid repeated reflection
• HashSet<string> for O(1) sort column validation
• Dapper.AOT for compile-time SQL interception

Unit of Work

UnitOfWork wraps NpgsqlConnection and NpgsqlTransaction:

public interface IUnitOfWork
{
    IRepository<T> GetRepository<T>() where T : BaseEntity;
    Task BeginTransactionAsync();
    Task CommitAsync(CancellationToken cancellationToken = default);
    Task RollbackAsync(CancellationToken cancellationToken = default);
}

Specialized Repository

ProjectRepository implements IProjectRepository for project-specific queries that go beyond the generic CRUD operations.

Fake Data Generation

The Infrastructure layer includes a FakeDataHelper that uses the Bogus library to generate realistic test data. When CreateFakeData=true is set in configuration:

1. Bogus generates fake data for all entities
2. Outputs SQL/CSV dump files
3. Files should be placed in docker-entrypoint-initdb.d/ for seeding

Deployment

Deployment

Cpnucleo uses Docker Compose for containerized deployment and GitHub Actions for CI/CD, with final deployment to Azure Web Apps.

Docker Compose Configurations

The project provides three compose configurations that can be layered:

Base (compose.yaml)

The base configuration defines all services with pre-built GHCR images:

All API services depend on db being healthy before starting.

Development Override (compose.override.yaml)

docker compose -f compose.yaml -f compose.override.yaml up --build

Differences from base:

• Builds from source using Dockerfiles in src/
• Build args: AOT=false, TRIM=false, EXTRA_OPTIMIZE=false, BUILD_CONFIGURATION=Debug
• Adds Grafana LGTM OpenTelemetry stack (ports 3000, 4317, 4318)
• Resource limits: 0.4 CPU, 100MB memory per service

Production Override (compose.prod.yaml)

docker compose -f compose.yaml -f compose.prod.yaml up -d

Differences from base:

• restart: always on all services
• Resource reservations: 0.25 CPU / 256MB per API, 0.50 CPU / 512MB per DB
• Resource limits: 0.50 CPU / 512MB per API, 1.0 CPU / 1GB for DB
• JSON logging with rotation: 10MB max size, 3 files retained
• No build step (uses pre-built images)

Dockerfiles

Each service has a multi-stage Dockerfile supporting configurable build options:

Build Arguments

Build Stages

1. base -- mcr.microsoft.com/dotnet/aspnet:10.0 runtime image
2. build -- mcr.microsoft.com/dotnet/sdk:10.0 with clang/zlib for AOT support; restores, builds
3. publish -- Publishes with configured optimizations
4. final -- Copies published output to runtime image

Platform Support

All images are built for linux/amd64 and linux/arm64/v8.

NGINX Reverse Proxy

NGINX load-balances traffic across two WebApi instances:

upstream api {
    least_conn;
    server webapi1-cpnucleo:5000;
    server webapi2-cpnucleo:5000;
}

server {
    listen 9999;
    location / {
        proxy_pass http://api;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Configuration Highlights

• least_conn load balancing -- sends requests to the server with fewest active connections
• gzip compression -- level 5, minimum 256 bytes
• keepalive_timeout: 0 -- persistent connections disabled for stateless APIs
• server_tokens: off -- hides NGINX version
• access_log: off -- disabled for performance
• epoll event model with multi_accept

GitHub Actions CI/CD

Build Check (build-check.yml)

Triggered on pull requests to main.

Jobs:

1. Setup, Build & Test (matrix: WebApi, GrpcServer, IdentityApi, WebClient)

   • Checkout repository
   • Setup .NET SDK (from global.json)
   • Restore dependencies
   • Build application (Debug, no AOT/Trim)
   • Run Architecture Tests

2. Container Healthcheck Test (depends on build)

   • Build Docker image from source
   • Start container via Docker Compose
   • Poll /healthz endpoint up to 20 times with 5-second intervals
   • Fail if health check does not return 200

Main Release (main-release.yml)

Triggered on push to main and manual dispatch.

Jobs:

1. Setup, Build & Test -- Same as build check but with TRIM=true, EXTRA_OPTIMIZE=true, BUILD_CONFIGURATION=Release

2. Build & Push Docker Image (depends on test)

   • Setup QEMU and Docker Buildx for multi-platform builds
   • Login to GHCR
   • Build and push images for linux/amd64 and linux/arm64/v8
   • Images pushed to GHCR: ghcr.io/jonathanperis/cpnucleo-{service}:latest

3. Container Healthcheck Test (depends on push)

   • Pull production images
   • Run healthcheck validation

4. Deploy to Azure (depends on healthcheck)

   • Deploy each service to its Azure Web App
   • Uses publish profiles stored in GitHub Secrets

Azure Deployment Targets

Environment Variables

Required (.env)

GitHub Secrets (for CI/CD)

Network

All services communicate over a shared Docker bridge network:

networks:
  default:
    name: cpnucleo_network
    driver: bridge

Service discovery uses Docker DNS (e.g., db, webapi1-cpnucleo).

Getting Started

Getting Started

Prerequisites

Clone the Repository

git clone https://github.com/jonathanperis/cpnucleo.git
cd cpnucleo

Run with Docker Compose (Recommended)

Default Mode (Pre-built Images)

Uses pre-built images from GHCR:

docker compose up

Development Mode

Builds from source with debug configuration and includes an OpenTelemetry/Grafana LGTM stack for observability:

docker compose -f compose.yaml -f compose.override.yaml up --build

Production Mode

Uses pre-built images with resource reservations, restart policies, and structured JSON logging:

docker compose -f compose.yaml -f compose.prod.yaml up -d

Services and Ports

Once running, the services are available at:

Health Checks

All services expose a health endpoint:

curl http://localhost:5100/healthz   # WebApi
curl http://localhost:5200/healthz   # IdentityApi
curl http://localhost:5300/healthz   # GrpcServer
curl http://localhost:5400/healthz   # WebClient

Run Locally (Without Docker)

1. Start PostgreSQL

Ensure PostgreSQL 16+ is running locally. Execute the init scripts to set up the schema:

psql -U postgres -f docker-entrypoint-initdb.d/001-track-commit-timestamp.sql
psql -U postgres -d cpnucleo -f docker-entrypoint-initdb.d/002-database-dump-ddl.sql

2. Configure Environment

The project uses environment variables loaded from the .env file. For local development, update the connection string to point to localhost:

POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=cpnucleo
DB_CONNECTION_STRING=Host=localhost;Username=postgres;Password=postgres;Database=cpnucleo;Minimum Pool Size=10;Maximum Pool Size=10;Multiplexing=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_METRIC_EXPORT_INTERVAL=5000

3. Build the Solution

dotnet build cpnucleo.slnx

4. Run the Services

Each service must be run in a separate terminal:

# Terminal 1 - REST API
cd src/WebApi && dotnet run

# Terminal 2 - Identity/Auth API
cd src/IdentityApi && dotnet run

# Terminal 3 - gRPC Server
cd src/GrpcServer && dotnet run

# Terminal 4 - Blazor Web Client
cd src/WebClient && dotnet run

Swagger UI

When running in Development mode, Swagger UI is available for interactive API exploration:

• WebApi: http://localhost:5100/swagger
• IdentityApi: http://localhost:5200/swagger

Generate Fake Data

Set CreateFakeData=true in the application configuration to generate CSV/SQL dump files using Bogus. The generated files should be placed in docker-entrypoint-initdb.d/ for automatic database seeding on container startup.

Project Structure

Project Structure

Solution Overview

cpnucleo/
├── cpnucleo.slnx                         # Solution file
├── global.json                           # .NET SDK version (10.0.102)
├── compose.yaml                          # Docker Compose (default/base)
├── compose.override.yaml                 # Docker Compose (development overrides)
├── compose.prod.yaml                     # Docker Compose (production overrides)
├── nginx.conf                            # NGINX reverse proxy configuration
├── .env                                  # Environment variables
├── docker-entrypoint-initdb.d/           # PostgreSQL initialization scripts
├── .github/workflows/                    # CI/CD pipelines
├── src/                                  # Source code
└── test/                                 # Test projects

Source Projects (src/)

Domain (src/Domain/)

The core business layer with zero external dependencies.

Domain/
├── Domain.csproj                         # No external NuGet packages
├── Usings.cs                             # Global usings
├── Common/
│   └── Security/
│       └── CryptographyManager.cs        # PBKDF2 password hashing
├── Entities/
│   ├── BaseEntity.cs                     # Abstract base (Id, CreatedAt, UpdatedAt, DeletedAt, Active)
│   ├── Appointment.cs                    # Time tracking entries
│   ├── Assignment.cs                     # Tasks/work items
│   ├── AssignmentImpediment.cs           # Links assignments to impediments
│   ├── AssignmentType.cs                 # Task categorization
│   ├── Impediment.cs                     # Blockers/obstacles
│   ├── Organization.cs                   # Top-level organizational unit
│   ├── Project.cs                        # Projects within organizations
│   ├── User.cs                           # System users with encrypted credentials
│   ├── UserAssignment.cs                 # User-to-assignment mapping (many-to-many)
│   ├── UserProject.cs                    # User-to-project mapping (many-to-many)
│   └── Workflow.cs                       # Workflow stages with ordering
├── Models/
│   ├── PaginatedResult.cs                # Generic paginated response model
│   └── PaginationParams.cs              # Pagination request parameters
├── Repositories/
│   ├── IRepository.cs                    # Generic CRUD repository interface
│   └── IProjectRepository.cs            # Specialized project repository
└── UoW/
    └── IUnitOfWork.cs                    # Unit of Work interface for transactions

Infrastructure (src/Infrastructure/)

Data access implementations using both EF Core and Dapper.

Infrastructure/
├── Infrastructure.csproj                 # EF Core, Dapper, Dapper.AOT, Npgsql, Bogus, Delta
├── DependencyInjection.cs                # Service registration for all data access
├── Usings.cs
├── Common/
│   ├── Context/
│   │   ├── ApplicationDbContext.cs       # EF Core DbContext implementation
│   │   └── IApplicationDbContext.cs      # DbContext interface
│   ├── Helpers/
│   │   └── FakeDataHelper.cs             # Bogus-based test data generator
│   └── Mappings/
│       └── ...                           # EF Core entity configurations
├── Migrations/
│   └── ...                               # EF Core database migrations
├── Repositories/
│   ├── DapperRepository.cs               # Generic Dapper CRUD repository
│   └── ProjectRepository.cs             # Specialized Dapper project repository
└── UoW/
    └── UnitOfWork.cs                     # Dapper-based Unit of Work with transactions

WebApi (src/WebApi/)

REST API using FastEndpoints with EF Core data access.

WebApi/
├── WebApi.csproj                         # FastEndpoints, Swagger, Mapperly, OpenTelemetry
├── Program.cs                            # App configuration (rate limiting, health checks, Swagger)
├── AssemblyInfo.cs
├── Usings.cs
├── Dockerfile                            # Multi-stage build with AOT/Trim support
├── Common/
│   └── Dtos/                             # Data transfer objects
├── Endpoints/
│   ├── Appointment/
│   │   ├── CreateAppointment/            # POST /api/appointment
│   │   │   ├── Endpoint.cs
│   │   │   └── Models.cs                 # Request/Response models
│   │   ├── GetAppointmentById/           # GET /api/appointment/{id}
│   │   ├── ListAppointments/             # GET /api/appointment
│   │   ├── RemoveAppointment/            # DELETE /api/appointment/{id}
│   │   └── UpdateAppointment/            # PUT /api/appointment/{id}
│   ├── Assignment/                       # Same 5 CRUD endpoints
│   ├── AssignmentImpediment/
│   ├── AssignmentType/
│   ├── Impediment/
│   ├── Organization/
│   ├── Project/
│   ├── User/
│   ├── UserAssignment/
│   ├── UserProject/
│   └── Workflow/
├── Middlewares/
│   ├── ElapsedTimeMiddleware.cs          # Request timing
│   └── ErrorHandlingMiddleware.cs        # Global error handling
├── Properties/
│   └── launchSettings.json
├── ServiceExtensions/
│   └── ...                               # OpenTelemetry configuration
├── appsettings.json
├── appsettings.Development.json
└── appsettings.Testing.json

GrpcServer (src/GrpcServer/)

gRPC command server using FastEndpoints Remote Messaging with Dapper data access.

GrpcServer/
├── GrpcServer.csproj                     # FastEndpoints.Messaging.Remote, Mapperly, OpenTelemetry
├── Program.cs                            # HTTP/2 on port 5021, handler registration (55 handlers)
├── Usings.cs
├── Dockerfile
├── Common/
│   └── Dtos/                             # Data transfer objects
├── Handlers/
│   ├── Appointment/
│   │   ├── CreateAppointmentHandler.cs
│   │   ├── GetAppointmentByIdHandler.cs
│   │   ├── ListAppointmentsHandler.cs
│   │   ├── RemoveAppointmentHandler.cs
│   │   └── UpdateAppointmentHandler.cs
│   ├── Assignment/                       # Same 5 handlers per entity
│   ├── AssignmentImpediment/
│   ├── AssignmentType/
│   ├── Impediment/
│   ├── Organization/
│   ├── Project/
│   ├── User/
│   ├── UserAssignment/
│   ├── UserProject/
│   └── Workflow/
├── Properties/
│   └── launchSettings.json
├── ServiceExtensions/
│   └── ...                               # OpenTelemetry configuration
├── appsettings.json
└── appsettings.Development.json

GrpcServer.Contracts (src/GrpcServer.Contracts/)

Shared command/result contracts between gRPC client and server.

GrpcServer.Contracts/
├── GrpcServer.Contracts.csproj           # FastEndpoints.Messaging.Core, Domain reference
├── Usings.cs
├── Common/
│   └── Dtos/                             # Shared DTOs
└── Commands/
    ├── Appointment/                      # CreateAppointmentCommand, GetAppointmentByIdCommand, etc.
    ├── Assignment/
    ├── AssignmentImpediment/
    ├── AssignmentType/
    ├── Impediment/
    ├── Organization/
    ├── Project/
    ├── User/
    ├── UserAssignment/
    ├── UserProject/
    └── Workflow/

IdentityApi (src/IdentityApi/)

JWT authentication service.

IdentityApi/
├── IdentityApi.csproj                    # FastEndpoints, FastEndpoints.Security, Swagger, OpenTelemetry
├── Program.cs                            # JWT config, rate limiting (10/min), output caching
├── Usings.cs
├── Dockerfile
├── Endpoints/
│   └── Login/
│       ├── Endpoint.cs                   # POST /api/login
│       └── Models.cs                     # Request (Login, Password) / Response (Token)
├── Middlewares/
│   ├── ElapsedTimeMiddleware.cs
│   └── ErrorHandlingMiddleware.cs
├── Properties/
│   └── launchSettings.json
├── ServiceExtensions/
│   └── ...                               # OpenTelemetry configuration
├── appsettings.json
└── appsettings.Development.json

WebClient (src/WebClient/)

Blazor Server + WebAssembly frontend.

WebClient/
├── WebClient.csproj                      # MudBlazor, MudBlazor.Translations, OpenTelemetry
├── Program.cs                            # Blazor hybrid rendering, MudBlazor services
├── Usings.cs
├── Dockerfile
├── Components/
│   └── ...                               # Blazor components
├── Properties/
│   └── launchSettings.json
├── ServiceExtensions/
│   └── ...                               # OpenTelemetry configuration
├── wwwroot/
│   └── ...                               # Static assets
├── appsettings.json
└── appsettings.Development.json

Test Projects (test/)

Architecture.Tests (test/Architecture.Tests/)

Validates Clean Architecture dependency rules using NetArchTest.

Architecture.Tests/
├── Architecture.Tests.csproj             # xUnit, NetArchTest.Rules, FluentAssertions
├── ArchitectureTests.cs                  # 25+ architecture validation tests
├── Usings.cs
└── README.md

WebApi.Unit.Tests (test/WebApi.Unit.Tests/)

Unit tests for WebApi endpoints.

WebApi.Unit.Tests/
├── WebApi.Unit.Tests.csproj              # NUnit, FakeItEasy, Shouldly, FastEndpoints
├── Endpoints/
│   └── ...                               # Endpoint unit tests
├── Usings.cs
└── README.md

WebApi.Integration.Tests (test/WebApi.Integration.Tests/)

Integration tests running against real services.

WebApi.Integration.Tests/
├── WebApi.Integration.Tests.csproj       # xUnit v3, FastEndpoints.Testing, Shouldly
├── AssemblyInfo.cs
├── Endpoints/
│   └── ...                               # Endpoint integration tests
├── Hosts/
│   └── ...                               # Test host configuration
└── Usings.cs

Configuration Files

Technologies

Technologies

Runtime & Framework

Web Frameworks & API

Data Access

Database

Authentication

Mapping

Querying

Observability & Monitoring

Frontend

Testing

Infrastructure & DevOps

Build Optimization

Testing

Testing

Cpnucleo has three test projects covering architecture validation, unit testing, and integration testing.

Test Projects Overview

Architecture Tests (test/Architecture.Tests/)

These tests enforce Clean Architecture dependency rules at build time using NetArchTest and FluentAssertions. They run as part of both the PR build check and the release pipeline.

Layer Dependency Tests

Domain Layer Tests

Infrastructure Layer Tests

Naming Convention Tests

Clean Architecture Pattern Tests

Unit Tests (test/WebApi.Unit.Tests/)

Unit tests for WebApi endpoints using NUnit with FakeItEasy for mocking and Shouldly for assertions.

Structure

WebApi.Unit.Tests/
├── Endpoints/
│   └── ...                    # Tests organized by endpoint
├── Usings.cs
└── WebApi.Unit.Tests.csproj

Key Libraries

Integration Tests (test/WebApi.Integration.Tests/)

Integration tests that exercise the full request pipeline using FastEndpoints.Testing and xUnit v3.

Structure

WebApi.Integration.Tests/
├── AssemblyInfo.cs
├── Endpoints/
│   └── ...                    # Integration tests by endpoint
├── Hosts/
│   └── ...                    # Test host/server configuration
├── Usings.cs
└── WebApi.Integration.Tests.csproj

Key Libraries

Prerequisites

Integration tests require a running PostgreSQL database. In CI, this is provisioned via Docker Compose:

docker compose up db -d --build --force-recreate
sleep 30

Integration tests are currently commented out in CI workflows and are run manually.

Running Tests

Run All Tests

dotnet test cpnucleo.slnx

Run Architecture Tests Only

dotnet test test/Architecture.Tests/

Run Unit Tests Only

dotnet test test/WebApi.Unit.Tests/

Run Integration Tests (requires running database)

# Start the database first
docker compose up db -d
sleep 30

# Run integration tests
dotnet test test/WebApi.Integration.Tests/

Run with Code Coverage

dotnet test --collect:"XPlat Code Coverage"

CI Pipeline Test Execution

Architecture tests run automatically in both CI workflows:

• build-check.yml (PR): runs architecture tests for each service (WebApi, GrpcServer, IdentityApi, WebClient)
• main-release.yml (push to main): runs architecture tests before building Docker images

Unit and integration tests are configured in the workflows but currently commented out, pending further setup.