How I Built a .NET 8 Clean Architecture SaaS Boilerplate (And What I Learned)

Hitesh Prajapati — Tue, 17 Mar 2026 06:56:49 +0000

Every .NET developer eventually faces the same painful moment: you're starting a new SaaS project and you spend the first 3–4 weeks doing absolutely nothing unique.

Authentication. Multi-tenancy. CQRS setup. Repository patterns. JWT. Stripe. Role-based permissions. Logging. Error handling middleware.

It's the same scaffolding, over and over again.

After going through this cycle one too many times, I decided to build a reusable .NET 8 Clean Architecture SaaS Boilerplate — and in this article, I want to walk you through exactly how it's structured, the key decisions I made, and what you can learn from it even if you don't use the boilerplate itself.

Why Clean Architecture for SaaS?

Clean Architecture (popularised by Robert C. Martin) enforces a strict separation of concerns by organising code into concentric layers — each layer only depending on the layer inside it.

For a SaaS product, this matters enormously:

Business logic stays pure — your core domain doesn't care if you're using SQL Server or PostgreSQL, REST or gRPC
Testability is built-in — you can unit test use cases without touching infrastructure
Maintainability at scale — adding a new feature doesn't mean untangling spaghetti

Here's the layer structure I used:

📁 src/
  📁 Domain/          ← Entities, value objects, domain events
  📁 Application/     ← Use cases, CQRS commands/queries, interfaces
  📁 Infrastructure/  ← EF Core, JWT, email, external services
  📁 WebAPI/          ← Controllers, middleware, DI setup

The golden rule: dependencies always point inward. Infrastructure depends on Application. Application depends on Domain. Domain depends on nothing.

CQRS with MediatR

One of the most impactful patterns in the boilerplate is CQRS (Command Query Responsibility Segregation) implemented via MediatR.

Instead of fat service classes, every operation is a self-contained handler:

// Command
public record CreateTenantCommand(string Name, string AdminEmail) : IRequest<Guid>;

// Handler
public class CreateTenantCommandHandler : IRequestHandler<CreateTenantCommand, Guid>
{
    private readonly IApplicationDbContext _context;

    public CreateTenantCommandHandler(IApplicationDbContext context)
        => _context = context;

    public async Task<Guid> Handle(CreateTenantCommand request, CancellationToken ct)
    {
        var tenant = Tenant.Create(request.Name, request.AdminEmail);
        _context.Tenants.Add(tenant);
        await _context.SaveChangesAsync(ct);
        return tenant.Id;
    }
}

This gives you:

✅ Single Responsibility — each handler does exactly one thing

✅ Easy to test — just inject a mock IApplicationDbContext

✅ Pipeline behaviours for cross-cutting concerns (logging, validation, caching)

Multi-Tenancy Architecture

Multi-tenancy is the heart of any SaaS product and usually the most complex part to get right. The boilerplate supports a shared database with tenant isolation using a TenantId column on every tenant-scoped entity.

The tenant is resolved from the JWT token on every request:

public class TenantService : ITenantService
{
    private readonly IHttpContextAccessor _httpContextAccessor;

    public TenantService(IHttpContextAccessor accessor)
        => _httpContextAccessor = accessor;

    public Guid GetCurrentTenantId()
    {
        var claim = _httpContextAccessor.HttpContext?
            .User.FindFirst("tenant_id");

        return Guid.Parse(claim?.Value 
            ?? throw new UnauthorizedAccessException());
    }
}

And the ApplicationDbContext automatically filters by tenant using EF Core Global Query Filters:

protected override void OnModelCreating(ModelBuilder builder)
{
    foreach (var entityType in builder.Model.GetEntityTypes())
    {
        if (typeof(ITenantEntity).IsAssignableFrom(entityType.ClrType))
        {
            builder.Entity(entityType.ClrType)
                .HasQueryFilter(BuildTenantFilter(entityType.ClrType));
        }
    }
}

Every DbSet query is now automatically scoped to the current tenant. No risk of data leaking between customers.

Authentication & JWT

The boilerplate uses ASP.NET Core Identity + JWT Bearer tokens for stateless authentication — perfect for API-first SaaS apps.

A few things I did differently from the typical tutorial approach:

1. Refresh tokens stored in the database

Access tokens are short-lived (15 minutes). Refresh tokens are stored in the UserTokens table and rotated on every use, protecting against token theft.

2. Claims-based permissions (not just roles)

Instead of checking [Authorize(Roles = "Admin")], permissions are granular claims:

[Authorize(Policy = "CanManageUsers")]
[HttpDelete("users/{id}")]
public async Task<IActionResult> DeleteUser(Guid id) { ... }

This lets you give a user specific permissions without promoting them to a full admin role — critical in multi-tenant SaaS where tenant admins manage their own users.

3. Tenant claims in the token

{
  "sub": "user-guid",
  "tenant_id": "tenant-guid",
  "permissions": ["manage_users", "view_billing"],
  "exp": 1735689600
}

FluentValidation Pipeline Behaviour

One of my favourite parts of the boilerplate is the automatic validation pipeline. Any command or query with a corresponding AbstractValidator<T> is validated before it reaches the handler:

public class CreateTenantCommandValidator : AbstractValidator<CreateTenantCommand>
{
    public CreateTenantCommandValidator()
    {
        RuleFor(x => x.Name)
            .NotEmpty()
            .MaximumLength(100);

        RuleFor(x => x.AdminEmail)
            .NotEmpty()
            .EmailAddress();
    }
}

The MediatR pipeline behaviour catches validation failures and returns a structured 400 Bad Request automatically — no manual validation code in controllers.

Global Exception Handling

Nothing breaks SaaS apps faster than unhandled exceptions leaking stack traces to users (or worse, to the browser console).

The boilerplate includes a middleware that maps domain exceptions to HTTP responses:

app.UseExceptionHandler(exceptionHandlerApp =>
{
    exceptionHandlerApp.Run(async context =>
    {
        var exception = context.Features.Get<IExceptionHandlerFeature>()?.Error;

        var (statusCode, message) = exception switch
        {
            NotFoundException => (404, exception.Message),
            UnauthorizedAccessException => (401, "Unauthorized"),
            ValidationException ve => (400, ve.Message),
            _ => (500, "An unexpected error occurred")
        };

        context.Response.StatusCode = statusCode;
        await context.Response.WriteAsJsonAsync(new { error = message });
    });
});

What's Included in the Boilerplate

To summarise everything that's pre-built and ready to go:

Feature	Detail
Clean Architecture layers	Domain, Application, Infrastructure, WebAPI
CQRS + MediatR	Commands, queries, pipeline behaviours
Multi-tenancy	Shared DB with EF Core global query filters
Authentication	ASP.NET Identity + JWT + refresh tokens
Authorization	Claims-based permission policies
Validation	FluentValidation via MediatR pipeline
Error handling	Global exception middleware
Logging	Structured logging with Serilog
API documentation	Swagger/OpenAPI with JWT support
Unit test project	xUnit + Moq setup included

How Much Time Does This Save?

Based on my own experience (and feedback from developers who've used it), setting all of this up from scratch typically takes 3–6 weeks for a solo developer:

Clean Architecture setup & conventions: ~3 days
Multi-tenancy implementation: ~5 days
Auth with JWT + refresh tokens + permissions: ~5 days
CQRS + validation pipeline: ~2 days
Error handling, logging, Swagger: ~2 days
Testing setup: ~2 days

The boilerplate brings that down to a single afternoon of configuration — updating connection strings, setting your JWT secret, and deploying.

Who Is This For?

This boilerplate is best suited for:

.NET / C# developers building their first or second SaaS product
Indie hackers who want to ship fast without compromising architecture
Small teams who want an opinionated, well-structured starting point
Developers learning Clean Architecture through a real, complete codebase

It is not a tutorial codebase — it's a production-ready starting point. Every pattern used is one you'd find in enterprise .NET projects.

Get the Boilerplate

The full .NET 8 Clean Architecture SaaS Boilerplate is available here:

👉 Download on Gumroad

It includes the complete source code, a detailed README with setup instructions, and all the patterns described in this article.

Questions?

Drop a comment below — happy to discuss any of the architectural decisions, why I chose one approach over another, or how to adapt the boilerplate for specific use cases.

If you found this useful, a ❤️ or 🦄 means a lot. And if you know another .NET developer who's about to spend 4 weeks reinventing the same wheel — share this with them!

Built with .NET 8 · ASP.NET Core · Entity Framework Core · MediatR · FluentValidation · Serilog

DEV Community: Hitesh Prajapati