Farrahni Project - Clean Architecture Guide

📋 Table of Contents

Project Overview
Architecture Pattern
Project Structure
Layer Responsibilities
Dependency Flow
Workflow Guidelines
Development Standards
Getting Started

🏗️ Project Overview

This project follows Clean Architecture principles combined with Domain-Driven Design (DDD) patterns to create a maintainable, testable, and scalable .NET Web API.

🎯 Architecture Pattern

The solution implements the Onion Architecture (Clean Architecture) with these core principles:

Dependency Inversion: Dependencies point inward toward the domain
Separation of Concerns: Each layer has distinct responsibilities
Framework Independence: Business logic is isolated from external frameworks
Testability: Easy to unit test business logic in isolation

📁 Project Structure

Farrahni/
├── src/
│   ├── Farrahni.API/                 # 🌐 Presentation Layer
│   ├── Farrahni.Application/         # 📚 Application Layer  
│   ├── Farrahni.Domain/              # 🏛️ Domain Layer (Core)
│   └── Farrahni.Infrastructure/      # 🔧 Infrastructure Layer
├── tests/
│   ├── Farrahni.UnitTests/          # Unit Tests
│   └── Farrahni.IntegrationTests/   # Integration Tests
├── docs/                            # Documentation
├── docker-compose.yml               # Docker configuration
├── Farrahni.sln                     # Solution file
└── README.md                        # This file

🎯 Layer Responsibilities

🌐 Presentation Layer (`Farrahni.API`)

Purpose: Handles HTTP requests and responses, user interface concerns.

Farrahni.API/
├── Controllers/          # API endpoints and HTTP logic
│   ├── ProductsController.cs
│   ├── UsersController.cs
│   └── OrdersController.cs
├── Middlewares/          # Custom middleware components
│   ├── GlobalExceptionHandlerMiddleware.cs
│   ├── RequestLoggingMiddleware.cs
│   └── AuthenticationMiddleware.cs
├── Filters/              # Action filters and attributes
│   ├── ValidationFilter.cs
│   ├── AuthorizeFilter.cs
│   └── CacheFilter.cs
├── Extensions/           # Service configuration extensions
│   ├── PresentationServiceExtensions.cs
│   └── SwaggerExtensions.cs
├── Program.cs            # Application entry point
└── appsettings.json      # Configuration files

Responsibilities:

✅ HTTP request/response handling
✅ Input validation and model binding
✅ Authentication and authorization
✅ API documentation (Swagger)
✅ Dependency injection configuration
❌ Business logic (belongs in Application/Domain)
❌ Data access (belongs in Infrastructure)

📚 Application Layer (`Farrahni.Application`)

Purpose: Orchestrates business workflows and use cases.

Farrahni.Application/
├── DTOs/                 # Data Transfer Objects
│   ├── ProductDto.cs
│   ├── CreateProductDto.cs
│   └── UpdateProductDto.cs
├── Interfaces/           # Service contracts
│   ├── IProductService.cs
│   ├── IUserService.cs
│   └── IEmailService.cs
├── Services/             # Application services
│   ├── ProductService.cs
│   ├── UserService.cs
│   └── OrderService.cs
├── Validators/           # Input validation rules
│   ├── CreateProductValidator.cs
│   └── UpdateUserValidator.cs
├── Mappings/             # AutoMapper profiles
│   ├── ProductProfile.cs
│   └── UserProfile.cs
├── Common/               # Shared application logic
│   ├── Models/
│   │   ├── ApiResponse.cs
│   │   └── PaginatedResult.cs
│   ├── Exceptions/
│   │   ├── NotFoundException.cs
│   │   └── ValidationException.cs
│   └── Behaviors/        # MediatR behaviors
│       ├── ValidationBehavior.cs
│       └── LoggingBehavior.cs
└── ApplicationServiceExtensions.cs

Responsibilities:

✅ Use case implementation
✅ DTO mapping and transformation
✅ Input validation
✅ Business workflow orchestration
✅ Cross-cutting concerns (logging, caching)
❌ UI concerns (belongs in Presentation)
❌ Data persistence logic (belongs in Infrastructure)
❌ Core business rules (belongs in Domain)

🏛️ Domain Layer (`Farrahni.Domain`) - CORE

Purpose: Contains pure business logic and domain models.

Farrahni.Domain/
├── Entities/             # Domain entities (business objects)
│   ├── Product.cs
│   ├── User.cs
│   ├── Order.cs
│   └── Category.cs
├── ValueObjects/         # Immutable domain values
│   ├── Money.cs
│   ├── Address.cs
│   └── Email.cs
├── Interfaces/           # Domain contracts
│   ├── IRepository.cs
│   ├── IUnitOfWork.cs
│   └── IDomainService.cs
├── Events/               # Domain events
│   ├── ProductCreatedEvent.cs
│   └── OrderPlacedEvent.cs
├── Services/             # Domain services
│   ├── PricingService.cs
│   └── InventoryService.cs
├── Enums/                # Domain enumerations
│   ├── OrderStatus.cs
│   └── UserRole.cs
└── Common/               # Shared domain logic
    ├── BaseEntity.cs
    ├── IAggregateRoot.cs
    └── IDomainEvent.cs

Responsibilities:

✅ Core business entities and rules
✅ Domain services and logic
✅ Value objects and enumerations
✅ Domain events and behaviors
✅ Repository interfaces
❌ External dependencies (UI, Database, APIs)
❌ Framework-specific code

⚠️ IMPORTANT: Domain layer should have NO external dependencies!

🔧 Infrastructure Layer (`Farrahni.Infrastructure`)

Purpose: Handles external concerns and technical implementations.

Farrahni.Infrastructure/
├── Data/                 # Database-related implementations
│   ├── Context/
│   │   └── ApplicationDbContext.cs
│   ├── Repositories/
│   │   ├── Repository.cs
│   │   ├── ProductRepository.cs
│   │   └── UserRepository.cs
│   ├── Configurations/   # Entity Framework configurations
│   │   ├── ProductConfiguration.cs
│   │   └── UserConfiguration.cs
│   └── Migrations/       # EF Core migrations
├── Services/             # External service implementations
│   ├── EmailService.cs
│   ├── FileStorageService.cs
│   └── CachingService.cs
├── External/             # Third-party integrations
│   ├── PaymentService.cs
│   ├── GoogleMapsService.cs
│   └── AzureBlobStorage.cs
└── InfrastructureServiceExtensions.cs

Responsibilities:

✅ Database access and ORM configuration
✅ External API integrations
✅ File system operations
✅ Email/SMS services
✅ Caching implementations
✅ Third-party service integrations
❌ Business logic (belongs in Domain/Application)

🔄 Dependency Flow

┌─────────────────────────────────────────┐
│             Presentation                │
│           (Farrahni.API)               │
└─────────┬───────────────────┬───────────┘
          │                   │
          ▼                   ▼
┌─────────────────┐  ┌─────────────────┐
│   Application   │  │ Infrastructure  │
│ (Farrahni.App)  │  │ (Farrahni.Infra)│
└─────────┬───────┘  └─────────┬───────┘
          │                   │
          ▼                   ▼
┌─────────────────────────────────────────┐
│              Domain                     │
│          (Farrahni.Domain)              │
│             ⭐ CORE ⭐                   │
└─────────────────────────────────────────┘

Dependency Rules:

✅ API → Application + Infrastructure
✅ Application → Domain only
✅ Infrastructure → Domain + Application
✅ Domain → No external dependencies
❌ Domain should never depend on outer layers

🚀 Workflow Guidelines

Creating a New Feature (e.g., Product Management)

1️⃣ Start with Domain (Inside-Out Approach)

// Farrahni.Domain/Entities/Product.cs
public class Product : BaseEntity
{
    private Product() { } // EF Constructor
    
    public Product(string name, decimal price)
    {
        if (string.IsNullOrEmpty(name)) 
            throw new ArgumentException("Name is required");
        if (price <= 0) 
            throw new ArgumentException("Price must be positive");
            
        Name = name;
        Price = price;
    }
    
    public string Name { get; private set; }
    public decimal Price { get; private set; }
    
    public void UpdatePrice(decimal newPrice)
    {
        if (newPrice <= 0) 
            throw new ArgumentException("Price must be positive");
        Price = newPrice;
    }
}

2️⃣ Create Application Services

// Farrahni.Application/DTOs/ProductDto.cs
public class ProductDto
{
    public Guid Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
}

// Farrahni.Application/Interfaces/IProductService.cs
public interface IProductService
{
    Task<ApiResponse<ProductDto>> GetByIdAsync(Guid id);
    Task<ApiResponse<ProductDto>> CreateAsync(CreateProductDto dto);
}

// Farrahni.Application/Services/ProductService.cs
public class ProductService : IProductService
{
    // Implementation using repository and mapping
}

3️⃣ Implement Infrastructure

// Farrahni.Infrastructure/Data/Configurations/ProductConfiguration.cs
public class ProductConfiguration : IEntityTypeConfiguration<Product>
{
    public void Configure(EntityTypeBuilder<Product> builder)
    {
        builder.Property(p => p.Name).HasMaxLength(200);
        builder.Property(p => p.Price).HasPrecision(18, 2);
    }
}

4️⃣ Create API Controller

// Farrahni.API/Controllers/ProductsController.cs
[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    private readonly IProductService _productService;
    
    [HttpGet("{id}")]
    public async Task<IActionResult> GetById(Guid id)
    {
        var result = await _productService.GetByIdAsync(id);
        return result.Success ? Ok(result) : NotFound(result);
    }
}

5️⃣ Register Dependencies

// Update ApplicationServiceExtensions.cs
services.AddScoped<IProductService, ProductService>();

// Update InfrastructureServiceExtensions.cs  
services.AddScoped<IProductRepository, ProductRepository>();

🔄 Development Workflow

Domain First: Start with entities and business rules
Test Early: Write unit tests for domain logic
Application Layer: Create DTOs, services, and validators
Infrastructure: Implement repositories and external services
API Layer: Create controllers and configure endpoints
Integration: Wire up dependency injection
Test: Integration and end-to-end testing

📋 Development Standards

Naming Conventions

Entities: Product, User, Order
DTOs: ProductDto, CreateProductDto, UpdateProductDto
Services: IProductService, ProductService
Repositories: IProductRepository, ProductRepository
Controllers: ProductsController (plural)

File Organization

✅ One class per file
✅ Namespace matches folder structure
✅ Group related functionality together
✅ Separate interfaces from implementations

Dependency Injection

// ✅ Use interfaces for loose coupling
services.AddScoped<IProductService, ProductService>();

// ❌ Don't register concrete classes directly
services.AddScoped<ProductService>();

Error Handling

// ✅ Use custom exceptions with meaningful messages
throw new NotFoundException($"Product with ID {id} not found");

// ✅ Use ApiResponse for consistent API responses
return ApiResponse<ProductDto>.FailureResult("Product not found");

🚀 Getting Started

Prerequisites

.NET 8.0 SDK
SQL Server or PostgreSQL
Docker (optional)

Setup

Clone the repository
```
git clone <repository-url>
cd Farrahni
```
Restore dependencies
```
dotnet restore
```

Update connection string

// appsettings.json
{
  "ConnectionStrings": {
    "DefaultConnection": "your-connection-string-here"
  }
}

Run migrations

dotnet ef database update --project src/Farrahni.API

Run the application
```
dotnet run --project src/Farrahni.API
```
Access Swagger UI
```
https://localhost:7xxx/swagger
```

Docker Setup

Build and run with Docker Compose
```
docker-compose up --build
```
Access the application
- API: http://localhost:8080/swagger
- Database: localhost:5432 (PostgreSQL)
- pgAdmin: http://localhost:8081

📚 Additional Resources

Remember: The goal is to keep business logic pure and independent of external frameworks, making the application maintainable, testable, and adaptable to change.

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.config		.config
.idea/.idea.Backend/.idea		.idea/.idea.Backend/.idea
Farrahni.API		Farrahni.API
Farrahni.Application		Farrahni.Application
Farrahni.Domain		Farrahni.Domain
Farrahni.Infrastructure		Farrahni.Infrastructure
src/obj		src/obj
.DS_Store		.DS_Store
.gitignore		.gitignore
Backend.sln		Backend.sln
Dockerfile		Dockerfile
README.md		README.md
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation

Farrahni Project - Clean Architecture Guide

📋 Table of Contents

🏗️ Project Overview

🎯 Architecture Pattern

📁 Project Structure

🎯 Layer Responsibilities

🌐 Presentation Layer (Farrahni.API)

📚 Application Layer (Farrahni.Application)

🏛️ Domain Layer (Farrahni.Domain) - CORE

🔧 Infrastructure Layer (Farrahni.Infrastructure)

🔄 Dependency Flow

🚀 Workflow Guidelines

Creating a New Feature (e.g., Product Management)

1️⃣ Start with Domain (Inside-Out Approach)

2️⃣ Create Application Services

3️⃣ Implement Infrastructure

4️⃣ Create API Controller

5️⃣ Register Dependencies

🔄 Development Workflow

📋 Development Standards

Naming Conventions

File Organization

Dependency Injection

Error Handling

🚀 Getting Started

Prerequisites

Setup

Docker Setup

📚 Additional Resources

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

🌐 Presentation Layer (`Farrahni.API`)

📚 Application Layer (`Farrahni.Application`)

🏛️ Domain Layer (`Farrahni.Domain`) - CORE

🔧 Infrastructure Layer (`Farrahni.Infrastructure`)

Packages