Clean Architecture Full-Stack Starter
A production-ready full-stack application with Angular 21, .NET 10, and PostgreSQL 17 using Clean Architecture principles, orchestrated with .NET Aspire
Get Started View on GitHub Feature List
A modern, full-stack contact management system built with Angular 21, .NET 10, and PostgreSQL 17 following Clean Architecture principles. This project demonstrates how to structure enterprise applications for maintainability, testability, and scalability while providing a complete development workflow with .NET Aspire orchestration and Docker containerization.
🌟 What You’ll Learn
- Clean Architecture principles and implementation
- Angular 21 with signals, standalone components, and Fluent Design
- .NET 10 with dependency injection and repository pattern
- PostgreSQL 17 with Dapper for efficient data access
- .NET Aspire 9.5 for local development orchestration
- Scalar for modern API documentation
- JWT Authentication with role-based permissions
- Docker containerization for development and production
- NGINX as a reverse proxy and API gateway
- CI/CD with GitHub Actions
🚀 Quick Start
Option 1: Using .NET Aspire (Recommended for Development)
Prerequisites:
- .NET SDK 10.0 or later
- Node.js 22 LTS (not Node 23)
- Docker Desktop
git clone https://github.com/nitin27may/clean-architecture-docker-dotnet-angular.git clean-app
cd clean-app
# Install frontend dependencies
cd frontend && npm install && cd ..
# Run with Aspire
dotnet run --project aspire/AppHost
Access the Aspire Dashboard at https://localhost:17178 to see all services.
Option 2: Using Docker Compose (Production-like)
Prerequisites:
git clone https://github.com/nitin27may/clean-architecture-docker-dotnet-angular.git clean-app
cd clean-app
cp .env.example .env
docker-compose up
Visit http://localhost in your browser.
👤 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 |
🏗️ System Architecture
Container Architecture
The application is structured into multiple services that work together:
- Frontend: Angular 21 with Material Design, TailwindCSS, and Fluent Design
- API: .NET 10 RESTful API built with Clean Architecture and Scalar docs
- Database: PostgreSQL 17 for data persistence
- pgAdmin: Database management interface
- NGINX: Reverse proxy that routes requests to the appropriate service
When using .NET Aspire, all services are orchestrated automatically with service discovery and health monitoring.
📐 Clean Architecture Explained
Why Choose 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
Core Principles
- Separation of concerns: Each layer has a specific responsibility
- Dependency rule: Dependencies point inward, with inner circles having no knowledge of outer circles
- Abstraction: Business rules are independent of UI, database, and external services
- Testability: Core business logic can be tested without dependencies on external systems
💻 Key Features
Modern Angular Frontend
- Signals-based state management with Angular 21
- Material Design with TailwindCSS v4 for responsive UI
- Fluent Design System 2 tokens and styling
- Role-based routing and permissions
- Dark/light theme support
Secure .NET Backend
- Clean Architecture implementation with .NET 10
- Generic Repository pattern with Dapper
- JWT authentication with role-based permissions
- Scalar API documentation (replacing Swagger)
- Global exception handling
Contact Management
- CRUD operations for contacts
- Role-based access control
- Search, sort, and filter functionality
- Form validation
📚 Documentation
For more detailed information, explore these documentation pages:
- Aspire Guide - Running with .NET Aspire
- Development Guide - Setting up your environment
- Clean Architecture Series - Architecture deep dives
- Frontend Documentation - Angular 21 implementation
- Backend Documentation - .NET 10 API details
- Docker Guide - Container configuration
- Feature List - Visual feature breakdown
- Roadmap - Upcoming features
🤝 Contributing
We welcome contributions! Please check 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.