DEV Community: Brian Spann

Clean Architecture in .NET 10: The Domain Layer — Entities That Actually Have Behavior

Brian Spann — Thu, 29 Jan 2026 17:00:00 +0000

Part 2 of 7. Start from the beginning if you're new here.

In Part 1, we set up our solution structure and created our first entity with real behavior. Now we'll flesh out the Domain layer properly—value objects, the Collection aggregate, and honest talk about when your "domain" is too thin to bother.

The Domain Layer's Job

The Domain layer has one job: encode the business rules that would exist even if there were no computers.

"A prompt must have a title" — business rule
"Updating a prompt creates a version" — business rule
"Tags are case-insensitive" — business rule
"The database column is NVARCHAR(500)" — not a business rule

If you find yourself thinking about HTTP status codes, SQL queries, or JSON serialization in your Domain project, you've gone off track.

Value Objects: Wrapping Primitives That Deserve It

The typical Clean Architecture tutorial tells you to wrap everything:

// This is often shown, but...
public record Email(string Value);
public record FirstName(string Value);
public record LastName(string Value);

🔥 Real talk: Most of the time, this is pointless ceremony. You've created a wrapper that does nothing but add .Value everywhere.

Value objects earn their keep when they have behavior or validation:

src/PromptVault.Domain/ValueObjects/Tag.cs

namespace PromptVault.Domain.ValueObjects;

public readonly record struct Tag
{
    public string Value { get; }
    public string Slug { get; }

    public Tag(string value)
    {
        if (string.IsNullOrWhiteSpace(value))
            throw new ArgumentException("Tag cannot be empty", nameof(value));

        if (value.Length > 50)
            throw new ArgumentException("Tag cannot exceed 50 characters", nameof(value));

        Value = value.Trim();
        Slug = Slugify(Value);
    }

    private static string Slugify(string input)
    {
        return input
            .ToLowerInvariant()
            .Replace(" ", "-")
            .Replace("_", "-");
    }

    public static implicit operator string(Tag tag) => tag.Value;

    public override string ToString() => Value;
}

Why this value object earns its place:

Validation: can't create empty or too-long tags
Behavior: auto-generates a slug
Implicit conversion: can use it where strings are expected

But don't do this:

// ❌ Pointless wrapper — just use string
public readonly record struct PromptTitle(string Value);

Unless PromptTitle has validation or behavior beyond "is not null," it's noise.

ModelType: When Enums Aren't Enough

For ModelType (gpt-4, claude-3, etc.), we have options:

Option 1: Just use a string

public string ModelType { get; private set; }

Simple. Works. But any string is accepted.

Option 2: Enum

public enum ModelType { Gpt4, Gpt4Turbo, Claude3Opus }

Type-safe, but adding new models requires code changes and redeployment.

Option 3: Smart Value Object

public readonly record struct ModelType
{
    public string Value { get; }
    public string Provider { get; }

    // Well-known models
    public static readonly ModelType Gpt4 = new("gpt-4", "openai");
    public static readonly ModelType Claude3Opus = new("claude-3-opus", "anthropic");

    public ModelType(string value, string? provider = null)
    {
        if (string.IsNullOrWhiteSpace(value))
            throw new ArgumentException("Model type is required", nameof(value));

        Value = value.Trim().ToLowerInvariant();
        Provider = provider?.ToLowerInvariant() ?? InferProvider(Value);
    }

    private static string InferProvider(string model)
    {
        if (model.StartsWith("gpt")) return "openai";
        if (model.StartsWith("claude")) return "anthropic";
        if (model.StartsWith("gemini")) return "google";
        return "unknown";
    }
}

Tradeoff acknowledged: This is more code than an enum. It's worth it if:

Users can enter custom model names
You want to infer provider from model name
New models shouldn't require code changes

For most apps, an enum is fine. Pick based on your needs, not architectural purity.

The Collection Entity

Let's add our second aggregate root: Collections (like folders for prompts).

namespace PromptVault.Domain.Entities;

public class Collection
{
    public Guid Id { get; private set; }
    public string Name { get; private set; } = null!;
    public string? Description { get; private set; }
    public bool IsPublic { get; private set; }
    public Guid OwnerId { get; private set; }
    public DateTime CreatedAt { get; private set; }

    private readonly List<Guid> _promptIds = new();
    public IReadOnlyCollection<Guid> PromptIds => _promptIds.AsReadOnly();

    private Collection() { }

    public Collection(string name, Guid ownerId, string? description = null)
    {
        if (string.IsNullOrWhiteSpace(name))
            throw new ArgumentException("Name is required", nameof(name));

        Id = Guid.NewGuid();
        Name = name.Trim();
        Description = description?.Trim();
        OwnerId = ownerId;
        CreatedAt = DateTime.UtcNow;
    }

    public void AddPrompt(Guid promptId)
    {
        if (!_promptIds.Contains(promptId))
            _promptIds.Add(promptId);
    }

    public void RemovePrompt(Guid promptId)
    {
        _promptIds.Remove(promptId);
    }

    public void MakePublic() => IsPublic = true;
    public void MakePrivate() => IsPublic = false;
}

Design Decision: IDs vs Navigation Properties

Notice we store List<Guid> _promptIds rather than List<Prompt> _prompts.

The purist approach: Store full Prompt entities.

The pragmatic approach: Store IDs. Why?

A prompt can be in multiple collections (many-to-many)
Loading a collection doesn't load all prompts
Avoids deep object graphs

⚠️ Real-world callout: If you store full entities, EF Core will try to load them all when you load a Collection. For a collection with 500 prompts, that's a problem.

The tradeoff: your domain doesn't enforce that those IDs actually exist. That's an infrastructure concern (foreign keys) or application concern (validation before adding).

The Anemic Domain: When It's Okay

Here's the uncomfortable truth: some domains really are just CRUD.

If your application is:

Accept data from user
Validate it
Store it
Retrieve it
Display it

...then your "domain logic" is basically just validation. That's fine. Don't invent complexity.

Signs Your Domain Is Actually Anemic

Every entity method is just a setter in disguise:

   public void UpdateTitle(string title) => Title = title;

All your "business rules" are just null checks and length limits
Your handlers do all the work; entities are just data bags

What To Do About It

Option A: Embrace it. Use EF Core entities directly. Skip the ceremony.

Option B: Keep the structure but be minimal. Thin Domain layer. Most logic in Application layer services.

Option C: Look harder for the domain. Often there IS logic hiding in:

"Only admins can delete"
"Can't change status from Published back to Draft"
"Title must be unique per user"

Where Does Validation Live?

Validation Type	Where It Lives	Example
Domain invariants	Entity constructors/methods	"Prompt must have content"
Business rules	Domain entities	"Updating content creates a version"
Input validation	Application layer (FluentValidation)	"Email must be valid format"
API contracts	API layer	"Field X is required in this request"

Overlap is okay. Checking "title is not empty" in both the API request validator AND the entity constructor is fine. Defense in depth.

Updated Prompt with Value Objects

Here's our refined Prompt entity using the Tag value object:

using PromptVault.Domain.ValueObjects;

namespace PromptVault.Domain.Entities;

public class Prompt
{
    public Guid Id { get; private set; }
    public string Title { get; private set; } = null!;
    public string Content { get; private set; } = null!;
    public ModelType ModelType { get; private set; }
    public DateTime CreatedAt { get; private set; }
    public DateTime? UpdatedAt { get; private set; }

    private readonly List<PromptVersion> _versions = new();
    public IReadOnlyCollection<PromptVersion> Versions => _versions.AsReadOnly();

    private readonly List<Tag> _tags = new();
    public IReadOnlyCollection<Tag> Tags => _tags.AsReadOnly();

    private Prompt() { }

    public Prompt(string title, string content, ModelType modelType)
    {
        // Validation...
        Id = Guid.NewGuid();
        Title = title.Trim();
        Content = content;
        ModelType = modelType;
        CreatedAt = DateTime.UtcNow;
        _versions.Add(new PromptVersion(this, 1, content));
    }

    public void AddTag(string tagValue)
    {
        var tag = new Tag(tagValue); // Validation happens here

        if (_tags.Any(t => t.Slug == tag.Slug))
            return; // Deduplicate by slug

        _tags.Add(tag);
        UpdatedAt = DateTime.UtcNow;
    }
}

Testing Domain Logic

public class PromptTests
{
    [Fact]
    public void AddTag_NormalizesDuplicates()
    {
        var prompt = new Prompt("Test", "Content", ModelType.Gpt4);

        prompt.AddTag("Machine Learning");
        prompt.AddTag("machine-learning"); // Same slug
        prompt.AddTag("MACHINE_LEARNING"); // Same slug again

        Assert.Single(prompt.Tags);
    }
}

public class TagTests
{
    [Theory]
    [InlineData("Machine Learning", "machine-learning")]
    [InlineData("AI_Tools", "ai-tools")]
    public void Constructor_NormalizesToSlug(string input, string expected)
    {
        var tag = new Tag(input);
        Assert.Equal(expected, tag.Slug);
    }

    [Fact]
    public void Constructor_WithEmptyValue_Throws()
    {
        Assert.Throws<ArgumentException>(() => new Tag(""));
    }
}

No mocks. No database. Pure logic.

What We Didn't Add

Things often shown in Domain layers that we're skipping:

Aggregate Root base class — Overkill unless you're doing event sourcing
Entity base class with Id — Just put Guid Id on each entity
Domain events — Overkill for this scope
Specification pattern — Query logic belongs in repositories

Keep it simple. Add complexity when you need it.

Domain Project Structure

src/PromptVault.Domain/
├── Entities/
│   ├── Prompt.cs
│   ├── PromptVersion.cs
│   └── Collection.cs
└── ValueObjects/
    ├── Tag.cs
    └── ModelType.cs

No references to EF Core. No references to ASP.NET. The domain is pure.

Key Takeaways

Value objects should earn their place — Don't wrap primitives that have no behavior
Entities enforce invariants — Validation in constructors and methods
Store IDs, not full entities — For many-to-many relationships and performance
Some domains are thin, and that's okay — Don't invent complexity
Pure domain = easy testing — No mocks, no setup, just logic

Coming Up

In Part 3, we'll build the Application layer:

Commands and Queries with MediatR
When handlers are overkill (and what to use instead)
Repository interfaces

👉 Part 3: The Application Layer — CQRS Without the Ceremony

Full source: github.com/bspann/promptvault

Clean Architecture in .NET 10: The Setup (And When It's Overkill)

Brian Spann — Wed, 28 Jan 2026 17:00:00 +0000

This is Part 1 of a 7-part series. Start from the beginning if you haven't read the introduction.

The Promise

You've seen the diagram. Concentric circles. Domain at the center. Dependencies pointing inward. The promise: code that's testable, maintainable, and survives framework upgrades.

The reality? Four projects for a CRUD API. Interfaces for everything. A CreateUserCommandHandler that does nothing but call a repository method. And somehow, adding a field to an entity requires touching six files.

Here's the thing: Clean Architecture isn't wrong. But the way it's typically taught—as a rigid folder structure—misses the point.

Clean Architecture is about dependency direction, not folder count.

What Problem Are We Actually Solving?

Before creating any folders, let's be clear about what Clean Architecture gives you:

1. Your domain logic doesn't depend on your database

You can swap EF Core for Dapper. You can move from SQL Server to Postgres. Your business rules don't care.

2. Your domain logic doesn't depend on your web framework

ASP.NET Core, Minimal APIs, gRPC—your core logic stays the same.

3. You can test business logic without spinning up infrastructure

No database. No HTTP. Just logic and assertions.

If you don't need these benefits—if you're building an internal tool that will never change databases, will always be ASP.NET, and has minimal business logic—you might not need Clean Architecture.

🔥 Real talk: A lot of enterprise software is just CRUD with authorization. For that, a well-organized monolith with sensible folders might be better than architectural astronautics.

When Clean Architecture Earns Its Keep

✅ Use it when:

You have real business rules beyond "save this to the database"
Multiple teams will work on the codebase
The project will live for years
You want to test business logic in isolation
You anticipate significant changes to infrastructure

❌ Skip it when:

It's a prototype or proof-of-concept
The entire "domain" is data in, data out
You're the only developer and will be for the foreseeable future
You're time-boxed and need to ship

For PromptVault, we have real business rules: prompt versioning, tag normalization, collection access control. Clean Architecture makes sense.

The Project Structure

Let's create our solution. No magic templates—just dotnet CLI so you understand every file.

mkdir PromptVault
cd PromptVault

# Create the solution
dotnet new sln -n PromptVault

# Create projects
mkdir src tests

# Domain - the core, no dependencies
dotnet new classlib -n PromptVault.Domain -o src/PromptVault.Domain

# Application - use cases, orchestration
dotnet new classlib -n PromptVault.Application -o src/PromptVault.Application

# Infrastructure - EF Core, external services
dotnet new classlib -n PromptVault.Infrastructure -o src/PromptVault.Infrastructure

# API - HTTP layer
dotnet new webapi -n PromptVault.API -o src/PromptVault.API

# Add to solution
dotnet sln add src/PromptVault.Domain
dotnet sln add src/PromptVault.Application
dotnet sln add src/PromptVault.Infrastructure
dotnet sln add src/PromptVault.API

The Dependency Rules

This is the part that matters more than folder names:

# Application depends on Domain (can use entities, value objects)
dotnet add src/PromptVault.Application reference src/PromptVault.Domain

# Infrastructure depends on Domain AND Application
# (implements interfaces defined in Application)
dotnet add src/PromptVault.Infrastructure reference src/PromptVault.Domain
dotnet add src/PromptVault.Infrastructure reference src/PromptVault.Application

# API depends on Application AND Infrastructure
# (wires everything together)
dotnet add src/PromptVault.API reference src/PromptVault.Application
dotnet add src/PromptVault.API reference src/PromptVault.Infrastructure

The key insight: Domain depends on nothing. Application depends only on Domain. Infrastructure implements what Application defines. API composes it all.

┌─────────────────────────────────────────┐
│                  API                     │
│         (composition root)               │
└───────────────┬─────────────────────────┘
                │ references
    ┌───────────┴───────────┐
    │                       │
    ▼                       ▼
┌─────────────┐      ┌─────────────────┐
│ Application │      │ Infrastructure  │
│ (use cases) │      │ (EF, external)  │
└──────┬──────┘      └────────┬────────┘
       │                      │
       │    references        │ implements
       ▼                      │
┌─────────────┐               │
│   Domain    │ ◄─────────────┘
│  (entities) │
└─────────────┘

But Wait—Four Projects for What?

Here's the honest conversation we need to have.

You're about to create a User entity in Domain. Then an IUserRepository interface in Application. Then a UserRepository implementation in Infrastructure. Then inject it in API. For every entity. Forever.

The criticism is valid. If your app is small, this is overhead. The response to that criticism isn't "trust the process." It's:

Accept the overhead for the benefit. You're paying upfront for future flexibility.
Or don't use this architecture. A single project with folders (/Entities, /Data, /Controllers) is fine for many apps.

We're using Clean Architecture for PromptVault because:

Prompt versioning has real business logic
We want to test that logic without a database
This is a teaching exercise that should scale to real projects

Initial Domain Setup

Let's create our first entity. In Clean Architecture, domain entities have behavior, not just properties.

src/PromptVault.Domain/Entities/Prompt.cs

namespace PromptVault.Domain.Entities;

public class Prompt
{
    public Guid Id { get; private set; }
    public string Title { get; private set; } = null!;
    public string Content { get; private set; } = null!;
    public string ModelType { get; private set; } = null!;
    public DateTime CreatedAt { get; private set; }
    public DateTime? UpdatedAt { get; private set; }

    private readonly List<PromptVersion> _versions = new();
    public IReadOnlyCollection<PromptVersion> Versions => _versions.AsReadOnly();

    private readonly List<string> _tags = new();
    public IReadOnlyCollection<string> Tags => _tags.AsReadOnly();

    // EF Core needs this, but we make it private
    private Prompt() { }

    public Prompt(string title, string content, string modelType)
    {
        if (string.IsNullOrWhiteSpace(title))
            throw new ArgumentException("Title is required", nameof(title));
        if (string.IsNullOrWhiteSpace(content))
            throw new ArgumentException("Content is required", nameof(content));

        Id = Guid.NewGuid();
        Title = title.Trim();
        Content = content;
        ModelType = modelType ?? "gpt-4";
        CreatedAt = DateTime.UtcNow;

        // Initial version is always created
        _versions.Add(new PromptVersion(this, 1, content));
    }

    public void UpdateContent(string newContent, string? updatedBy = null)
    {
        if (string.IsNullOrWhiteSpace(newContent))
            throw new ArgumentException("Content is required", nameof(newContent));

        if (newContent == Content)
            return; // No change, no new version

        Content = newContent;
        UpdatedAt = DateTime.UtcNow;

        var nextVersion = _versions.Max(v => v.VersionNumber) + 1;
        _versions.Add(new PromptVersion(this, nextVersion, newContent, updatedBy));
    }

    public void AddTag(string tag)
    {
        var normalized = tag.Trim().ToLowerInvariant();
        if (!_tags.Contains(normalized))
            _tags.Add(normalized);
    }

    public void RemoveTag(string tag)
    {
        var normalized = tag.Trim().ToLowerInvariant();
        _tags.Remove(normalized);
    }
}

What's Happening Here

Private setters — State changes go through methods
Validation in constructor — Can't create an invalid entity
Behavior on the entity — UpdateContent creates a version, AddTag normalizes input
Internal constructor — PromptVersion can only be created by Prompt

⚠️ Real-world callout: You'll notice EF Core needs that private parameterless constructor. This is one of those "in concept vs. real world" moments. Pure domain-driven design says entities shouldn't know about persistence. EF Core says "give me a constructor or suffer." We compromise with private Prompt() { }.

The PromptVersion Entity

src/PromptVault.Domain/Entities/PromptVersion.cs

namespace PromptVault.Domain.Entities;

public class PromptVersion
{
    public Guid Id { get; private set; }
    public Guid PromptId { get; private set; }
    public int VersionNumber { get; private set; }
    public string Content { get; private set; } = null!;
    public DateTime CreatedAt { get; private set; }
    public string? CreatedBy { get; private set; }

    private PromptVersion() { } // EF Core

    internal PromptVersion(Prompt prompt, int versionNumber, string content, string? createdBy = null)
    {
        Id = Guid.NewGuid();
        PromptId = prompt.Id;
        VersionNumber = versionNumber;
        Content = content;
        CreatedAt = DateTime.UtcNow;
        CreatedBy = createdBy;
    }
}

Notice the internal constructor. Only code within the Domain project can create versions. External code must go through Prompt.UpdateContent().

The Anemic Entity Trap

Here's what most tutorials show you:

// ❌ DON'T DO THIS
public class Prompt
{
    public Guid Id { get; set; }
    public string Title { get; set; }
    public string Content { get; set; }
    // ...all public, no behavior
}

This is a "data bag." It has no rules. Any code anywhere can set any property to anything. Your "domain" is just a mirror of your database tables.

The problem: Business rules end up scattered across services, controllers, and validators. Six months later, nobody knows where the "real" logic is.

The fix: Entities protect their invariants. If updating content should create a version, that logic lives on Prompt, not in PromptService.UpdateContent().

Testing the Domain (Already!)

Because our Domain has no dependencies, testing is trivial:

[Fact]
public void UpdateContent_CreatesNewVersion()
{
    var prompt = new Prompt("Test", "Original content", "gpt-4");

    prompt.UpdateContent("Updated content");

    Assert.Equal(2, prompt.Versions.Count);
    Assert.Equal("Updated content", prompt.Content);
}

[Fact]
public void UpdateContent_WithSameContent_DoesNotCreateVersion()
{
    var prompt = new Prompt("Test", "Same content", "gpt-4");

    prompt.UpdateContent("Same content");

    Assert.Single(prompt.Versions); // Still just the initial version
}

No database. No HTTP. No mocking. Just logic.

What We Built

At the end of Part 1, you have:

PromptVault/
├── PromptVault.sln
└── src/
    ├── PromptVault.Domain/
    │   └── Entities/
    │       ├── Prompt.cs
    │       └── PromptVersion.cs
    ├── PromptVault.Application/   (empty for now)
    ├── PromptVault.Infrastructure/ (empty for now)
    └── PromptVault.API/            (empty for now)

The Domain project compiles with zero NuGet packages. That's the whole point.

Key Takeaways

Clean Architecture is about dependency direction, not folder structure
Domain entities should have behavior, not just properties
Accept the overhead consciously — if you don't need the benefits, use a simpler structure
EF Core will make you compromise — that's okay, be pragmatic
Testable domain is the real win — everything else is details

Coming Up

In Part 2, we'll flesh out the Domain layer:

Value objects that earn their keep (not just wrapping strings)
The Collection entity
When domain validation vs. application validation

We'll also address the elephant: what if your domain really is just CRUD?

👉 Part 2: The Domain Layer — Entities That Actually Have Behavior

Questions? Drop them in the comments. The full source code is on GitHub: PromptVault

Clean Architecture in .NET 10: Why Your Code Turns Into Spaghetti (And How to Prevent It)

Brian Spann — Tue, 27 Jan 2026 21:00:00 +0000

Who This Series Is For

You know C#. You've built some projects—maybe in school, maybe at your first job. Things worked. But something felt off:

Adding a feature meant changing 10 files
You were scared to refactor because everything might break
Your controllers were 500 lines long
Testing felt impossible, so you didn't
Senior devs talked about "architecture," and you nodded along, confused

This series is for you.

We're going to build a real application from scratch. By the end, you'll understand why experienced developers structure code the way they do—and more importantly, you'll know when these patterns matter and when they're overkill.

The Problem We're Solving

Let me show you code that works but will ruin your life in six months.

The "Just Make It Work" Approach

[ApiController]
[Route("api/prompts")]
public class PromptsController : ControllerBase
{
    private readonly AppDbContext _context;

    public PromptsController(AppDbContext context)
    {
        _context = context;
    }

    [HttpPost]
    public async Task<IActionResult> Create(CreatePromptRequest request)
    {
        // Validation mixed with business logic
        if (string.IsNullOrEmpty(request.Title))
            return BadRequest("Title is required");

        if (request.Title.Length > 200)
            return BadRequest("Title too long");

        // Check for duplicates
        if (await _context.Prompts.AnyAsync(p => p.Title == request.Title))
            return BadRequest("Title already exists");

        // Business logic in the controller
        var prompt = new Prompt
        {
            Id = Guid.NewGuid(),
            Title = request.Title.Trim(),
            Content = request.Content,
            CreatedAt = DateTime.UtcNow
        };

        // Create initial version
        var version = new PromptVersion
        {
            Id = Guid.NewGuid(),
            PromptId = prompt.Id,
            VersionNumber = 1,
            Content = request.Content,
            CreatedAt = DateTime.UtcNow
        };

        // Tags normalization
        if (request.Tags != null)
        {
            foreach (var tag in request.Tags)
            {
                prompt.Tags.Add(tag.Trim().ToLower());
            }
        }

        _context.Prompts.Add(prompt);
        _context.PromptVersions.Add(version);
        await _context.SaveChangesAsync();

        return CreatedAtAction(nameof(GetById), new { id = prompt.Id }, prompt);
    }

    // ... 20 more methods, all 50+ lines each
}

This works. It ships. Users are happy (for now).

Why It Becomes a Problem

Month 1: "Can you add email notifications when a prompt is created?"
You add the email code to the controller. It's getting long, but manageable.

Month 2: "We need the same logic in our mobile API."
You copy-paste the controller. Now you have duplicate business logic.

Month 3: "We need to write tests for the prompt creation."
You realize you can't test the logic without spinning up a database and HTTP server.

Month 4: "The tag normalization is wrong. Fix it everywhere."
You search the codebase. It's in 6 controllers, 3 services, and a background job. You miss one.

Month 6: "We're switching from SQL Server to PostgreSQL."
Everything breaks. Database code is everywhere.

The Root Cause

The problem isn't that you're a bad programmer. The problem is everything is mixed together:

HTTP handling (what format is the request?)
Validation (is the data valid?)
Business logic (what should happen?)
Data access (how do we save it?)

When everything is in one place, changing one thing risks breaking everything else.

What "Clean Architecture" Actually Means

Forget the complicated diagrams for now. Clean Architecture boils down to one idea:

Separate things that change for different reasons.

HTTP formats change (JSON today, maybe something else tomorrow)
Validation rules change (business decides title max is now 500)
Business logic changes (versioning rules become more complex)
Database changes (new ORM, new database, new table structure)

If these are all tangled together, every change is scary. If they're separate, you change one thing without touching the others.

An Analogy: The Restaurant Kitchen

Think of a restaurant:

Front of House (Waiters) — Takes orders from customers, brings food out
Kitchen — Cooks the food according to recipes
Pantry/Storage — Stores ingredients, retrieves them when needed

Now imagine a restaurant where:

The waiter cooks the food while taking your order
The cook stores ingredients in their pockets
There's no menu—customers describe what they want and the waiter figures it out

Chaos, right?

Clean Architecture is the same idea for code:

Restaurant	Code
Waiter	API Layer (Controllers)
Kitchen	Application Layer (Use Cases)
Recipes	Domain Layer (Business Rules)
Pantry	Infrastructure Layer (Database)

The waiter doesn't need to know how to cook. The chef doesn't need to know where ingredients are stored. Each part has one job.

What We're Building

Throughout this series, we'll build PromptVault—an API for storing and organizing AI prompts (like the ones you'd use with ChatGPT or Claude).

Why this example?

It's relevant (you probably use AI tools)
It has real business logic (versioning, tagging, collections)
It's simple enough to understand, complex enough to be realistic

Features we'll implement:

Create prompts with automatic versioning
Tag prompts for organization
Group prompts into collections
Search by content or tags
Track version history

The Four Layers (Simply Explained)

1. Domain — The Business Rules

This is the heart of your application. It knows nothing about HTTP, databases, or frameworks. It only knows the rules of your business.

"Updating a prompt should create a new version."
"Tags should be lowercase and unique."
"A prompt must have a title."

If you explained your app to a non-technical person, the Domain is what you'd talk about.

2. Application — The Use Cases

This coordinates what happens when a user wants to do something:

"Create a prompt" → Check if title exists, create the prompt, save it.
"Get prompt history" → Find the prompt, load its versions, return them.

The Application layer knows WHAT to do, but not HOW data is stored.

3. Infrastructure — The Real World

This is where we talk to external things:

Databases (Entity Framework)
File systems
External APIs
Email services

The Infrastructure layer knows HOW to store and retrieve data.

4. API — The Door

This is where requests come in:

HTTP endpoints (controllers or minimal APIs)
Request/response formatting
Authentication

The API layer translates between "HTTP" and "what the application needs to do."

The Key Rule: Dependencies Point Inward

Here's the rule that makes everything work:

API → Application → Domain
       ↓
   Infrastructure

Domain depends on nothing
Application depends only on Domain
Infrastructure depends on Domain and Application
API depends on Application

What this means in practice:

Your Prompt entity (Domain) doesn't know Entity Framework exists.
Your CreatePromptHandler (Application) doesn't know you're using SQL Server.
Your controller (API) doesn't know how data is stored.

If you swap PostgreSQL for MongoDB, only Infrastructure changes. The rest of your code doesn't care.

"This Seems Like a Lot of Work"

It is. That's the honest truth.

For a simple CRUD app that one person maintains, this is overkill. You'd spend more time on architecture than features.

Use Clean Architecture when:

Multiple developers will work on the code
The project will live for years
You have real business logic (not just save/load data)
You want to write tests
You might change databases or frameworks

Skip it when:

It's a prototype or hackathon project
You're the only developer forever
The whole app is just CRUD
You need to ship in a week

We'll be honest throughout this series about when patterns are worth the cost.

Prerequisites

To follow along, you should know:

C# basics — classes, methods, async/await
Some ASP.NET Core — you've built a controller before
Basic Entity Framework — you've saved something to a database

You don't need to know:

MediatR (we'll explain it)
Design patterns (we'll introduce them as needed)
Previous architecture experience (that's what we're teaching)

What's Coming

Part	Topic
1	The Setup — Creating the project structure
2	Domain Layer — Entities with real behavior
3	Application Layer — CQRS and MediatR
4	Infrastructure Layer — EF Core without leakage
5	API Layer — Controllers that do almost nothing
6	Production Polish — Validation, logging, caching
7	Testing — What matters and what to skip

Each part:

Shows you the "textbook" approach
Explains "in the real world, here's what happens."
Gives you working code you can run

Let's Start

By the end of this series, you'll:

Understand why senior developers make certain choices
Know when to use these patterns (and when not to)
Have a real project to reference for future work
Be able to explain Clean Architecture in a job interview

Ready?

👉 Part 1: The Setup (And When Clean Architecture Is Overkill) — coming next!

Follow me for the next part. Drop a comment if you have questions—I read all of them.