Building a Headless Blog Engine with .NET 8, Clean Architecture, and Zero-Cost Cloud

When I set out to build my personal portfolio and technical blog, I intentionally avoided ready-made CMS platforms or bloated, monolithic frameworks. As a software engineer, my goal was to turn the platform itself into a core case study in software engineering: a modular, decoupled, and secure solution designed to run in production with zero infrastructure costs.

In this inaugural post, I break down the architectural decisions, design patterns, and continuous delivery pipeline powering the Dev Portfolio & Headless Blog API.

---

🎯 Requirements & Key Design Decisions

The API was designed from the ground up as a canonical backend engine adhering to core principles:

• Pragmatic Clean Architecture with Vertical Slices: The enterprise domain remains completely pure and isolated from external concerns, while the application layer is partitioned into focused, discrete feature slices rather than monolithic, bloated service classes.
• Native Multilingual Support (i18n): First-class support for bilingual content (pt-BR and en-US), enforced at the database level via translation grouping (TranslationGroupId) with unique constraints per language.
• Hardened Single-Admin Security: Cryptographic password hashing using PBKDF2 (100,000 iterations with unique salts and constant-time byte comparisons) coupled with HMAC-SHA256 signed JWT Bearer tokens for administrative routes.
• RFC 7807 ProblemDetails Standard: Centralized exception handling ensuring machine-readable, consistent error envelopes across all HTTP boundaries.
• Zero Runtime Migrations: Standalone, idempotent EF Core Migration Bundles compiled inside CI pipelines to completely prevent startup container deadlocks.

---

🏗️ Architectural Overview

The application follows a pragmatic three-layer Clean Architecture model, isolating pure business invariants from delivery mechanisms and persistence details:

graph TD
    subgraph Presentation ["Presentation Layer (Blog.Api)"]
        Routes["Minimal API Endpoints<br>(/posts, /categories, /auth)"]
        AuthMid["JWT Bearer Authentication & Policies"]
        ExHandler["GlobalExceptionHandler (RFC 7807)"]
        Swagger["Swagger UI & OpenAPI Explorer"]
    end

    subgraph Application ["Application Layer (Blog.Application)"]
        VS_Posts["Posts Slices<br>(Create, Update, Publish, SoftDelete, Feeds)"]
        VS_Drafts["Drafts Slices<br>(ListDrafts, GetDraftById)"]
        VS_Categories["Categories Slices<br>(List, GetBySlug, Create)"]
        VS_Auth["Auth Slices<br>(LoginHandler, JWT Token Generation)"]
    end

    subgraph Domain ["Domain Layer (Blog.Domain)"]
        Entities["Entities<br>(Post, Category, Tag, User)"]
        Enums["Enums (PostStatus: Draft, Published, Archived)"]
        Interfaces["Repository Interfaces<br>(IPostRepository, ICategoryRepository, IUserRepository)"]
        Helpers["SlugHelper & Password Hashing Contracts"]
    end

    subgraph Infrastructure ["Infrastructure & Persistence (Blog.Api/Data)"]
        EF["Entity Framework Core 8 (AppDbContext)"]
        PG[("PostgreSQL Database (Supabase)")]
    end

    Routes --> VS_Posts & VS_Drafts & VS_Categories & VS_Auth
    VS_Posts & VS_Drafts & VS_Categories & VS_Auth --> Interfaces
    VS_Posts & VS_Drafts & VS_Categories & VS_Auth --> Entities
    EF --> PG
    Interfaces -.->|Implemented by| EF