Clean Architecture: .NET API + Next.js Web (Production Template)

.NET monoreposunda Next.js frontend ile bir Clean Architecture kurulumu, doğru yapıldığında hem takım üretkenliğini artırır hem de sistemin test edilebilirliğini garantiler. Bu yazıda gerçek bir projeye uyguladığım katman yapısını ve bağımlılık yönünü ele alacağım.

Neden Clean Architecture?

Çoğu ekip mimari pattern'leri "best practice" olduğu için uygular, ama neden işe yaradığını anlamaz. CA'nın özü şu: bağımlılıklar daima içeriye doğru akar. Domain katmanı hiçbir şeye bağımlı değil; altyapı her şeye bağımlı.

Katman Yapısı

Monoreponuzdaki proje yapısı şu şekilde olabilir:

src/
  Domain/           # Entity, ValueObject, IDomainEvent
  Application/      # UseCase, IRepository, IService, DTO
  Infrastructure/   # EF Core, dış servisler, repo impls
  Api/              # Controllers / Minimal API, DI setup
  Web/              # Next.js frontend (ayrı repo ya da packages/)

Bağımlılık Yönü

Temel kural: Infrastructure → Application → Domain. Application katmanı asla Infrastructure'u import etmez. Bunu garantilemek içinArchUnitNET veya CI'da çalışan bir bağımlılık testi ekleyebilirsiniz.

[Fact]
public void Application_ShouldNot_DependOn_Infrastructure()
{
    var result = Types.InAssembly(typeof(ApplicationAssembly).Assembly)
        .ShouldNot()
        .HaveDependencyOn("Infrastructure")
        .GetResult();

    result.IsSuccessful.Should().BeTrue();
}

Deploy Stratejisi

Monorepo'da Next.js ve .NET API'yi ayrı container'lara build edip aynı Compose veya Kubernetes namespace'inde çalıştırın. Geliştirme ortamında ise:

services:
  api:
    build: ./src/Api
    ports: ["5000:8080"]
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
    volumes:
      - ./src:/app/src  # hot reload

  web:
    build: ./src/Web
    ports: ["3000:3000"]
    environment:
      - NEXT_PUBLIC_API_URL=http://api:8080
    depends_on: [api]

Sonuç

Clean Architecture her proje için doğru seçim değil, ama kurumsal ölçekte büyüyen, birden fazla takımın katkı yaptığı sistemlerde katman izolasyonu uzun vadede yönetim kolaylığı sağlar. Önemli olan mimariyi körü körüne uygulamak değil, neden uyguladığınızı bilmek.