A production-ready backend API for a modern blogging platform built with .NET 11, following Clean Architecture, Domain-Driven Design (DDD), and CQRS.
- Features
- Technology Stack
- Architecture Overview
- Project Structure
- Getting Started
- API Overview
- Production Configuration
- License
- Identity & Access Control (Keycloak OIDC):
- Asynchronous user provisioning via the Transactional Outbox Pattern with DataProtection-encrypted credential transit and automatic payload scrubbing.
- Role-based (
Registered,Administrator) and resource-ownership authorization (BOLA/IDOR protection on posts and comments, admin moderation support).
- Content & Taxonomy Management:
- Full lifecycle management for Posts (
Draft,Published,Archived), Categories, Tags, and Comments. - Public anonymous reads for published content; non-published posts (
Draft/Archived) and their comments are restricted to their author and administrators. - Paginated list endpoints (
?page=1&pageSize=20, capped at100) withPagedResponse<T>metadata and PostgreSQLuuid[]GIN-indexed taxonomy filtering.
- Full lifecycle management for Posts (
- Distributed Caching & Tag Invalidation:
- Redis-backed
ICacheServicewith graceful degradation on cache outages and Redis-set tag invalidation (cache-tag:*) to evict related entries across posts, categories, and tags. - Cache eligibility gating prevents non-published posts from ever entering the shared cache.
- Redis-backed
- Reliable Asynchronous Processing (Outbox Pattern):
- Quartz.NET workers using PostgreSQL
FOR UPDATE SKIP LOCKED, worker leases (locked_by,locked_until_utc), exponential backoff, poison-message handling,[JsonDerivedType]polymorphic event allowlisting, and hourly retention cleanup (OutboxCleanupJob).
- Quartz.NET workers using PostgreSQL
- API Hardening & Resilience:
- Built-in ASP.NET Core Rate Limiting (
authIP-partitioned policy andapiuser/IP-partitioned policy) returning RFC 9457ProblemDetails(429). Microsoft.Extensions.Http.Resiliencestandard resilience pipelines for Keycloak communication with cached client-credentials admin tokens.- Reverse-proxy
ForwardedHeaders, environment-aware CORS allowlisting, Brotli/Gzip response compression, and URL-segment API versioning (/api/v1/...).
- Built-in ASP.NET Core Rate Limiting (
- Observability & Health Checks:
- OpenTelemetry distributed tracing & runtime/DB metrics exported via OTLP gRPC (Aspire Dashboard), structured logging via Serilog + Seq with correlation IDs and credential masking.
- Separate
/health/live,/health/ready, and/healthprobes for PostgreSQL, Redis, and Keycloak.
| Area | Technology / Library |
|---|---|
| Runtime & Web | .NET 11 (net11.0), ASP.NET Core 11 |
| Architecture & Patterns | Clean Architecture, DDD, CQRS (MediatR 12.5), Result Pattern |
| Database | PostgreSQL (18.7) with GIN indexes on uuid[] taxonomy columns |
| ORM & Data Access | Entity Framework Core 10.0, Npgsql.EntityFrameworkCore.PostgreSQL, Dapper |
| Authentication | Keycloak (26.0.7, OAuth 2.0 / OIDC JWT Bearer), ASP.NET Core DataProtection |
| Caching | Redis (8.10) via IDistributedCache + StackExchange.Redis tag sets |
| Resilience & Rate Limiting | Microsoft.Extensions.Http.Resilience, Microsoft.AspNetCore.RateLimiting |
| Validation | FluentValidation |
| Background Jobs | Quartz.NET (4.7) |
| API & Documentation | Asp.Versioning.Mvc, Microsoft.AspNetCore.OpenApi, Scalar (Scalar.AspNetCore) |
| Observability | OpenTelemetry (OTLP), .NET Aspire Dashboard, Serilog, Seq |
| Testing | xUnit v3 (Microsoft.Testing.Platform), Shouldly, NSubstitute, NetArchTest, Testcontainers |
Blogify enforces strict unidirectional dependencies using NetArchTest.Rules:
- Domain: Entities, Value Objects, Domain Events, Repository interfaces, and
Result/Errorprimitives (zero external infrastructure dependencies). - Application: CQRS Commands/Queries, FluentValidation validators, MediatR pipeline behaviors (
Logging,Validation,QueryCaching,CacheInvalidation). - Infrastructure: EF Core & Dapper persistence, PostgreSQL outbox & Quartz jobs, Redis caching & DataProtection key ring, Keycloak authentication/authorization handlers.
- API (Presentation): Versioned REST controllers, RFC 9457
ProblemDetailsexception mapping, rate limiting, health probes, and OpenAPI/Scalar docs.
graph TD
USER[Client] -->|HTTPS| API[Blogify API]
subgraph "API & Application"
API --> APP[MediatR Pipeline\nLogging · Validation · Caching]
end
subgraph "Infrastructure"
APP -->|Writes & Reads| DB[(PostgreSQL)]
APP -->|Cache & Tag Sets| REDIS[(Redis)]
API -->|OIDC / JWT| KEYCLOAK[Keycloak]
QUARTZ[Quartz.NET\nOutbox & Cleanup Jobs] -->|SKIP LOCKED Poll| DB
QUARTZ -->|Provision Identity| KEYCLOAK
QUARTZ -->|Publish Events| APP
end
subgraph "Observability"
API -->|Structured Logs| SEQ[Seq]
API -->|Traces & Metrics| ASPIRE[Aspire Dashboard\nOTLP/gRPC]
end
classDef app fill:#e6f3ff,stroke:#0066cc,stroke-width:2px;
classDef infra fill:#fff5e6,stroke:#ff9900,stroke-width:2px;
classDef db fill:#d9f2d9,stroke:#009900,stroke-width:2px;
class API,APP app;
class KEYCLOAK,QUARTZ,SEQ,ASPIRE infra;
class DB,REDIS db;
├── src/
│ ├── Blogify.Domain/ # Aggregates, Value Objects, Domain Events, Result/Error
│ ├── Blogify.Application/ # CQRS handlers, Validators, Pipeline Behaviors, Abstractions
│ ├── Blogify.Infrastructure/ # EF Core, Dapper, Outbox, Redis Cache, Keycloak, Quartz
│ └── Blogify.Api/ # Controllers, Middleware, Rate Limiting, OpenAPI/Scalar
├── test/
│ ├── Blogify.Domain.UnitTests/
│ ├── Blogify.Application.UnitTests/
│ ├── Blogify.Infrastructure.UnitTests/
│ ├── Blogify.ArchitectureTests/
│ └── Blogify.FunctionalTests/ # End-to-end tests backed by Testcontainers
├── docker-compose/ # Full local stack (API, Postgres, Redis, Keycloak, Seq, Aspire)
├── Directory.Build.props # Shared target framework (net11.0) & test packages
├── Directory.Packages.props # Central Package Management (CPM)
└── global.json # .NET 11 SDK & Microsoft.Testing.Platform config
- .NET 11 SDK (
11.0.100+) - Docker & Docker Compose (for running the full stack and functional tests)
From the repository root:
docker compose -f docker-compose/docker-compose.yml up --buildThe compose stack starts the API and all supporting infrastructure (including automatic EF Core migrations and pre-imported Keycloak realm in Development):
| Service | URL / Port | Purpose |
|---|---|---|
| Blogify API | http://localhost:5000 |
REST API |
| Scalar API Reference | http://localhost:5000/scalar/v1 |
Interactive API docs (Development only) |
| OpenAPI Spec | http://localhost:5000/openapi/v1.json |
OpenAPI JSON document (Development only) |
| Health Probes | /health, /health/live, /health/ready |
Liveness & dependency readiness |
| Keycloak | http://localhost:18080 |
Identity Provider (admin / admin) |
| PostgreSQL | localhost:5454 |
Primary database (blogify) |
| Redis | localhost:6379 |
Distributed cache & DataProtection key ring |
| Seq | http://localhost:8082 |
Structured log viewer |
| Aspire Dashboard | http://localhost:18888 |
OpenTelemetry traces & metrics |
Run the entire solution test suite (unit, architecture, and Docker-backed functional tests):
dotnet test Blogify.slnxNote:
Blogify.FunctionalTestsspins up real PostgreSQL, Redis, and Keycloak containers via Testcontainers, so Docker must be running.
All endpoints are versioned under /api/v1:
| Resource | Public ([AllowAnonymous]) |
Authenticated (Registered) |
Admin Only (Administrator) |
|---|---|---|---|
| Users | POST /users/register, POST /users/login (rate-limited) |
GET /users/me |
— |
| Posts | GET /posts, GET /posts/{id}, GET /posts/author/{id}, GET /posts/category/{id}, GET /posts/tag/{id} (Published only) |
GET /posts/mine, POST /posts, PUT/DELETE /posts/{id}, PUT /posts/{id}/publish|archive, tags & categories (Owner or Admin) |
Can modify/delete any post |
| Comments | GET /comments/{id}, GET /comments/by-post/{postId} (Published posts only) |
POST /comments, PUT /comments/{id} (Author only), DELETE /comments/{id} (Author or Admin) |
Can delete any comment |
| Categories | GET /categories, GET /categories/{id}, GET /categories/with-post-count |
— | POST, PUT, DELETE |
| Tags | GET /tags, GET /tags/{id} |
— | POST, PUT, DELETE |
List endpoints accept ?page=1&pageSize=20 (pageSize capped at 100) and return:
{
"items": [],
"page": 1,
"pageSize": 20,
"totalCount": 0,
"totalPages": 0,
"hasNextPage": false,
"hasPreviousPage": false
}appsettings.Production.json disables automatic startup migrations and enforces HTTPS metadata by default. Before deploying to production, configure the following via environment variables or a secret store:
- Connection Strings:
ConnectionStrings__Database,ConnectionStrings__Cache - Keycloak & JWT:
Authentication__Issuer,Authentication__MetadataUrl,Authentication__Audience,Keycloak__BaseUrl,Keycloak__AdminUrl,Keycloak__TokenUrl,Keycloak__AdminClientId,Keycloak__AdminClientSecret,Keycloak__AuthClientId,Keycloak__AuthClientSecret - CORS:
Cors__AllowedOrigins__0=https://your-frontend.example(empty array rejects cross-origin requests outsideDevelopment) - Reverse Proxy:
ForwardedHeaders__KnownProxies__0/KnownNetworks__0(required behind Nginx/Traefik/Cloudflare/ALB so IP-based rate limiting and scheme detection see the real client IP) - Database Migrations: Apply EF Core migrations explicitly in your CI/CD pipeline (
dotnet ef database update) prior to starting application instances. - Bootstrap Admin: Assign the seeded
Administratorrole (roles_id = 2) inrole_userto your initial admin account.
This project is licensed under the MIT License — see the LICENSE file for details.