Deep dives on enterprise .NET

Open-sourced and graded against 34 categories

Why I open-sourced a production .NET framework and scored it against a 34-category architecture rubric, gaps and all.

Modular monolith to microservices

The cornerstone idea: build the monolith now and extract a service later with no rewrite, via module discovery, gRPC contracts, and a YARP gateway.

• ADR 006
• ADR 007
• ADR 008

The 34-category architecture rubric

A two-axis rubric for scoring architecture on maturity and implementation, so 'good architecture' stops being a vibe.

The Result railway in C#

Model expected failures as Result values with a transport-agnostic error type, and keep exceptions for the genuinely exceptional.

• ADR 013

Kill the anemic domain model

Push behavior into rich aggregates with factory methods and invariants instead of bags of public setters.

Specifications over LINQ spaghetti

Compose queries from reusable specification objects instead of scattering LINQ across handlers.

• ADR 055

The CQRS decorator pipeline

Thin command and query handlers wrapped by a Scrutor decorator chain whose order is load-bearing.

• ADR 014

Compose validators, don't copy them

A validation kit that composes FluentValidation rules instead of copy-pasting them across features.

The transactional outbox

Events that survive a crash: persist them atomically with your data, then dispatch at least once.

• ADR 003

Database-per-service inside a monolith

Give each module its own database and outbox before you extract it, so extraction changes hosting, not data.

• ADR 006

Polyglot persistence: one model, three engines

SQL Server, Cosmos, and SQLite behind a single entity model, with the engine chosen by attribute.

• ADR 018

Navigation populators

Eager-load relationships that cross containers and data sources without N+1 or a leaky abstraction.

• ADR 002

Optimistic concurrency: RowVersion round-trips

Carry the RowVersion from database to DTO and back, so a concurrent edit fails fast as a conflict instead of silently overwriting.

• ADR 035

Self-ordering modules

Modules declare their dependencies and load in topological order, so registration is never hand-sequenced.

Event-schema versioning

Every integration event carries a schema version; breaking changes get a new event type and an upcaster, never a silent reshape.

• ADR 010

JWKS cross-service auth

Validate another service's RS256 tokens via JWKS discovery, with no shared secret crossing a boundary.

• ADR 004

Password hashing done right

The non-negotiables of password storage in .NET, done correctly and tested.

• ADR 032

Idempotency in one attribute

Dedup client retries with an Idempotency-Key header and cached replay, plus a consumer-side inbox for brokers.

• ADR 017
• ADR 021

The self-invalidating cache

A caching decorator where commands invalidate and queries populate, plus an authenticated output-cache tier at the API edge.

• ADR 026
• ADR 040

Problem Details across HTTP and gRPC

One error contract mapped consistently to HTTP Problem Details and gRPC status.

Notifications as a vertical slice

A notifications feature built as a clean vertical slice across every layer.

• ADR 024

Live channels over one SignalR hub

Sub-second ephemeral events (polls, Q&A, live counts) fanned out over the existing notification hub, with nothing persisted.

• ADR 039

Delete AutoMapper: manual DTO mapping

Why source-generated, per-entity mappers beat reflection-based mapping for clarity and speed.

• ADR 001

Permission-based authorization over roles

A capability layer over RBAC: permission policies that resolve on demand from a central registry.

• ADR 020

Browser session-cookie auth for Blazor SSR

HttpOnly session cookies and an SSR-time scheme so [Authorize] passes during prerender, with the API still the boundary.

• ADR 022

External OAuth login behind your own JWTs

Sign in with Google or GitHub without leaking provider tokens: external identity exchanged for your own JWTs at the boundary.

• ADR 036

One rotating refresh token

A short-lived JWT plus one server-stored refresh token that rotates on every use, with reuse detection that makes a stolen token end its own session.

• ADR 050

Generic entity controllers

A write-once REST surface every entity inherits, plus a bounded dynamic query contract that is never open SQL.

• ADR 034

Resource-ownership authorization

Beyond roles and permissions: which rows you may touch, enforced per resource.

• ADR 033

Rate limiting and brute-force protection

Two layers that cover the whole API edge: endpoint rate limits plus lockout-based brute-force defense on identity.

• ADR 019
• ADR 029

Aspire: one command

Model services, databases, and the broker as one Aspire graph that runs from laptop to Azure with one command.

• ADR 023
• ADR 025
• ADR 041

Extracting a module to a gRPC service

A step-by-step extraction of an in-process module into its own gRPC service, database, and auth.

• ADR 007
• ADR 008
• ADR 012

Resilience and recovery objectives

Standard resilience on every outbound client, plus declared RTO/RPO and a drilled restore.

• ADR 009

Architecture fitness functions

Architecture rules that fail the build: a compile-time layer guard plus a shared NetArchTest rule library.

• ADR 015

The test pyramid

How the framework's tests stack up: fast unit and architecture tests at the base, E2E at the tip.

Soft-delete vs the right to erasure

Soft-delete for lifecycle, anonymization plus outbox purge for GDPR/CCPA erasure, and why both exist.

• ADR 005

A reusable Blazor UI framework

A shared Blazor and MudBlazor UI layer with accessibility enforced by axe in CI.

i18n and theming on one preference pipeline

A culture choice and a theme choice ride the same cookie, profile column, and login reconciliation: one persistence path, two switches.

• ADR 027
• ADR 028

Build your first module

A hands-on walkthrough of building a new module across all five layers.

Write your first fitness test

Author your first architecture fitness test and watch it fail the build on a violation.

• ADR 015

Two real apps on one framework

A case study: a conference platform and an e-commerce store built on the same kernel.

One Blazor UI, two hosts

The same Blazor components run in a browser and inside a MAUI hybrid app; small per-capability contracts reach native hardware without ever asking 'am I on mobile?'.

• ADR 042
• ADR 043

Managed file storage: uploads you don't have to trust

Attacker-controlled bytes become safe avatars: content sniffing, metadata stripping, re-encoding, and pluggable blob storage.

• ADR 045

HTTP API versioning, proven not just claimed

Header-based versioning introduced without breaking a single caller, plus a fitness contract that proves two live versions coexist.

• ADR 046

Feature flags in the CQRS pipeline

Gate commands and queries at the outermost decorator, so a handler never checks a flag and a disabled feature is rejected before any work runs.

• ADR 031

Field-level encryption in EF Core

An AES-256-GCM value converter that keeps a PII column ciphertext even for someone who can query the database.

• ADR 037

Security headers and CSP for Blazor

One middleware stamps hardened response headers on every host, with the Blazor CSP resolved through a pluggable provider.

• ADR 023

Observability by default

A shared OpenTelemetry baseline with CQRS duration metrics, correlation IDs, and outbox-poll span filtering, exported to Azure Monitor.

• ADR 041

Saga compensation and the reconciliation backstop

Undo as a first-class event handler: give back stock a committed transaction already took, with a periodic sweep as the saga-timeout backstop.

• ADR 054

The series index

The full series index and recommended reading order.