Store API — E-Commerce Backend

Overview

A deliberate learning project that mirrors real production evolution.
Built as a mentored progression through 10 increasingly complex business scenarios — from simple product search to explicit transactions with savepoints — this API demonstrates how architectural decisions compound. Starting score: 3.7/10. Final architecture: 9.3/10.

This is not a tutorial follow-along. Each task was submitted, reviewed, and iterated. The codebase captures the exact journey from "controllers talking directly to the database" to a fully layered system with the Dependency Rule, Result<T> patterns, global exception handling, and automated validation.

Architecture Evolution

The project evolved in two distinct phases, both preserved in the commit history.

Phase 1 — EF Core Mastery (Tasks 01–10)

Controllers called DbContext directly while I learned how EF Core actually translates LINQ to SQL. The focus was query performance, data integrity, and understanding the ORM at the expression-tree level.

• Deferred execution with conditional IQueryable chaining

• AsNoTracking() + Select() projection for read-only endpoints (65% fewer columns over the wire vs Include())

• AsSplitQuery() to eliminate Cartesian explosion on multi-collection loads

• ExecuteUpdateAsync / ExecuteDeleteAsync for true bulk operations without loading entities

• Compiled queries (EF.CompileAsyncQuery) to skip LINQ-to-SQL translation on hot paths

• Savepoints inside explicit transactions to preserve critical work when audit trails fail

Phase 2 — Production Architecture (Direction A)

The same business logic was refactored into a layered architecture to prove the patterns transfer to real systems.

HTTP Request → Controller → IService → ServiceImpl → DbContext → Database

Dependency Rule held throughout:
Store.API → Store.Application → Store.Domain ← Store.Infrastructure

Featured Code Snippets

1. The Result<T> Pattern — Replacing Exceptions with Contracts

Services communicate failures without throwing. The controller maps to HTTP in one line.

// Store.Application/Common/Result.cs
public class Result<T>
{
    public bool IsSuccess { get; }
    public bool IsFailure => !IsSuccess;
    public T? Value { get; }
    public string Error { get; } = string.Empty;
    public int StatusCode { get; }

    private Result(bool isSuccess, T? value, string error, int statusCode)
    {
        IsSuccess = isSuccess; Value = value;
        Error = error; StatusCode = statusCode;
    }

    public static Result<T> Success(T value)
        => new(true, value, string.Empty, 200);
    public static Result<T> NotFound(string error)
        => new(false, default, error, 404);
    public static Result<T> BadRequest(string error)
        => new(false, default, error, 400);
}

// Controller — zero business logic, zero HTTP status logic
[HttpGet("{id}")]
public async Task<IActionResult> GetById([FromRoute] Guid id)
    => (await _productService.GetByIdAsync(id)).ToActionResult(this);

Why this matters: Exceptions are expensive and carry no HTTP semantics. Result<T> makes failure a first-class value that is explicit, testable, and cheap.

2. Select() Projection vs Include() — The 65% Reduction

For read scenarios, Select() fetches only the columns you name. Include() loads full entities including every column you never use.

// Version A — Include(): ~40 columns, full change-tracking overhead
var order = await _db.Orders
    .Include(o => o.Customer)
    .Include(o => o.Items).ThenInclude(i => i.Product)
    .Include(o => o.Payments)
    .FirstOrDefaultAsync(o => o.Id == id);

// Version C — Select() projection: 14 columns, zero tracking
var order = await _db.Orders
    .Where(o => o.Id == id)
    .Select(o => new
    {
        o.Id, o.OrderNumber, o.OrderDate, o.TotalAmount, o.IsPaid,
        CustomerName = o.Customer.Name,
        Items = o.Items.Select(i => new
        {
            ProductName = i.Product.Name,
            i.Quantity,
            TotalPrice = i.Quantity * i.UnitPrice // computed in SQL
        }),
        Payments = o.Payments.Select(p => new
        {
            p.Id, p.Amount, p.Method, p.ReferenceCode, p.PaidAt
        })
    })
    .AsNoTracking()
    .FirstOrDefaultAsync();

The rule I now apply in production:

• Writing data → Include() → modify entity → SaveChangesAsync()

• Reading data → Select() projection → AsNoTracking() → never Include()

3. Explicit Transactions with Savepoints — Protecting Critical Work

When confirming an order, stock reduction is critical. Audit trail creation is recoverable. A savepoint preserves the critical work if the audit fails.

await using var transaction = await _db.Database.BeginTransactionAsync();

// Step 1 — confirm order
order.Status = OrderStatus.Confirmed;
await _db.SaveChangesAsync();

// Step 2 — reduce stock
foreach (var item in order.Items)
    item.Product.StockQuantity -= item.Quantity;
await _db.SaveChangesAsync();

// Savepoint: order + stock are now safe
await transaction.CreateSavepointAsync("StockReduced");

// Step 3 — audit trail (non-critical)
try
{
    await _db.StockMovements.AddRangeAsync(movements);
    await _db.SaveChangesAsync();
    await transaction.CommitAsync();
}
catch
{
    // Roll back only the audit. Order and stock remain committed.
    await transaction.RollbackToSavepointAsync("StockReduced");
    await transaction.CommitAsync();
}

Why this matters: In high-throughput systems, failing an entire transaction because an audit log insert failed is unacceptable. Savepoints let you define which operations are essential and which are best-effort.

4. Bulk Operations — ExecuteUpdateAsync Without Loading Entities

Applying a discount across an entire category in a single SQL statement. No entities loaded. No SaveChanges. No change tracker.

[HttpPatch("apply-discount/{categoryId}")]
public async Task<IActionResult> ApplyDiscount(
    [FromRoute] Guid categoryId,
    [FromBody] decimal percentage)
{
    decimal discount = percentage / 100;

    int affected = await _db.Products
        .Where(p => p.CategoryId == categoryId && p.IsActive)
        .ExecuteUpdateAsync(s => s.SetProperty(
            p => p.Price,
            p => p.Price * (1 - discount))); // formula pushed into SQL

    return Ok(new { NumberOfRowsAffected = affected });
}

The trap I learned to avoid: Pre-computing decimal newPrice = product.Price * 0.9 in C# forces EF to generate one UPDATE per row. Referencing the column inside the lambda (p.Price * (1 - discount)) generates a single bulk UPDATE with SQL arithmetic.

5. FluentValidation — Validation as Infrastructure, Not Code

Validation rules live in dedicated classes and run automatically before the controller action is ever invoked.

public class ProductSearchRequestValidator : AbstractValidator<ProductSearchRequest>
{
    public ProductSearchRequestValidator()
    {
        RuleFor(r => r.Page).GreaterThanOrEqualTo(1);
        RuleFor(r => r.PageSize).LessThanOrEqualTo(50);

        RuleFor(r => r.MaxPrice)
            .GreaterThanOrEqualTo(r => r.MinPrice!.Value)
            .When(r => r.MaxPrice.HasValue && r.MinPrice.HasValue);
    }
}

Impact: Services no longer contain defensive if checks against malformed input. The boundary is enforced at the edge, keeping business logic clean and focused.

Key Metrics & Growth

Total progression: 3.7 → consistent 9.0+ across all new tasks.

What I Would Do Next

This project established the foundation. The next iteration would add:

• Unit & integration test suite (xUnit + Moq + FluentAssertions) — roadmap already planned

• Soft-delete safety audit on ExecuteDeleteAsync to prevent accidental hard deletes

• CQRS split — separate read models with Dapper for report-heavy endpoints

• Redis caching on compiled query results for hot product/catalog data