Learning Project — This project is built for learning purposes. Any developer is welcome to clone it, explore the code, experiment, and build on top of it.

A full-featured e-commerce backend built with .NET 10 and Clean Architecture. The solution exposes two separate REST APIs — one for admin management and one for customer-facing operations — orchestrated with .NET Aspire.

• Architecture Overview
• Project Structure
• Tech Stack
• Domain Model
• API Reference
  • Admin API
  • Customer API
• Authentication
• Request & Response Format
• Getting Started
  • Prerequisites
  • Configuration
  • Running the Application
• Running Tests
• Key Features

The solution follows Clean Architecture with a strict dependency rule — inner layers never depend on outer layers:

Domain  ←  Application  ←  Infrastructure  ←  API

Additional patterns in use:

• Result pattern — services return Result<T> instead of throwing exceptions for flow control
• Repository + Unit of Work — abstracts data access (both EF Core and Dapper)
• Value objects — domain validation is encapsulated in value object constructors
• Background service — email sending is offloaded to an in-memory queue processed by a hosted service

eShop/
├── eShop.Api.Admin/            # Admin-facing REST API
│   ├── Controllers/
│   ├── Extensions/             # JWT & Swagger configuration
│   ├── Middlewares/            # Global exception handler
│   ├── Responses/              # ApiResponse<T> envelope
│   └── Program.cs
├── eShop.Api.Customer/         # Customer-facing REST API
│   ├── Controllers/
│   ├── Extensions/
│   ├── Middlewares/
│   ├── Responses/
│   └── Program.cs
├── eShop.AppHost/              # .NET Aspire orchestration host
├── eShop.Application/          # Use cases & business logic
│   ├── Constants/
│   ├── Enums/
│   ├── Exceptions/
│   ├── Extensions/
│   ├── Helpers/
│   ├── Interfaces/
│   ├── Requests/
│   ├── Responses/
│   ├── Services/
│   └── Validations/
├── eShop.Domain/               # Core domain
│   ├── Enums/
│   ├── Exceptions/
│   ├── Helpers/
│   ├── Interfaces/
│   ├── Models/
│   ├── Primitives/
│   └── ValueObjects/
├── eShop.Infrastructure/       # Data access & external services
│   ├── BackgroundServices/
│   ├── Configurations/         # EF Core entity configs
│   ├── Context/
│   ├── IoC/
│   ├── Migrations/
│   ├── Repositories/
│   └── Services/
├── eShop.Application.Tests/
├── eShop.Domain.Tests/
└── eShop.Infrastructure.Tests/

ProductName, ProductDescription, UnitPrice, UnitQuantity, Image, CategoryName, Email, Username, FullName, CommentText

Each value object validates its own invariants on construction and throws a DomainValidationException on invalid input.

• BaseEntity — Id (Guid)
• AuditableBaseEntity — extends BaseEntity with Created, CreatedBy, LastModified, LastModifiedBy (auto-populated on save)

Product, Category, and User are never hard-deleted — they carry an IsDeleted flag.

All endpoints return JSON. The response envelope is:

// Success
{ "data": { ... }, "message": "...", "totalCount": 25 }

// Error
{ "message": "Reason for failure" }

// No content (204)
// empty body

totalCount and message are omitted when null.

Base URL: http://localhost:{port}/api Authentication: JWT Bearer — include Authorization: Bearer <token> on all protected routes.

Login request body:

{ "username": "admin", "password": "Admin@123" }

Base URL: http://localhost:{port}/api

JWT Bearer tokens are used across both APIs.

• Tokens are generated on login and must be sent in the Authorization: Bearer <token> header
• Role-based authorization: Admin role for the Admin API, Customer role for protected Customer endpoints
• Token lifetime validation is enabled; issuer/audience validation is disabled (configurable)

Password requirements: minimum 4 characters, at least one uppercase letter, one lowercase letter, one digit, and one special character.

Password hashing: PBKDF2-SHA256 with 100,000 iterations and a 16-byte random salt per user.

FluentValidation runs automatically on all requests. Invalid input returns 400 Bad Request:

{ "message": "Validation error description" }

Unhandled exceptions are caught by the global exception handler middleware:

• .NET 10 SDK
• SQL Server (local or remote)
• (Optional) .NET Aspire workload for orchestrated startup

Both API projects require an appsettings.json (or user secrets / environment variables) with the following keys:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=.;Database=eShopDb;Trusted_Connection=True;"
  },
  "Jwt": {
    "SecretKey": "your-secret-key-at-least-32-characters"
  },
  "SeedAdmin": {
    "Password": "Admin@123"
  },
  "OpenAI": {
    "ApiKey": "your-openai-api-key"
  },
  "EmailSettings": {
    "Host": "smtp.example.com",
    "Port": 587,
    "Username": "[email protected]",
    "Password": "your-email-password"
  }
}

Option 1 — With .NET Aspire (recommended):

dotnet run --project eShop.AppHost

This starts both APIs and the Aspire dashboard in one command.

Option 2 — Run APIs individually:

# Apply migrations (run once)
dotnet ef database update --project eShop.Infrastructure --startup-project eShop.Api.Admin

# Admin API
dotnet run --project eShop.Api.Admin

# Customer API
dotnet run --project eShop.Api.Customer

Swagger UI is available at /swagger in the Development environment.

A default admin user is seeded on first startup using the SeedAdmin:Password configuration value.

dotnet test

Test projects:

• Hierarchical categories — categories support a parent/child tree structure with cascading soft-deletes
• AI product descriptions — admins can generate product descriptions via GPT-4o-mini
• Shopping basket — supports guest-to-authenticated basket merging
• Order placement — places an order, reduces basket, and sends an HTML confirmation email asynchronously
• Email queue — emails are queued in-memory and dispatched by a background hosted service, keeping order placement fast
• Dual data access — EF Core for writes and complex queries, Dapper for lightweight read queries
• Auditing — all auditable entities automatically track creation and modification timestamps and user
• Clean separation of concerns — Admin and Customer APIs share the same Application and Infrastructure layers but have completely separate controllers, DTOs, and service interfaces