Engrslan.SME.DDD 1.0.0-beta3

Important Note: This repository is under active development. Expect frequent changes, and use it at your own discretion.

🏗️ SME DDD Pattern Template

A comprehensive Domain-Driven Design (DDD) pattern template for building scalable, maintainable enterprise applications with .NET 9 and Angular 19.

📑 Table of Contents

• 📜 License
• 🎯 Overview
  • Key Highlights
• 🚀 Features
  • Backend (.NET 9)
  • Frontend (Angular 19)
• 📁 Project Structure
• 🛠️ Technology Stack
• 🚦 Getting Started
  • Prerequisites
• 📦 Template Installation
  • Install as .NET Template
  • Create New Project from Template
  • Template Parameters
  • Template Usage Examples
  • Post-Installation Steps
  • Installation
  • Development
  • Configuration
• 📖 Usage
  • Creating a New Entity
  • Using Role-Based Directives
• 🧪 Testing
• 📊 Health Checks
• 🔒 Security
  • Authentication Flow
  • Security Best Practices
• 🤝 Contributing
• 📚 Documentation
• 📝 Roadmap
• 👤 Credits
• 🙏 Acknowledgments

📜 License

This template is FREE to use for your projects, but commercial resale is restricted. See LICENSE.md for details.

✅ You CAN: Use it for commercial projects, client work, modify it freely
❌ You CANNOT: Sell or resell this template without permission

🎯 Overview

This template provides a production-ready foundation implementing Domain-Driven Design patterns with clean architecture principles. It combines the power of .NET 9 backend with Angular 19 frontend, offering a complete full-stack solution for enterprise applications.

Key Highlights

• Clean Architecture with clear separation of concerns
• OpenIddict OAuth2/OpenID Connect authentication
• Entity Framework Core with SQL Server
• Angular 19 with standalone components
• Serilog structured logging
• Health Checks for production monitoring
• CORS support for cross-origin requests
• Role-based access control directives

🚀 Features

Backend (.NET 9)

Domain Layer

• ✅ Entities and Value Objects
• ✅ Aggregates and Aggregate Roots
• ✅ Domain Events with Light Event Bus
• ✅ Domain Services
• ✅ Repository Interfaces
• ❌ Specifications Pattern (Planned)

Application Layer

• ✅ Application Services
• ✅ DTOs and Mapping
• ❌ CQRS Pattern (Planned)
• ✅ FluentValidation Integration
• ✅ Event Handlers
• ✅ Use Case Implementation

Infrastructure Layer

• ✅ Entity Framework Core 9
• ✅ Generic Repository Pattern
• ✅ Unit of Work Pattern
• ✅ Database Migrations
• ✅ SQL Server Integration
• ✅ External Service Integration

Identity & Security

• ✅ OpenIddict Integration
• ✅ OAuth2/OpenID Connect
• ✅ JWT Token Authentication
• ✅ Role-based Authorization
• ✅ CORS Configuration
• ✅ Secure Token Storage

API Layer

• ✅ RESTful API Design
• ✅ Swagger/OpenAPI Documentation
• ✅ Health Check Endpoints
• ✅ Structured Logging with Serilog
• ✅ Global Exception Handling
• ✅ API Versioning Ready

Frontend (Angular 19)

Core Features

• ❌ Standalone Components (Using Modules)
• ✅ OAuth2/OIDC Authentication
• ✅ Auth Guards and Interceptors
• ✅ Role-based Directives
• ✅ Reactive Forms
• ✅ State Management Ready

UI Components

• ✅ Responsive Landing Page
• ✅ Dashboard with Role-based Access
• ✅ Authentication Callback Handler
• ✅ Navigation with Smooth Scrolling
• ✅ Modern UI with SCSS
• ✅ Mobile-responsive Design

Security & Performance

• ✅ Token Refresh Management
• ✅ Silent Token Renewal
• ✅ Lazy Loading Ready
• ✅ Production Build Optimization
• ✅ PWA Ready Structure

🛠️ Technology Stack

Backend

• .NET 9.0 - Latest .NET framework
• Entity Framework Core 9 - ORM
• OpenIddict - OAuth2/OpenID Connect server
• SQL Server - Database
• Serilog - Structured logging
• FluentValidation - Input validation
• Fast Endpoints - RESTful API Engine

Frontend

• Angular 19 - Frontend framework
• TypeScript 5.6 - Type-safe JavaScript
• RxJS - Reactive programming
• SCSS - Styling
• ❌ Design System (Not implemented. use your preferred design system)
• OIDC Client - OAuth2/OIDC authentication

DevOps & Tools

• Docker - Containerization ready
• ❌ GitHub Actions (Not implemented)
• Swagger/OpenAPI - API documentation
• Scaler - OpenAPI Explorer
• Health Checks - Production monitoring

🚦 Getting Started

Prerequisites

• .NET 9 SDK
• Node.js 20+
• SQL Server or SQL Server Express
• Visual Studio 2022 or Visual Studio Code
• Angular CLI npm install -g @angular/cli

📦 Template Installation

Install as .NET Template

1. Install from NuGet

   dotnet new install Engrslan.SME.DDD
   

2. Install from Local Source

   # Clone the repository
   git clone https://github.com/EngRslan/ddd-pattern-template.git
   cd ddd-pattern-template
   
   # Install the template locally
   dotnet new install .
   

Create New Project from Template

# Create with default settings
dotnet new engrslan-ddd -n YourProjectName

# Create with custom options
dotnet new engrslan-ddd -n YourProjectName \
  --UseAngular true \
  --UseDocker true \
  --IncludeSampleCode true \
  --UseIdentity true \
  --EnableHealthChecks true \
  --skipRestore false

Template Parameters

Parameter	Type	Default	Description
--UseAngular	bool	true	Include Angular frontend application with OIDC authentication, dashboard, and role-based directives
--UseDocker	bool	true	Include Docker support with Dockerfile and docker-compose configurations
--IncludeSampleCode	bool	true	Include sample entities, services, DTOs, and validators to demonstrate DDD patterns
--UseIdentity	bool	true	Include OpenIddict Identity Server for OAuth2/OpenID Connect authentication
--EnableHealthChecks	bool	true	Enable health check endpoints for production monitoring
--skipRestore	bool	true	Skip automatic restore of NuGet and npm packages during project creation

Template Usage Examples

Full-Featured Application (Default)

dotnet new engrslan-ddd -n MyApp

Creates a complete DDD application with Angular frontend, Identity Server, Docker support, sample code, and health checks.

API-Only (No Frontend)

dotnet new engrslan-ddd -n MyApi --UseAngular false

Creates a backend-only API without the Angular frontend.

Clean Template (No Samples)

dotnet new engrslan-ddd -n MyApp --IncludeSampleCode false

Creates the template structure without sample entities and services.

Minimal API (No Identity, No Docker)

dotnet new engrslan-ddd -n MyMinimalApi \
  --UseAngular false \
  --UseDocker false \
  --UseIdentity false \
  --IncludeSampleCode false

Creates a minimal DDD API without authentication, frontend, or containerization.

Auto-Restore Dependencies

dotnet new engrslan-ddd -n MyApp --skipRestore false

Automatically restores NuGet packages and runs npm install after project creation.

Post-Installation Steps

After creating a project from the template:

1. Update the namespace - The template will rename Engrslan to your project name automatically
2. Configure connection strings - Update database connections in appsettings.json files
3. Run database migrations - Apply EF Core migrations to create the database schema
4. Configure CORS - Update allowed origins for your environment
5. Start development - Run Identity Server and API Host projects

Installation

Option 1: Using the NuGet Template (Recommended)

1. Create a new project from template

   # If template is already installed
   dotnet new engrslan-ddd -n YourProjectName
   cd YourProjectName
   

2. Setup the database

   # Update connection strings in appsettings.json files
   
   # Create initial migration for Application DbContext
   cd src/HttpApi.Host
   dotnet ef migrations add Initial -c ApplicationDataContext -p ../EfCore -s .
   
   # Apply migrations to create the database
   dotnet ef database update -c ApplicationDataContext
   

3. Install dependencies

   # Backend dependencies (if not auto-restored)
   dotnet restore
   
   # Frontend dependencies
   cd src/HttpApi.Host/ClientApp
   npm install
   

Option 2: Clone from GitHub

1. Clone the repository

   git clone https://github.com/EngRslan/ddd-pattern-template.git
   cd ddd-pattern-template
   

2. Setup the database

   # Update connection strings in appsettings.json files
   
   # Create initial migration for Application DbContext
   cd src/HttpApi.Host
   dotnet ef migrations add Initial -c ApplicationDataContext -p ../EfCore -s .
   
   # Apply migrations to create the database
   dotnet ef database update -c ApplicationDataContext
   

3. Install dependencies

   # Backend dependencies
   dotnet restore
   
   # Frontend dependencies
   cd src/HttpApi.Host/ClientApp
   npm install
   

Running the Application

1. Run the Identity Server (if using Identity)

   cd src/Identity
   dotnet run
   # Identity server will run on https://localhost:{{generated}}
   

2. Run the API Host

   cd src/HttpApi.Host
   dotnet run
   # API will run on https://localhost:{{generated}}
   # Angular app will run on http://localhost:4200
   

Development

Backend Development

# Run with hot reload
dotnet watch run --project src/HttpApi.Host

# Run tests
dotnet test

# Add migration
dotnet ef migrations add MigrationName -c ApplicationDataContext -p src/EfCore -s src/HttpApi.Host

# Update database
dotnet ef database update -c ApplicationDataContext -p src/EfCore -s src/HttpApi.Host

Frontend Development

cd src/HttpApi.Host/ClientApp

# Development server
npm start

# Run tests
npm test

# Build for production
npm run build

# Lint
npm run lint

Configuration

Connection Strings

Update connection strings in:

• src/HttpApi.Host/appsettings.json
• src/Identity/appsettings.json

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=DddTemplate;Trusted_Connection=true;TrustServerCertificate=true;"
  }
}

CORS Settings

Configure allowed origins in appsettings.json:

{
  "AllowedOrigins": ["http://localhost:4200", "https://yourdomain.com"]
}

📖 Usage

Creating a New Entity

1. Define the entity in Domain layer

For simple entities:

public class Product : Entity<Guid>
{
    public string Name { get; private set; }
    public decimal Price { get; private set; }
    
    public Product(string name, decimal price)
    {
        Name = name;
        Price = price;
    }
}

For aggregate roots with domain events and auditing:

public class Order : FullAuditedAggregateRoot<Guid>
{
    public string OrderNumber { get; private set; }
    public decimal TotalAmount { get; private set; }
    public OrderStatus Status { get; private set; }
    private readonly List<OrderItem> _items = new();
    public IReadOnlyCollection<OrderItem> Items => _items.AsReadOnly();
    
    public Order(string orderNumber)
    {
        OrderNumber = orderNumber;
        Status = OrderStatus.Pending;
        
        // Raise domain event
        AddDomainEvent(new OrderCreatedEvent(Id, orderNumber));
    }
    
    public void AddItem(Product product, int quantity)
    {
        var item = new OrderItem(product.Id, product.Name, product.Price, quantity);
        _items.Add(item);
        TotalAmount = _items.Sum(x => x.Price * x.Quantity);
        
        // Raise domain event
        AddDomainEvent(new OrderItemAddedEvent(Id, product.Id, quantity));
    }
    
    public void Complete()
    {
        Status = OrderStatus.Completed;
        AddDomainEvent(new OrderCompletedEvent(Id, TotalAmount));
    }
}

2. Create repository interface

public interface IProductRepository : IRepository<Product, Guid>
{
    Task<Product> GetByNameAsync(string name);
}

3. Implement repository in Infrastructure layer

public class ProductRepository : Repository<Product, Guid>, IProductRepository
{
    public async Task<Product> GetByNameAsync(string name)
    {
        return await FirstOrDefaultAsync(p => p.Name == name);
    }
}

Using Role-Based Directives

<div *appHasRole="'Admin'">
  Admin only content
</div>


<button *appHasAnyRole="['Admin', 'Manager']">
  Management Action
</button>


<div *appHasNotRole="'Guest'">
  Premium content
</div>

🧪 Testing

Unit Tests

dotnet test tests/Domain.Tests
dotnet test tests/Application.Tests

Integration Tests

dotnet test tests/HttpApi.Tests

Frontend Tests

cd src/HttpApi.Host/ClientApp
npm test
npm run test:coverage

📊 Health Checks

The application includes comprehensive health checks:

• /health - Overall health status
• /health/ready - Readiness probe
• /health/live - Liveness probe

🔒 Security

Authentication Flow

1. User clicks login → Redirected to Identity Server
2. User authenticates → Identity Server issues tokens
3. Tokens stored in browser → Used for API calls
4. Silent renewal → Tokens refreshed automatically

Security Best Practices

• ✅ HTTPS enforced in production
• ✅ CORS properly configured
• ✅ JWT tokens with expiration
• ✅ Role-based authorization
• ✅ Input validation with FluentValidation
• ✅ SQL injection protection with EF Core
• ✅ XSS protection in Angular

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

How to Contribute

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Development Guidelines

• Follow DDD principles and clean architecture
• Write unit tests for new features
• Update documentation as needed
• Follow existing code style and conventions
• Ensure all tests pass before submitting PR

📚 Documentation

• Domain-Driven Design
• Clean Architecture
• OpenIddict Documentation
• Angular Documentation
• Entity Framework Core

📝 Roadmap

• Support Permission-Based Access Control
• Add API Versioning
• Add Rich Documentation
• Add Core Unit Tests
• Add message queue integration (RabbitMQ/Azure Service Bus)
• Add Blazor WebAssembly alternative frontend
• Implement caching with Redis
• Add GraphQL support
• Add Docker Compose configuration
• Add multi-tenancy Core support
• Add support to use as a microservice module

👤 Credits

Developed by Muhammad Raslan

• GitHub: @EngRslan
• Email: [eng.m.rslan@hotmail.com]

📄 License

This project is licensed under the MIT License with Commercial Resale Restriction.

• ✅ Free to use for personal and commercial projects
• ✅ Free to modify and customize as needed
• ✅ Free to use for client projects
• ❌ Cannot be resold as a template or product without permission

See the LICENSE file for full details.

🙏 Acknowledgments

Architecture Inspiration

• File organization and structure inspired by ABP Framework - A complete infrastructure to create modern web applications
• Clean Architecture principles by Robert C. Martin (Uncle Bob)
• Domain-Driven Design concepts by Eric Evans

External Dependencies

Backend Libraries

• OpenIddict - Flexible OpenID Connect server framework
• Entity Framework Core - Modern object-database mapper for .NET
• Serilog - Simple .NET logging with structured events
• FluentValidation - Popular .NET validation library

Frontend Libraries

• Angular - Platform for building mobile and desktop apps
• angular-oauth2-oidc - OAuth2 and OpenID Connect (OIDC) client
• RxJS - Reactive Extensions Library for JavaScript
• TypeScript - Typed superset of JavaScript

Development Tools

• NSwag - TypeScript client code generator for OpenAPI/Swagger specifications
  • Automatically generates TypeScript contracts from your .NET API
  • Ensures type-safe API communication between backend and frontend
  • Reduces manual contract synchronization efforts

Special Thanks

• Thanks to all contributors who have helped shape this template
• The .NET and Angular communities for continuous support and inspiration
• Built with ❤️ for the developer community

---

<p align="center"> Made with ❤️ by Muhammad Raslan </p>