🛒 StackCart

A modern, full-featured e-commerce platform built with .NET 10 as a Modular Monolith with Clean Architecture, CQRS, and multi-tenant isolation.

Manage tenants, users, products, categories, orders, customers, and shopping carts — all from a single, secure, multi-tenant API.

---

📖 Table of Contents

• ✨ Features
• 🛠 Tech Stack
• 📂 Project Structure
• 🚀 Getting Started
• 🏗 Architecture & Design Patterns
• 🌐 API Endpoints
• 🗄 Database Design
• 🔐 Security & Middleware
• 📄 License

---

✨ Features

Multi-Tenancy

• Tenant isolation via shared-database with TenantId column on every tenant-scoped table.
• Automatic tenant resolution from X-Tenant-Id HTTP header.
• Tenant validation middleware — verifies JWT tenant_id claim matches the header.

User Management

• Registration with email uniqueness enforced per tenant.
• Login with JWT token generation (BCrypt password hashing).
• Profile retrieval (GET /api/users/me) with Redis caching (15-min TTL).
• User deactivation for account lifecycle management.

Catalog Management

• Products — Create, read, search (paginated), update, delete. SKU uniqueness per tenant.
• Categories — Create, read by ID/slug, list all, update, delete. Self-referencing hierarchy.
• Price value object with amount + currency, DB CHECK constraint (price > 0).
• Stock tracking with DB CHECK constraint (stock >= 0).

Order Management

• Order lifecycle — Create, add items, submit, cancel.
• Order status tracking via OrderStatus enum.
• Paginated order listing with tenant isolation.
• Domain events — OrderSubmittedDomainEvent raised on submission.

Customer Management

• Customer profiles linked to user accounts.
• Address management via CustomerAddress value object (street, city, state, country, postal code).
• Self-service — customers manage their own profile via /api/customers/me.

Shopping Cart

• Full cart CRUD — Add items, update quantities, remove items, clear cart.
• Checkout flow — Converts cart to an order and clears the cart.
• Real-time capacity checks — Duplicate prevention and stock validation.

Cross-Cutting

• CQRS — Every action is a Command (mutates) or Query (reads).
• Result Pattern — All operations return Result<T> or Result. No exceptions for control flow.
• Custom Mediator — Built on native DI (no MediatR dependency).
• Soft Deletes — Entities are marked IsDeleted, never physically removed.
• Audit Trail — CreatedAtUtc, CreatedBy, ModifiedAtUtc, ModifiedBy auto-set on every entity.
• Hybrid Caching — Redis-backed HybridCache for high-performance lookups.
• Structured Logging — Serilog with console (dev) and MongoDB (prod) sinks.
• JWT Authentication — Bearer token with sub, email, tenant_id, tenant_slug claims.

---

🛠 Tech Stack

Layer	Technology
Runtime	.NET 10
API Host	Minimal APIs (no controllers)
ORM	Entity Framework Core 10
Database	PostgreSQL 18 (single shared DB)
Caching	HybridCache (with Redis 8 backing store)
Logging	Serilog with MongoDB 8 sink
Mapping	Mapster 10 (planned)
Mediator	Custom mediator via native DI
Auth	JWT Bearer (Microsoft.AspNetCore.Authentication.JwtBearer)
Password Hashing	BCrypt.Net-Next 4.2.0
Proxy/LB	Nginx 1.29 (planned)
Containerization	Docker Compose (planned)
Testing	xUnit + FluentAssertions + Testcontainers (planned)

---

📂 Project Structure

StackCart/
├── Directory.Packages.props              # Central package version management
├── StackCart.slnx                        # Solution file (new .slnx format)
├── .env.example                          # Environment variable template
├── project-architecture-map.md           # Living architecture documentation
│
├── src/
│   ├── BuildingBlocks/                   # Shared infrastructure & domain primitives
│   │   ├── StackCart.BuildingBlocks.Domain/
│   │   │   ├── Abstractions/             # Entity, AggregateRoot, ValueObject, IDomainEvent
│   │   │   ├── Shared/                   # Error, Result (Result Pattern)
│   │   │   └── MultiTenancy/             # ITenantScoped, ITenantContext
│   │   │
│   │   ├── StackCart.BuildingBlocks.Application/
│   │   │   ├── Messaging/                # IRequest, IRequestHandler, IMediator, Mediator
│   │   │   ├── Caching/                  # ICacheService
│   │   │   ├── Security/                 # ICurrentUser, IJwtService, IPasswordHasher
│   │   │   ├── Abstractions/             # IApplicationDbContext
│   │   │   └── Extensions/               # ResultExtensions (centralized HTTP mapping)
│   │   │
│   │   └── StackCart.BuildingBlocks.Infrastructure/
│   │       ├── Persistence/              # ApplicationDbContext, Interceptors
│   │       │   ├── Interceptors/         # AuditInterceptor, SoftDeleteInterceptor, TenantSaveChangesInterceptor
│   │       ├── Caching/                  # HybridCacheService
│   │       ├── Security/                 # CurrentUserService, JwtService
│   │       ├── Tenancy/                  # TenantContext
│   │       ├── Messaging/                # DomainEventDispatcher (stub)
│   │       └── Logging/                  # SerilogConfiguration
│   │
│   └── Modules/                          # ★ Each module is a self-contained vertical slice ★
│       │
│       ├── Tenancy/                      # Multi-tenant management
│       │   ├── StackCart.Tenancy.Domain/         # Tenant entity, TenantSlug VO
│       │   ├── StackCart.Tenancy.Application/    # CreateTenant, GetTenantBySlug
│       │   ├── StackCart.Tenancy.Infrastructure/ # TenancyDbContext, TenantConfiguration
│       │   ├── StackCart.Tenancy.Presentation/   # TenancyEndpoints
│       │   └── StackCart.Tenancy.Contracts/      # TenantSummaryDto, TenantCreatedIntegrationEvent
│       │
│       ├── Users/                        # User authentication & profile
│       │   ├── StackCart.Users.Domain/           # User entity, UserErrors, UserRegisteredDomainEvent
│       │   ├── StackCart.Users.Application/      # RegisterUser, Login, GetCurrentUser, DeactivateUser
│       │   ├── StackCart.Users.Infrastructure/   # UsersDbContext, BCryptPasswordHasher
│       │   ├── StackCart.Users.Presentation/     # UserEndpoints
│       │   └── StackCart.Users.Contracts/        # UserSummaryDto, LoginResponse
│       │
│       ├── Catalog/                      # Product & category management
│       │   ├── StackCart.Catalog.Domain/         # Product, Category, Price VO, Sku VO
│       │   ├── StackCart.Catalog.Application/    # CRUD + SearchProducts (paginated)
│       │   ├── StackCart.Catalog.Infrastructure/ # CatalogDbContext, ProductConfiguration, CategoryConfiguration
│       │   ├── StackCart.Catalog.Presentation/   # CatalogEndpoints
│       │   └── StackCart.Catalog.Contracts/      # ProductSummaryDto, CategorySummaryDto, PagedResult<T>
│       │
│       ├── Ordering/                     # Order lifecycle management
│       │   ├── StackCart.Ordering.Domain/        # Order, OrderItem, OrderStatus enum
│       │   ├── StackCart.Ordering.Application/   # CreateOrder, AddOrderItem, SubmitOrder, CancelOrder, GetOrders
│       │   ├── StackCart.Ordering.Infrastructure/# OrderingDbContext, OrderConfiguration, OrderItemConfiguration
│       │   ├── StackCart.Ordering.Presentation/  # OrderingEndpoints
│       │   └── StackCart.Ordering.Contracts/     # OrderSummaryDto, OrderSubmittedIntegrationEvent
│       │
│       └── Customer/                     # Customer profiles & shopping cart
│           ├── StackCart.Customer.Domain/        # Customer, Cart, CartItem, CustomerAddress VO
│           ├── StackCart.Customer.Application/   # CreateCustomer, UpdateCustomer, GetCustomer, Cart CRUD, Checkout
│           ├── StackCart.Customer.Infrastructure/# CustomerDbContext, CustomerConfiguration, CartConfiguration
│           ├── StackCart.Customer.Presentation/  # CustomerEndpoints
│           └── StackCart.Customer.Contracts/     # CustomerSummaryDto, CartDto
│
└── src/StackCart.Api/                    # API Host — composition root
    ├── Program.cs                        # App startup, middleware pipeline, module registration
    ├── Middleware/                        # TenantResolutionMiddleware
    ├── appsettings.json                  # Configuration (JWT, connection strings)
    └── appsettings.Development.json      # Dev overrides (Serilog console sink)

---

🚀 Getting Started

Prerequisites

• .NET 10 SDK
• PostgreSQL 18 (or Docker)
• Redis 8 (or Docker)
• MongoDB 8 (for Serilog sink — optional in dev)

1. Clone the Repository

git clone https://github.com/realAhmedAnwer/stack-cart.git
cd stack-cart

2. Configure Environment Variables

cp .env.example .env

Open .env and adjust values as needed. The defaults are configured for local development:

CONNECTIONSTRINGS__DEFAULT=Host=localhost;Port=5432;Database=stackcart;Username=postgres;Password=your_password_here
CONNECTIONSTRINGS__MONGOLOGCONNECTION=mongodb://localhost:27017/stackcart_logs
REDIS_CONNECTION=localhost:6379
JWT__SECRET=your-super-secret-key-at-least-32-characters-long
JWT__ISSUER=StackCart
JWT__AUDIENCE=StackCart
JWT__EXPIRYMINUTES=60

3. Start Dependencies (Docker)

docker run -d --name stackcart-postgres -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=your_password_here -e POSTGRES_DB=stackcart -p 5432:5432 postgres:18
docker run -d --name stackcart-redis -p 6379:6379 redis:8-alpine
docker run -d --name stackcart-mongo -p 27017:27017 mongo:8

4. Apply Database Migrations

# From the solution root, run migrations for each module:
dotnet ef database update --project src/Modules/Tenancy/StackCart.Tenancy.Infrastructure --startup-project src/StackCart.Api
dotnet ef database update --project src/Modules/Users/StackCart.Users.Infrastructure --startup-project src/StackCart.Api
dotnet ef database update --project src/Modules/Catalog/StackCart.Catalog.Infrastructure --startup-project src/StackCart.Api
dotnet ef database update --project src/Modules/Ordering/StackCart.Ordering.Infrastructure --startup-project src/StackCart.Api
dotnet ef database update --project src/Modules/Customer/StackCart.Customer.Infrastructure --startup-project src/StackCart.Api

5. Run the Application

dotnet run --project src/StackCart.Api

The API will be available at https://localhost:5001 (or http://localhost:5000).

6. Verify

curl -k https://localhost:5001/health

Open your browser and navigate to https://localhost:5001/openapi/v1.json (dev mode) to view the OpenAPI specification.

---

🏗 Architecture & Design Patterns

This project combines Clean Architecture (horizontal layer separation) with Vertical Slice Architecture (feature-based organization within the Application layer), creating a hybrid approach that maximizes both structural clarity and feature cohesion.

Clean Architecture (Layered Dependencies)

The solution enforces a strict inward dependency flow:

BuildingBlocks.Domain  (no dependencies)
        ↑
BuildingBlocks.Application
        ↑
BuildingBlocks.Infrastructure
        ↑
{Module}.Domain  →  BuildingBlocks.Domain
        ↑
{Module}.Application  →  {Module}.Domain, {Module}.Contracts, BuildingBlocks.Application
        ↑
{Module}.Infrastructure  →  {Module}.Application, {Module}.Domain, BuildingBlocks.Infrastructure
        ↑
{Module}.Presentation  →  {Module}.Application, {Module}.Contracts, BuildingBlocks.Application
        ↑
StackCart.Api  →  All module Infrastructure + Presentation, BuildingBlocks.Infrastructure

• Domain has zero external dependencies — pure entities, value objects, and enums.
• Application defines abstractions (ICustomerDbContext, ICacheService, IJwtService) and orchestrates use cases via CQRS handlers.
• Infrastructure implements abstractions and handles persistence, caching, security, and external services.
• Presentation owns Minimal API endpoints — each module registers its own routes.
• API Host composes everything at startup.

Vertical Slice Architecture (Feature-Based Organization)

Within each module's Application layer, every business feature is a self-contained vertical slice:

StackCart.Customer.Application/Features/
├── Customers/
│   ├── CreateCustomer/
│   │   ├── CreateCustomerCommand.cs     # Input record
│   │   └── CreateCustomerHandler.cs     # Handler logic
│   ├── GetCustomer/
│   │   └── GetCustomerQuery.cs          # Query + handler
│   └── UpdateCustomer/
│       └── UpdateCustomerCommand.cs     # Command + handler
└── Cart/
    ├── AddItemToCart/
    ├── RemoveItemFromCart/
    ├── UpdateCartItemQuantity/
    ├── GetCart/
    ├── ClearCart/
    └── Checkout/

Key benefits:

• Feature isolation — Adding a new feature means adding a new folder with minimal changes elsewhere.
• Layered enforceability — Clean Architecture dependency rules prevent logic leakage.
• Scalability — Slices can be developed, tested, and maintained independently.

CQRS (Command Query Responsibility Segregation)

Concern	Convention
Commands	Mutate state, call SaveChangesAsync, wrapped in implicit transactions
Queries	Read-only projections with AsNoTracking(), return DTOs
Result Pattern	All handlers return Result<T> or Result — never throw for control flow

Custom Mediator

Instead of MediatR, the project uses a custom mediator built on native DI:

• IRequest<TResponse> — marker interface for all requests (covariant).
• IRequestHandler<TRequest, TResponse> — handler contract.
• IMediator / Mediator — resolves handlers dynamically via IServiceProvider and reflection.
• AddMediator(params Assembly[]) — scans assemblies and registers handlers as scoped services.

Other Patterns

Pattern	Usage
Result Pattern	All operations return Result<T> or Result. Centralized HTTP mapping via ResultExtensions.
Soft Delete	All entities implement ISoftDeletableEntity. Global query filters exclude deleted rows.
Audit Trail	CreatedAtUtc, CreatedBy, ModifiedAtUtc, ModifiedBy auto-set via AuditInterceptor.
Multi-Tenancy	TenantId on all tenant-scoped tables. Global query filters + TenantSaveChangesInterceptor.
Repository via DbContext	No explicit repository interfaces. Data access through module-specific DbContexts.
Hybrid Caching	Redis-backed HybridCache with tenant-isolated cache keys.
Global Query Filters	EF Core filters for IsDeleted == false and TenantId == current.

---

🌐 API Endpoints

Tenancy (/api/tenants)

Method	Route	Description	Auth
POST	/api/tenants	Create a new tenant	No
GET	/api/tenants/by-slug/{slug}	Get tenant by slug	No

Users (/api/users)

Method	Route	Description	Auth
POST	/api/users/register	Register a new user	No
POST	/api/users/login	Login and receive JWT token	No
GET	/api/users/me	Get current user profile	Yes
POST	/api/users/{id}/deactivate	Deactivate a user	Yes

Catalog (/api/catalog)

Products

Method	Route	Description	Auth
POST	/api/catalog/products	Create a product	Yes
GET	/api/catalog/products/{id}	Get product by ID	Yes
GET	/api/catalog/products/by-sku/{sku}	Get product by SKU	Yes
GET	/api/catalog/products?searchTerm&categoryId&page&pageSize	Search products (paginated)	Yes
PUT	/api/catalog/products/{id}	Update a product	Yes
DELETE	/api/catalog/products/{id}	Delete a product	Yes

Categories

Method	Route	Description	Auth
POST	/api/catalog/categories	Create a category	Yes
GET	/api/catalog/categories/{id}	Get category by ID	Yes
GET	/api/catalog/categories/by-slug/{slug}	Get category by slug	Yes
GET	/api/catalog/categories	List all categories	Yes
PUT	/api/catalog/categories/{id}	Update a category	Yes
DELETE	/api/catalog/categories/{id}	Delete a category	Yes

Ordering (/api/ordering/orders)

Method	Route	Description	Auth
POST	/api/ordering/orders	Create an order	Yes
POST	/api/ordering/orders/{id}/items	Add item to order	Yes
POST	/api/ordering/orders/{id}/submit	Submit an order	Yes
GET	/api/ordering/orders?page&pageSize	List orders (paginated)	Yes
GET	/api/ordering/orders/{id}	Get order by ID	Yes
DELETE	/api/ordering/orders/{id}	Cancel an order	Yes

Customers (/api/customers)

Method	Route	Description	Auth
POST	/api/customers	Create a customer profile	Yes
GET	/api/customers/me	Get current customer profile	Yes
PUT	/api/customers/me	Update current customer profile	Yes

Cart (/api/cart)

Method	Route	Description	Auth
GET	/api/cart	Get current customer's cart	Yes
POST	/api/cart/items	Add item to cart	Yes
PUT	/api/cart/items/{productId}?quantity	Update cart item quantity	Yes
DELETE	/api/cart/items/{productId}	Remove item from cart	Yes
POST	/api/cart/checkout	Checkout (convert cart to order)	Yes
DELETE	/api/cart	Clear entire cart	Yes

---

🗄 Database Design

Multi-Tenant Strategy

• Single PostgreSQL database shared across all modules.
• Every tenant-owned table has TenantId column (Guid, FK to tenants.id).
• EF Core global query filters enforce tenant isolation at query level.
• TenantSaveChangesInterceptor auto-populates TenantId on new records.
• Every unique business key includes TenantId (composite unique constraint).

Table Layout

Table	Tenant-Scoped	Key Unique Constraint	Notes
tenants	No	slug UNIQUE	No tenant filter applied
users	Yes	(tenant_id, email)	BCrypt password hash stored
categories	Yes	(tenant_id, slug)	Self-referencing parent_category_id
products	Yes	(tenant_id, sku)	category_id FK nullable, CHECK price > 0, qty >= 0
orders	Yes	—	References user_id, status as int
order_items	Yes	—	FK to orders, products. CHECK qty > 0
customers	Yes	(tenant_id, user_id)	Links to users table
carts	Yes	(tenant_id, customer_id)	One cart per customer
cart_items	Yes	—	FK to carts, products

Indexing Strategy

All tenant-scoped indexes start with tenant_id:

• ix_users_tenant_email
• ix_products_tenant_sku
• ix_categories_tenant_slug
• ix_orders_tenant_user
• ix_customers_tenant_user
• ix_carts_tenant_customer

---

🔐 Security & Middleware

Middleware Pipeline Order

app.UseSerilogRequestLogging();
app.UseHttpsRedirection();
app.UseAuthentication();
app.UseMiddleware<TenantResolutionMiddleware>();
app.UseAuthorization();

JWT Configuration

• Secret Key — Symmetric signing key (Jwt:SecretKey)
• Issuer — Token issuer (Jwt:Issuer)
• Audience — Token audience (Jwt:Audience)
• Expiration — Configurable lifetime (Jwt:ExpirationInMinutes)
• Claims — sub (user ID), email, tenant_id, tenant_slug

Tenant Resolution

1. TenantContext reads X-Tenant-Id HTTP header from IHttpContextAccessor.
2. TenantResolutionMiddleware validates that if JWT tenant_id claim is present, it matches the X-Tenant-Id header. Returns 403 on mismatch.

Password Hashing

• Abstraction: IPasswordHasher in StackCart.BuildingBlocks.Application.Security
• Implementation: BCryptPasswordHasher in StackCart.Users.Infrastructure.Security using BCrypt.Net-Next

Global Query Filters

Applied in ApplicationDbContext.OnModelCreating:

• ISoftDeletableEntity → e.IsDeleted == false
• ITenantScoped → e.TenantId == _tenantContext.TenantId

---

📄 License

This project is licensed under the MIT License.

---

Built with ❤️ by Ahmed Anwer