@@ -28,18 +23,19 @@
Contact Management Application with Role-Based Access Control
-## ✨ What is this?
+## What is this?
A production-ready **full-stack starter kit** built with modern technologies and best practices:
-- **Frontend**: Angular 20 with signals, Material Design, and TailwindCSS
-- **Backend**: .NET 9 API with Clean Architecture
-- **Database**: PostgreSQL with Dapper
+- **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?
+## Why Clean Architecture?
@@ -54,7 +50,44 @@ Clean Architecture provides **significant benefits** for your application:
[Clean Architecture Series](./docs/architecture-series.md) - Read more about it!
-## 🚀 Quick Start
+## 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](https://dotnet.microsoft.com/download/dotnet/10.0) or later
+- [Node.js 22 LTS](https://nodejs.org/) (**not** Node 23 - use LTS version only)
+- [Docker Desktop](https://www.docker.com/products/docker-desktop) (for PostgreSQL container)
+
+#### Steps
+
+```bash
+# 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)
```bash
# Clone the repository
@@ -68,10 +101,10 @@ cp .env.example .env
docker-compose up
```
-🔗 Then access:
+Then access:
- Frontend: http://localhost
- API: http://localhost/api
-- Swagger: http://localhost/swagger
+- Scalar API Docs: http://localhost/scalar/v1
### 👤 Default Users
@@ -81,47 +114,80 @@ docker-compose up
| editor@gmail.com | P@ssword#321 | Editor |
| reader@gmail.com | P@ssword#321 | Reader |
-## 🔥 Key Features
+## Key Features
@@ -19,23 +19,25 @@ The frontend of this project is built with Angular 20, leveraging modern Angular
## Technology Stack
-- **Angular 20**
+- **Angular 21**
- Standalone components architecture
- Modern dependency injection with `inject()`
- Signal-based state management
- Reactive programming with RxJS
- Lazy-loaded routes for optimized performance
-- **Angular Material 19**
+- **Angular Material 21**
- Comprehensive UI component library
- Custom theme configuration
- Dark mode support
- Accessibility features
-- **TailwindCSS v4**
+- **TailwindCSS v4 with Fluent Design**
- Utility-first CSS framework
- - Integration with Material Design
- - Custom color schemes
+ - Fluent Design System 2 tokens
+ - Microsoft-style elevation shadows
+ - Comprehensive color system (neutral, brand, status)
+ - Motion and animation tokens
- Responsive design utilities
- **Additional Libraries**
diff --git a/docs/index.md b/docs/index.md
index 18dc5be..2a29866 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -9,7 +9,7 @@ permalink: /
# Clean Architecture Full-Stack Starter
{: .fs-9 }
-A production-ready full-stack application with Angular 20, .NET 9, and PostgreSQL using Clean Architecture principles
+A production-ready full-stack application with Angular 21, .NET 10, and PostgreSQL 17 using Clean Architecture principles, orchestrated with .NET Aspire
{: .fs-6 .fw-300 }
[Get Started](#-quick-start-in-60-seconds){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 }
@@ -26,45 +26,57 @@ A production-ready full-stack application with Angular 20, .NET 9, and PostgreSQ
-A modern, full-stack contact management system built with Angular 20, .NET 9, and PostgreSQL following Clean Architecture principles. This project demonstrates how to structure enterprise applications for maintainability, testability, and scalability while providing a complete development workflow with Docker containerization.
+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 20** with signals, standalone components, and Material Design
-- **.NET 9** with dependency injection and repository pattern
-- **PostgreSQL** with Dapper for efficient data access
+- **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 in 60 Seconds
+## 🚀 Quick Start
-### Prerequisites
+### Option 1: Using .NET Aspire (Recommended for Development)
-- [Docker](https://www.docker.com/products/docker-desktop){:target="_blank"} and Docker Compose
-- [Git](https://git-scm.com/downloads){:target="_blank"}
+**Prerequisites:**
+- [.NET SDK 10.0](https://dotnet.microsoft.com/download/dotnet/10.0){:target="_blank"} or later
+- [Node.js 22 LTS](https://nodejs.org/){:target="_blank"} (not Node 23)
+- [Docker Desktop](https://www.docker.com/products/docker-desktop){:target="_blank"}
-### Launch Commands
-
-Clone the repository:
```bash
git clone https://github.com/nitin27may/clean-architecture-docker-dotnet-angular.git clean-app
cd clean-app
-```
-Create environment file:
-```bash
-cp .env.example .env
+# Install frontend dependencies
+cd frontend && npm install && cd ..
+
+# Run with Aspire
+dotnet run --project aspire/AppHost
```
-Start the application:
+Access the Aspire Dashboard at `https://localhost:17178` to see all services.
+
+### Option 2: Using Docker Compose (Production-like)
+
+**Prerequisites:**
+- [Docker](https://www.docker.com/products/docker-desktop){:target="_blank"} and Docker Compose
+- [Git](https://git-scm.com/downloads){:target="_blank"}
+
```bash
+git clone https://github.com/nitin27may/clean-architecture-docker-dotnet-angular.git clean-app
+cd clean-app
+cp .env.example .env
docker-compose up
```
-That's it! Visit [http://localhost](http://localhost) in your browser.
+Visit [http://localhost](http://localhost) in your browser.
## 👤 Default Users
@@ -84,12 +96,15 @@ That's it! Visit [http://localhost](http://localhost) in your browser.
### Container Architecture
-The application is structured into multiple containers that work together:
+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
-- **Frontend Container**: Angular 20 with Material Design and TailwindCSS
-- **API Container**: .NET 9 RESTful API built with Clean Architecture
-- **Database Container**: PostgreSQL for data persistence
-- **NGINX Container**: 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
@@ -119,16 +134,18 @@ Clean Architecture provides **significant benefits** for your application:
### Modern Angular Frontend
-- **Signals-based state management**
-- **Material Design with TailwindCSS** for responsive UI
+- **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**
-- **Generic Repository pattern**
-- **JWT authentication**
+- **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
@@ -142,13 +159,14 @@ Clean Architecture provides **significant benefits** for your application:
For more detailed information, explore these documentation pages:
-- [Development Guide](development-guide.md)
-- [Clean Architecture Series](architecture-series.md)
-- [Frontend Documentation](frontend.md)
-- [Backend Documentation](backend.md)
-- [Feature List](visual-feature-guide.md)
-- [Roadmap](roadmap.md)
-- [Visual Feature Guide](visual-feature-guide.md)
+- [Aspire Guide](aspire-guide.md) - Running with .NET Aspire
+- [Development Guide](development-guide.md) - Setting up your environment
+- [Clean Architecture Series](architecture-series.md) - Architecture deep dives
+- [Frontend Documentation](frontend.md) - Angular 21 implementation
+- [Backend Documentation](backend.md) - .NET 10 API details
+- [Docker Guide](docker-guide.md) - Container configuration
+- [Feature List](visual-feature-guide.md) - Visual feature breakdown
+- [Roadmap](roadmap.md) - Upcoming features
## 🤝 Contributing
diff --git a/frontend/.github/copilot-design-checklist.md b/frontend/.github/copilot-design-checklist.md
new file mode 100644
index 0000000..abfa0ec
--- /dev/null
+++ b/frontend/.github/copilot-design-checklist.md
@@ -0,0 +1,39 @@
+# Design Quality Checklist
+
+Use this checklist before committing any UI component:
+
+## Visual Consistency
+- [ ] Spacing uses 8px grid (4, 8, 16, 24, 32, 48, 64)
+- [ ] Colors from theme palette (no hardcoded hex)
+- [ ] Typography follows Material scale
+- [ ] Consistent elevation (0, 1, 2, 4, 8)
+- [ ] Border radius consistent (sm/md/lg)
+
+## Responsiveness
+- [ ] Works on mobile (< 600px)
+- [ ] Works on tablet (600-960px)
+- [ ] Works on desktop (> 960px)
+- [ ] Touch targets minimum 44x44px
+- [ ] Text readable at all sizes
+
+## Theme Support
+- [ ] Light theme perfect
+- [ ] Dark theme perfect
+- [ ] No hardcoded colors
+- [ ] Proper contrast (WCAG AA)
+- [ ] Icons/borders adapt
+
+## Code Quality
+- [ ] Standalone component
+- [ ] OnPush change detection
+- [ ] Signals for state
+- [ ] New control flow syntax
+- [ ] Proper TypeScript types
+- [ ] No any types
+- [ ] ARIA labels present
+
+## Performance
+- [ ] Lazy loading where appropriate
+- [ ] Track by in loops
+- [ ] No unnecessary re-renders
+- [ ] Optimized imports
\ No newline at end of file
diff --git a/frontend/.github/copilot-instructions.md b/frontend/.github/copilot-instructions.md
index 5d39e9d..9395a37 100644
--- a/frontend/.github/copilot-instructions.md
+++ b/frontend/.github/copilot-instructions.md
@@ -1,24 +1,1023 @@
-# Use modern dependency injection syntax
+# GitHub Copilot Custom Instructions: Angular 21 + Material 3 + Tailwind 4 Enterprise Admin Dashboard
-- Whenever you have to inject a dependency using Angular DI system, use the `inject` function instead of constructor based injection.
- - this will apply to injecting services, tokens and parent components e.g. in directives as well
+## Project Overview
+This is an enterprise-grade admin dashboard built with Angular 21, Angular Material 3, and Tailwind CSS 4. The application follows modern Angular best practices with standalone components, signals-based state management, and a comprehensive design system that supports responsive layouts and light/dark theming.
+---
+## CRITICAL RULES - READ FIRST
-# For all state in components and directives, use a signal instead of a class property
-- For example:
+### 1. Technology Stack (Non-Negotiable)
+- **Angular 21**: Use latest features (signals, new control flow, standalone components)
+- **Angular Material 19+**: Material Design 3 components only
+- **Tailwind CSS 4**: CSS-first configuration (@theme syntax, NO tailwind.config.js)
+- **TypeScript 5.5+**: Strict mode enabled
-` counter = signal(0); `
+### 2. Framework Hierarchy
+```
+ALWAYS FOLLOW THIS ORDER:
+1. Angular Material → Structure, behavior, accessibility
+2. Tailwind 4 → Layout, spacing, responsive utilities
+3. Custom CSS → ONLY when absolutely necessary
-- For derived state from an existing signal, use computeds as follows.
+NEVER override Material component internals with custom CSS.
+NEVER duplicate Material functionality with Tailwind.
+```
-` doubleCounter = computed(() => this.counter() * 2); `
+---
+## ANGULAR 21 REQUIREMENTS
-- Use function style for guard, interceptors
+### Component Architecture
-- for the service call if using subscribe use next:
+#### ALWAYS Use Standalone Components
+```typescript
+// ✅ CORRECT
+@Component({
+ selector: 'app-dashboard',
+ standalone: true,
+ imports: [CommonModule, MatCardModule, ...],
+ template: `...`
+})
+export class DashboardComponent {}
-# For styling use Angular Material 19 with theming and tailwind v4
- - TailwindCSS for utility-first styling
- - make sure everything supporting the theme
+// ❌ WRONG - No NgModule components
+@NgModule({ ... })
+```
+
+#### ALWAYS Use Signals for State Management
+```typescript
+// ✅ CORRECT - Use signals
+export class MyComponent {
+ count = signal(0);
+ doubleCount = computed(() => this.count() * 2);
+ items = signal([]);
+
+ increment() {
+ this.count.update(n => n + 1);
+ }
+}
+
+// ❌ WRONG - Don't use traditional properties
+export class MyComponent {
+ count = 0; // AVOID
+ items: Item[] = []; // AVOID
+}
+```
+
+#### ALWAYS Use New Control Flow Syntax
+```typescript
+// ✅ CORRECT - New @syntax
+@Component({
+ template: `
+ @if (isLoggedIn()) {
+
+ } @else {
+
+ }
+
+ @for (item of items(); track item.id) {
+
+ }
+
+ @switch (status()) {
+ @case ('loading') { }
+ @case ('success') { }
+ @case ('error') { }
+ }
+ `
+})
+
+// ❌ WRONG - Old *ng syntax
+template: `
+
@@ -16,9 +10,10 @@
- 
- 
- 
+ 
+ 
+ 
+ 
@@ -54,7 +50,44 @@ Clean Architecture provides **significant benefits** for your application:
[Clean Architecture Series](./docs/architecture-series.md) - Read more about it!
-## 🚀 Quick Start
+## 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](https://dotnet.microsoft.com/download/dotnet/10.0) or later
+- [Node.js 22 LTS](https://nodejs.org/) (**not** Node 23 - use LTS version only)
+- [Docker Desktop](https://www.docker.com/products/docker-desktop) (for PostgreSQL container)
+
+#### Steps
+
+```bash
+# 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)
```bash
# Clone the repository
@@ -68,10 +101,10 @@ cp .env.example .env
docker-compose up
```
-🔗 Then access:
+Then access:
- Frontend: http://localhost
- API: http://localhost/api
-- Swagger: http://localhost/swagger
+- Scalar API Docs: http://localhost/scalar/v1
### 👤 Default Users
@@ -81,47 +114,80 @@ docker-compose up
| editor@gmail.com | P@ssword#321 | Editor |
| reader@gmail.com | P@ssword#321 | Reader |
-## 🔥 Key Features
+## Key Features
@@ -129,30 +195,45 @@ docker-compose up
Container Architecture Overview