Clean Architecture Full-Stack Starter: .NET, Angular, and PostgreSQL

Clean Architecture with RBAC implementation for API (.Net) and UI (Angular)

Contact Management Application with Role-Based Access Control

What is this?

A production-ready full-stack starter kit built with modern technologies and best practices:

• Frontend: Angular 21 with signals, Material Design, TailwindCSS v4, and Fluent Design
• Backend: .NET 10 API with Clean Architecture and Scalar API documentation
• Database: PostgreSQL 17 with pgAdmin and Dapper ORM
• Orchestration: .NET Aspire 9.5 for local development with service discovery
• DevOps: Docker, GitHub Actions, NGINX

Perfect for developers who want to focus on business logic instead of configuring infrastructure.

Why Clean Architecture?

Clean Architecture provides significant benefits for your application:

• ✅ Maintainability: Separate concerns to make your code easier to understand and modify
• ✅ Testability: Independent components that can be tested in isolation
• ✅ Flexibility: Swap frameworks or technologies without rewriting your core business logic
• ✅ Scalability: Grow your application with a clear structure that new team members can quickly understand

Clean Architecture Series - Read more about it!

Quick Start

Option 1: Using .NET Aspire (Recommended for Development)

.NET Aspire provides a streamlined local development experience with automatic service discovery, health monitoring, and an integrated dashboard.

Prerequisites

Important: Make sure you have the correct versions installed before proceeding.

• .NET SDK 10.0 or later
• Node.js 22 LTS (not Node 23 - use LTS version only)
• Docker Desktop (for PostgreSQL container)

Steps

# Clone the repository
git clone https://github.com/nitin27may/clean-architecture-docker-dotnet-angular.git clean-app
cd clean-app

# IMPORTANT: Install Angular dependencies first
cd frontend
npm install
cd ..

# Run with Aspire
dotnet run --project aspire/AppHost

🔗 Then access:

• Aspire Dashboard: https://localhost:17178 (see all services, logs, traces)
• Frontend: http://localhost:4200
• API: Check Aspire dashboard for the assigned port
• Scalar API Docs: {API_URL}/scalar/v1
• pgAdmin: Check Aspire dashboard for the assigned port

Option 2: Using Docker Compose (Production-like)

# Clone the repository
git clone https://github.com/nitin27may/clean-architecture-docker-dotnet-angular.git clean-app
cd clean-app

# Create .env file (required)
cp .env.example .env

# Start all services with Docker Compose
docker-compose up

Then access:

• Frontend: http://localhost
• API: http://localhost/api
• Scalar API Docs: http://localhost/scalar/v1

👤 Default Users

Username	Password	Role
nitin27may@gmail.com	P@ssword#321	Admin
editor@gmail.com	P@ssword#321	Editor
reader@gmail.com	P@ssword#321	Reader

Key Features

Modern Frontend Angular 21 with standalone components Signal-based state management Material Design + TailwindCSS v4 Fluent Design System tokens Dark/light theme support Responsive mobile-first design Role-based routing and menu

Secure Backend Clean Architecture implementation Generic Repository pattern JWT authentication Role-based permissions User activity logging Global exception handling Scalar API documentation PostgreSQL 17 with Dapper

DevOps Ready .NET Aspire orchestration Docker containerization GitHub Actions workflows NGINX reverse proxy pgAdmin database management Multi-environment configs Database seeding

Project Structure

clean-architecture-docker-dotnet-angular/
├── aspire/                      # .NET Aspire orchestration
│   ├── AppHost/                 # Aspire host application
│   │   └── AppHost.cs           # Service configuration
│   └── ServiceDefaults/         # Shared Aspire defaults
├── backend/                     # .NET 10 API (Clean Architecture)
│   ├── Contact.Api/             # API Layer (Controllers, Middleware)
│   ├── Contact.Application/     # Application Layer (Services, DTOs)
│   ├── Contact.Domain/          # Domain Layer (Entities, Interfaces)
│   ├── Contact.Infrastructure/  # Infrastructure Layer (Repositories)
│   └── Contact.Common/          # Shared utilities
├── frontend/                    # Angular 21 SPA
│   ├── src/app/@core/           # Core module (guards, interceptors, layout)
│   ├── src/app/feature/         # Feature modules (contact, user, admin)
│   └── src/app/styles/          # Global styles, Tailwind config
├── scripts/                     # Database initialization
│   ├── 01-init-db.sh            # Create database
│   └── 02-seed-data.sql         # Seed initial data
├── api-collection/              # Bruno API collection for testing
├── docs/                        # Documentation
├── loadbalancer/                # NGINX configuration
├── Contact.Api.sln              # .NET Solution file
├── docker-compose.yml           # Docker Compose configuration
└── Dockerfile.api               # API Dockerfile

Architecture

Container Architecture Overview

Documentation

Comprehensive documentation is available:

• Aspire Guide - Running with .NET Aspire
• Development Guide - Get started with development
• Frontend Documentation - Angular architecture details
• Backend Documentation - .NET API implementation
• Docker Guide - Container configuration
• Feature List - Detailed feature breakdown
• Clean Architecture Series - In-depth articles
• Roadmap - Upcoming features

Technology Stack

Layer	Technology	Version
Frontend	Angular	21.0
UI Components	Angular Material	21.0
CSS Framework	TailwindCSS	4.1
Backend	.NET	10.0
API Docs	Scalar	2.1
Database	PostgreSQL	17
ORM	Dapper	2.1
Orchestration	.NET Aspire	9.5
Containerization	Docker	Latest

🤝 Contributing

We welcome contributions! See our contributing guide for details on how to get involved.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contact

For questions or support, please contact Nitin Singh at nitin27may@gmail.com.

Star the Repository

If you find this project useful, please consider giving it a star on GitHub to show your support!