TechSpherex.CleanArchitecture.Template 2.0.4

🏗️ TechSpherex Clean Architecture Template

A production-ready Clean Architecture starter template for .NET 10. Ship features from day one — not boilerplate.

.NET 10 | Docker Ready | Native AOT Supported | MIT License

---

✨ What's Included

• 🏛️ Clean Architecture: 4-layer separation with enforced dependency rules.
• ⚡ Native AOT: ~35 MB images, ~50ms startup.
• 🏢 Multi-Tenancy: Shared-table with auto query filters.
• 🤖 Skill Agents (AI): Pluggable LLM orchestrator pattern.
• 📊 Full Observability: ELK Stack + Grafana Stack (Loki, Tempo, Prometheus).
• 🚀 HybridCache: L1 in-memory + L2 Redis with stampede protection.

---

🚀 Quick Start

To use this template, install it via NuGet:

# 1. Install template
dotnet new install TechSpherex.CleanArchitecture.Template

# 2. Create new project
dotnet new ts-clean-arch -n MyProjectName

---

🛠️ Tech Stack

Layer	Technology
Architecture	Clean Architecture (Domain → Application → Infrastructure → Api)
Runtime	.NET 10 / C# 14
API	Minimal APIs with TypedResults
CQRS	Manual handlers — zero dependencies, zero licensing risk
Validation	FluentValidation 12 + Result pattern
Error Handling	ProblemDetails (RFC 9457) + global exception handler
Database	EF Core 10 + PostgreSQL
Caching	Microsoft HybridCache (L1 in-memory + L2 Redis)
Auth	ASP.NET Identity + JWT Bearer with refresh tokens
Multi-Tenancy	Shared-table strategy with EF Core global query filters
AI / Agents	Skill Agents pattern (pluggable — OpenAI, Ollama, Semantic Kernel)
API Docs	Scalar (modern OpenAPI UI)
Logging	Serilog 10 + Elasticsearch sink
Observability	.NET Aspire 13 + OpenTelemetry + ELK + Grafana
Containerization	Docker multi-stage build (JIT + Native AOT)
Testing	xUnit v3 + FluentAssertions + NSubstitute + NetArchTest
Solution	.slnx format + Central Package Management

---

🏛️ Architecture

┌──────────────────────────────────────────────────┐
│                    Api Layer                      │
│      Endpoints · Middleware · OpenAPI · Scalar    │
└──────────────────┬───────────────────────────────┘
                   │ depends on
┌──────────────────▼───────────────────────────────┐
│              Infrastructure Layer                 │
│    EF Core · Identity · JWT · Cache · Tenancy    │
└──────────────────┬───────────────────────────────┘
                   │ depends on
┌──────────────────▼───────────────────────────────┐
│              Application Layer                    │
│  CQRS Handlers · Validators · Agent Abstractions │
└──────────────────┬───────────────────────────────┘
                   │ depends on
┌──────────────────▼───────────────────────────────┐
│                Domain Layer                       │
│   Entities · Value Objects · Result · Interfaces  │
└──────────────────────────────────────────────────┘

Dependency rule: Each layer only depends on the layer below it. Domain has zero external dependencies. Architecture tests enforce this at build time (9 tests).

---

📁 Project Structure

clean-architecture-template/
├── src/
│   ├── Domain/                    # Entities, value objects, ITenantEntity
│   ├── Application/               # CQRS handlers, validators, Skill Agents
│   ├── Infrastructure/            # EF Core, Identity, JWT, caching, tenancy
│   ├── Api/                       # Minimal API endpoints, Scalar, middleware
│   ├── AppHost/                   # .NET Aspire orchestration
│   └── ServiceDefaults/           # OpenTelemetry, health checks, resilience
├── tests/
│   ├── Architecture.Tests/        # Dependency rule enforcement (9 tests)
│   └── Application.UnitTests/     # Handler unit tests (8 tests)
├── docker/
│   ├── elk/                       # Logstash pipeline config
│   ├── grafana/                   # Loki, Tempo, Prometheus, dashboards
│   └── otel/                      # OpenTelemetry Collector config
├── docs/                          # 9 comprehensive documentation guides
├── Dockerfile                     # Multi-stage build (JIT + AOT)
├── docker-compose.yml             # Full stack with 4 profiles
├── Directory.Build.props          # .NET 10, C# latest, nullable
├── Directory.Packages.props       # Central Package Management
├── CHANGELOG.md                   # Version history
└── README.md

---

🚀 Getting Started

Prerequisites

Tool	Version	Required
.NET 10 SDK	10.0+	✅
Docker Desktop	4.x+	✅
IDE (VS 2026 / Rider / VS Code)	Latest	💡

Option A — Run with Aspire (recommended for development)

cd src/TechSpherex.CleanArchitecture.AppHost
dotnet run

This automatically starts:

• PostgreSQL database with pgAdmin
• Redis cache with RedisInsight
• API with auto-migration and seed data
• Aspire Dashboard for OpenTelemetry (traces, metrics, logs)

Option B — Run with Docker Compose

⚠️ Important: All docker compose and docker build commands must be run from the project root directory (where Dockerfile and docker-compose.yml are located), not from src/.

# Navigate to project root
cd clean-architecture-template

# Core: API + PostgreSQL + Redis
docker compose up -d --build

# Or explicitly specify the compose file
docker compose -f docker-compose.yml up -d --build

# + ELK Stack (Elasticsearch, Logstash, Kibana)
docker compose --profile elk up -d --build

# + Grafana Stack (Loki, Grafana, Tempo, Prometheus)
docker compose --profile grafana up -d --build

# + Dev Tools (pgAdmin, RedisInsight)
docker compose --profile tools up -d

# Combine multiple profiles
docker compose --profile elk --profile tools up -d --build

Option C — Standalone (without Aspire)

docker compose up -d postgres redis    # Start database & cache
cd src/Api && dotnet run               # Run the API locally

🔗 Explore the API

Service	URL	Credentials
Scalar API Docs	https://localhost:7200/scalar/v1	—
API (Docker)	http://localhost:8080	—
Aspire Dashboard	https://localhost:18888	—

Default admin credentials (seeded automatically in Development):

• Email: admin@TechSpherex.dev
• Password: Admin@123

Run Tests

cd src
dotnet build TechSpherex.CleanArchitecture.slnx
dotnet test TechSpherex.CleanArchitecture.slnx

---

🐳 Docker & Native AOT

Build Docker Image

Run from the project root directory (same level as Dockerfile):

# Standard build (JIT)
docker build -t techspherex-api .

# Native AOT build (smaller image, faster cold start)
docker build --build-arg PUBLISH_AOT=true -t techspherex-api:aot .

Build	Image Size	Startup	Use Case
JIT (Alpine)	~120 MB	~500ms	General purpose, full compatibility
AOT (Alpine)	~35 MB	~50ms	Serverless, edge, cold-start-sensitive

Docker Compose Profiles

Profile	Command	Services Added
(core)	docker compose up -d	API + PostgreSQL + Redis
elk	docker compose --profile elk up -d	+ Elasticsearch + Logstash + Kibana
grafana	docker compose --profile grafana up -d	+ Loki + Grafana + Tempo + Prometheus
tools	docker compose --profile tools up -d	+ pgAdmin + RedisInsight

---

🏢 Multi-Tenancy

Shared-table multi-tenancy with automatic tenant isolation powered by EF Core global query filters.

# Send request with tenant header
curl -H "X-Tenant-Id: acme-corp" \
     -H "Authorization: Bearer <token>" \
     http://localhost:8080/api/todos

Tenant resolution order: X-Tenant-Id header → JWT tenant_id claim → Default tenant

Make Any Entity Tenant-Aware

Simply implement ITenantEntity — global query filters and auto-assignment are applied automatically:

public sealed class Product : AuditableEntity, ITenantEntity
{
    public string Name { get; set; } = default!;
    public decimal Price { get; set; }
    public string TenantId { get; set; } = default!; // Auto-set on SaveChanges
}

📖 Multi-Tenancy Guide

---

🤖 Skill Agents (AI)

Built-in provider-agnostic AI agent pattern that integrates with your domain logic:

curl -X POST http://localhost:8080/api/agents/execute \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Show me all my todos"}'

Endpoint	Method	Auth	Description
/api/agents/execute	POST	🔒	Execute with auto skill routing
/api/agents/execute/{skillId}	POST	🔒	Execute a specific skill by ID
/api/agents/skills	GET	🌐	List all available skills

Key features:

• 🔌 Provider-agnostic — plug in OpenAI, Azure OpenAI, Ollama, or Semantic Kernel
• 🔍 Auto-discovery — skill agents are registered automatically via assembly scanning
• 💬 Multi-turn — conversation history support for contextual interactions
• 📦 Sample included — TodoAgentSkill demonstrates the full pattern

---

📊 Observability

Three levels of observability, from development to production:

Level 1 — Aspire Dashboard (Development)

Built-in with .NET Aspire. Shows structured logs, distributed traces, and metrics out of the box.

Level 2 — ELK Stack

docker compose --profile elk up -d --build

Service	URL	Purpose
Kibana	http://localhost:5601	Log visualization & search
Elasticsearch	http://localhost:9200	Log storage & indexing
Logstash	tcp://localhost:31311	Log pipeline processing

• Index pattern: techspherex-logs-*
• Structured JSON logs with trace correlation and tenant context

Level 3 — Grafana Stack (Recommended for Production)

docker compose --profile grafana up -d --build

Service	URL	Credentials
Grafana	http://localhost:3000	admin / Admin@123
Prometheus	http://localhost:9090	—
Loki	http://localhost:3100	—
Tempo	http://localhost:3200	—

Pre-built dashboard with 12 panels:

• Request rate · P99 latency · Error rate (5xx) · Active connections
• Memory usage · GC collections · Thread pool · Log volume
• HTTP status distribution · Recent logs

Cross-linked datasources: Loki (logs) ↔ Tempo (traces) ↔ Prometheus (metrics)

---

🗂️ Service Ports Reference

Service	Port	Profile
API	8080	core
PostgreSQL	5432	core
Redis	6379	core
Elasticsearch	9200	elk
Logstash (Beats / TCP)	5044 / 31311	elk
Kibana	5601	elk
Grafana	3000	grafana
Loki	3100	grafana
Tempo	3200	grafana
Prometheus	9090	grafana
OTel Collector (gRPC / HTTP)	4320 / 4321	elk / grafana
pgAdmin	5050	tools
RedisInsight	5540	tools

---

📝 Sample: Todos Feature

The template includes a complete Todos CRUD feature as a reference implementation:

Endpoint	Method	Auth	Description
/api/todos	GET	🔒	Get all todos (paginated)
/api/todos/{id}	GET	🔒	Get a todo by ID
/api/todos	POST	🔒	Create a new todo
/api/todos/{id}	PUT	🔒	Update a todo
/api/todos/{id}/complete	PATCH	🔒	Mark as completed
/api/todos/{id}	DELETE	🔒	Delete a todo

Adding a New Feature

Follow the Todos pattern — four simple steps:

1. Domain — Add entity in Domain/Entities/ (implement ITenantEntity if multi-tenant)
2. Application — Create feature folder in Application/Features/YourFeature/ with Command/Query + Handler + Validator
3. Infrastructure — Add EF Core configuration in Infrastructure/Persistence/Configurations/
4. Api — Add endpoint group in Api/Endpoints/ and register in Program.cs

---

🧠 Key Design Decisions

Decision	Why
Manual CQRS over MediatR	Zero licensing risk — MediatR is commercial since v13. Learn the pattern, not a library.
Scalar over Swagger UI	Modern, faster, better DX. Swagger UI is legacy.
HybridCache over IMemoryCache	Built-in stampede protection, L1+L2 cache layers, automatic serialization.
Result pattern over exceptions	Explicit error handling, no hidden control flow, better API contracts.
Shared-table tenancy	Simple, no migration complexity, cost-efficient — good for most SaaS apps.
Interface-only agents	No LLM provider lock-in. Swap OpenAI, Ollama, or Semantic Kernel freely.
Assembly scanning DI over Scrutor	Zero dependencies — 40 lines of reflection replaces an entire NuGet package.
.slnx over .sln	XML-based, merge-friendly, smaller — the future of .NET solution files.

---

🎓 Education Roadmap

New to Clean Architecture? Follow this learning path from the innermost layer outward. Each step builds on the previous one — just like the dependency rule itself.

  Step 1          Step 2            Step 3              Step 4           Step 5
 ┌────────┐    ┌─────────────┐   ┌────────────────┐   ┌──────────┐   ┌──────────────┐
 │ Domain │ ──▶│ Application │──▶│ Infrastructure │──▶│   Api    │──▶│ DevOps / Ops │
 └────────┘    └─────────────┘   └────────────────┘   └──────────┘   └──────────────┘
   Core           Use Cases        Implementations      Endpoints      Docker, CI/CD

Step 1 — 🏛️ Domain Layer (start here!)

"Understand the heart of the application — the business rules."

What to Read	Why
Domain/Entities/	Learn how entities are modeled — TodoItem, AuditableEntity
Domain/Interfaces/	See the contracts (e.g., IRepository<T>, ITenantProvider) — no implementation details here
Domain/Common/Result.cs	Understand the Result pattern — how errors are handled without exceptions
Domain/Common/ITenantEntity.cs	See how multi-tenancy is declared at the domain level

🎯 Key takeaway: Domain has zero NuGet dependencies. It defines what the system does, not how.

Step 2 — 📋 Application Layer

"Learn how use cases orchestrate domain logic."

What to Read	Why
Application/Features/Todos/	Full CQRS example — Commands, Queries, Handlers, Validators
Application/Features/Todos/Commands/CreateTodo/	Follow a Command from DTO → Handler → Result
Application/Features/Todos/Queries/GetTodos/	Follow a Query with pagination
Application/Common/	Shared behaviors, interfaces, pagination models
Application/Agents/	See how Skill Agent abstractions are defined (provider-agnostic AI)

🎯 Key takeaway: Application depends only on Domain. It defines what happens when a user action occurs.

Step 3 — 🔧 Infrastructure Layer

"See how contracts become concrete implementations."

What to Read	Why
Infrastructure/Persistence/AppDbContext.cs	EF Core setup, multi-tenant query filters, audit fields
Infrastructure/Persistence/Configurations/	Entity-to-table mapping with Fluent API
Infrastructure/Persistence/Repositories/	Generic Repository<T> implementing IRepository<T> from Domain
Infrastructure/Identity/	ASP.NET Identity + JWT token generation
Infrastructure/Caching/	HybridCache implementation (L1 + L2)
Infrastructure/DependencyInjection.cs	How everything is wired together — study this carefully

🎯 Key takeaway: This is where the Dependency Inversion Principle shines — Infrastructure implements Domain interfaces.

Step 4 — 🚀 Api Layer

"Connect everything to the outside world."

What to Read	Why
Api/Program.cs	The composition root — where all layers are registered
Api/Endpoints/	Minimal API endpoint groups — see how requests flow in
Api/Middleware/	Global exception handling, tenant resolution
Api/Extensions/	Service registration helpers, OpenAPI config

🎯 Key takeaway: Api is the entry point but contains zero business logic. It only maps HTTP → Application.

Step 5 — 🐳 DevOps & Orchestration

"Understand how the app runs in real environments."

What to Read	Why
AppHost/Program.cs	.NET Aspire orchestration — how services are composed
ServiceDefaults/	OpenTelemetry, health checks, resilience defaults
Dockerfile	Multi-stage build — JIT vs Native AOT
docker-compose.yml	Full stack with profiles (ELK, Grafana, tools)
docker/	Logstash, Grafana, OTel Collector configs

🎯 Key takeaway: DevOps config is separate from application code — clean boundary.

🧪 Bonus — Tests

"Read tests to verify your understanding."

What to Read	Why
tests/Architecture.Tests/	Must-read! 9 tests that enforce dependency rules between layers
tests/Application.UnitTests/	See how handlers are tested in isolation with mocks

📖 Suggested Reading Order (TL;DR)

1.  Domain/Common/Result.cs              → Understand error handling
2.  Domain/Entities/TodoItem.cs          → See a real entity
3.  Domain/Interfaces/                   → Learn the contracts
4.  Application/Features/Todos/          → Follow a full CQRS feature
5.  Infrastructure/DependencyInjection.cs→ See how DI wires everything
6.  Infrastructure/Persistence/          → See DB implementation
7.  Api/Program.cs                       → The composition root
8.  Api/Endpoints/TodoEndpoints.cs       → HTTP → Application mapping
9.  tests/Architecture.Tests/            → Verify the rules
10. Dockerfile + docker-compose.yml      → Production deployment

---

📄 License

This project is licensed under the MIT License.

Use it, modify it, ship it. Attribution appreciated but not required.

---