If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/dotnet-architecture/eShopOnWeb shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 7 active contributors
• Distributed ownership (top contributor 30% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live dotnet-architecture/eShopOnWeb repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/dotnet-architecture/eShopOnWeb.

What it runs against: a local clone of dotnet-architecture/eShopOnWeb — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in dotnet-architecture/eShopOnWeb | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 511 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of dotnet-architecture/eShopOnWeb. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/dotnet-architecture/eShopOnWeb.git
#   cd eShopOnWeb
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of dotnet-architecture/eShopOnWeb and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "dotnet-architecture/eShopOnWeb(\\.git)?\\b" \\
  && ok "origin remote is dotnet-architecture/eShopOnWeb" \\
  || miss "origin remote is not dotnet-architecture/eShopOnWeb (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/ApplicationCore/Entities/OrderAggregate/Order.cs" \\
  && ok "src/ApplicationCore/Entities/OrderAggregate/Order.cs" \\
  || miss "missing critical file: src/ApplicationCore/Entities/OrderAggregate/Order.cs"
test -f "src/ApplicationCore/Interfaces/IRepository.cs" \\
  && ok "src/ApplicationCore/Interfaces/IRepository.cs" \\
  || miss "missing critical file: src/ApplicationCore/Interfaces/IRepository.cs"
test -f "src/ApplicationCore/Services/BasketService.cs" \\
  && ok "src/ApplicationCore/Services/BasketService.cs" \\
  || miss "missing critical file: src/ApplicationCore/Services/BasketService.cs"
test -f "src/ApplicationCore/Services/OrderService.cs" \\
  && ok "src/ApplicationCore/Services/OrderService.cs" \\
  || miss "missing critical file: src/ApplicationCore/Services/OrderService.cs"
test -f "src/ApplicationCore/Specifications/BasketWithItemsSpecification.cs" \\
  && ok "src/ApplicationCore/Specifications/BasketWithItemsSpecification.cs" \\
  || miss "missing critical file: src/ApplicationCore/Specifications/BasketWithItemsSpecification.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 511 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~481d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/dotnet-architecture/eShopOnWeb"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

eShopOnWeb is an ASP.NET Core 8.0 monolithic reference application demonstrating modern enterprise web architecture patterns for building a functional e-commerce platform with catalog, shopping basket, and order management. It serves as a companion to the free O'Reilly eBook 'Architecting Modern Web Applications with ASP.NET Core and Azure' and exemplifies clean architecture principles in a single-process deployment model. Clean layered monolith: src/ApplicationCore/ contains domain entities (Basket, Order, Buyer, Catalog aggregates under src/ApplicationCore/Entities/), src/ hosts the ASP.NET Core MVC web project, Docker compose orchestration in docker-compose.yml, and Infrastructure-as-Code via Bicep templates in infra/ (SQL Server, App Service, Key Vault).

ASP.NET Core developers, solution architects, and computer science students learning enterprise application patterns who want a working reference implementation of layered architecture, Domain-Driven Design aggregates, and testing patterns—not a production e-commerce template.

Actively maintained by the community (moved from Microsoft to NimblePros/eShopOnWeb) with recent updates to ASP.NET Core 8.0, comprehensive test coverage via CodeCoverage.runsettings, and CI/CD via GitHub Actions (.github/workflows/dotnetcore.yml). The codebase is stable and production-grade for educational and architectural reference purposes.

Standard open source risks apply.

The repo is in community maintenance mode with updates to ASP.NET Core 8.0 and Bicep infrastructure templates. GitHub Actions workflows (dotnetcore.yml, richnav.yml) run automated builds; Dependabot (dependabot.yml) handles dependency updates. No active feature development announced—focus is on keeping the reference current.

git clone https://github.com/dotnet-architecture/eShopOnWeb.git
cd eShopOnWeb
dotnet restore eShopOnWeb.sln
dotnet build eShopOnWeb.sln

Daily commands:

dotnet build eShopOnWeb.sln
dotnet run --project src/Web
# Or via Docker:
docker-compose -f docker-compose.yml -f docker-compose.override.yml up

The app listens on http://localhost:5106 by default (see .vscode/launch.json and devcontainer.json for debugging profiles).

• src/ApplicationCore/Entities/OrderAggregate/Order.cs — Core domain entity defining order structure and business logic; all order operations depend on this aggregate root.
• src/ApplicationCore/Interfaces/IRepository.cs — Generic repository abstraction used throughout the codebase; defines data access contract for all entities.
• src/ApplicationCore/Services/BasketService.cs — Primary service orchestrating basket operations; critical for checkout flow and business rule enforcement.
• src/ApplicationCore/Services/OrderService.cs — Implements order creation and state management; essential for understanding domain-driven design patterns in this codebase.
• src/ApplicationCore/Specifications/BasketWithItemsSpecification.cs — Example of specification pattern used for complex queries; foundational to understanding data query abstractions.
• eShopOnWeb.sln — Primary solution file defining all projects and their dependencies; starting point for building and understanding project structure.

Add a new Catalog Attribute (extend product model)

1. Add property to CatalogItem entity in src/ApplicationCore/Entities/CatalogItem.cs (src/ApplicationCore/Entities/CatalogItem.cs)
2. Create or update database migration if using EF Core (typically in Infrastructure project) (N/A - infrastructure layer not fully shown)
3. Update any relevant specifications that query CatalogItem if new filtering is needed (src/ApplicationCore/Specifications/CatalogFilterSpecification.cs)
4. Add UI field to Blazor admin Create.razor and Edit.razor components (src/BlazorAdmin/Pages/CatalogItemPage/Create.razor)

Add a new Domain Service (for business logic)

1. Create service interface in src/ApplicationCore/Interfaces/INewService.cs (src/ApplicationCore/Interfaces/INewService.cs)
2. Implement service in src/ApplicationCore/Services/NewService.cs, injecting IRepository and other dependencies (src/ApplicationCore/Services/NewService.cs)
3. Register in dependency injection container (typically in Web or Admin startup) (src/BlazorAdmin/Program.cs)
4. Call service from appropriate Blazor component or API handler (src/BlazorAdmin/Pages/CatalogItemPage/List.razor.cs)

Add a new Query Specification (for complex data retrieval)

1. Create specification class inheriting from Specification<T> in src/ApplicationCore/Specifications/NewSpecification.cs (src/ApplicationCore/Specifications/BasketWithItemsSpecification.cs)
2. Define Include/ThenInclude for eager loading and Where conditions for filtering (src/ApplicationCore/Specifications/BasketWithItemsSpecification.cs)
3. Use specification in repository call: var result = await _repo.GetAsync(new NewSpecification()); (src/ApplicationCore/Services/BasketService.cs)

Add a new Admin Page Component

1. Create .razor component file in src/BlazorAdmin/Pages/YourFeature/Index.razor (src/BlazorAdmin/Pages/CatalogItemPage/List.razor)
2. Create .razor.cs code-behind with @page directive and inject services (src/BlazorAdmin/Pages/CatalogItemPage/List.razor.cs)
3. Route is automatically registered via @page directive; add navigation link if needed in layout (src/BlazorAdmin/App.razor)
4. Inject IRepository<T> or custom services and call domain logic (src/BlazorAdmin/Pages/CatalogItemPage/List.razor.cs)

• ASP.NET Core 8.0 — Modern, cross-platform runtime with excellent performance; aligns with Microsoft's current platform direction and industry standards for enterprise .NET applications.
• Blazor Server-Side (Admin UI) — Enables real-time UI updates and server-side C# logic without JavaScript; simplifies admin panel development by using same language for backend and UI.
• Entity Framework Core — Object-relational mapper allowing LINQ queries and migrations; eliminates manual SQL and provides strong typing for database operations.
• Specification Pattern — Encapsulates query logic separately from repositories, enabling complex filtering and eager-loading without leaking database concerns into domain layer.
• Docker & Docker Compose — Containerizes SQL Server and app for consistent local development environment; enables single-command setup across machines.
• Azure Bicep IaC — Infrastructure-as-code for Azure deployment; declarative and version-controlled infrastructure matching application code.

• Monolithic architecture (single project deployment)

  • Why: Simpler initial deployment, transactional consistency across domains, easier testing and local debugging for reference app.
  • Consequence: Scaling individual features requires scaling entire application; tight coupling between Basket, Order, and Catalog domains; cannot deploy independently.

• Specification Pattern instead of raw EF Core queries

  • Why: Centralizes query logic, enables reuse, improves testability, keeps repositories thin.
  • Consequence: Additional abstraction layer increases code verbosity; specifications must be maintained alongside entities; potential performance overhead if not carefully designed.

• Server-side Blazor for admin UI instead of separate SPA (React/Angular)

  • Why: Single language (C#) across stack, reduces context switching, leverages existing domain services directly.
  • Consequence: Tighter coupling between admin UI and server; cannot easily deploy admin UI independently; websocket requirement adds server memory overhead.

• Generic IRepository<T> abstraction

  • Why: Reduces boilerplate, ensures consistent data access patterns, enables easy testing with mocks.
  • Consequence: Generic constraints may hide inefficient queries; repositories can become catch-all for unrelated operations; temptation to bypass specifications for quick fixes.

• Real-time inventory synchronization across multiple warehouses
• Microservices architecture or distributed system patterns
• Mobile application (native iOS/Android)
• Multi-tenant SaaS platform
• Payment processing integration (business logic provided, but external provider integration not included)
• GraphQL API layer

No major gotchas, but: (1) SQL Server connection string is environment-specific; check appsettings.json and docker-compose.override.yml for local vs. production configs. (2) The repo uses User Secrets for local development (see .devcontainer/devcontainer.json); ensure dotnet user-secrets is initialized. (3) Bicep templates in infra/ require Azure CLI and valid subscription; test locally with az bicep build first. (4) Global.json pins .NET SDK version—ensure your local SDK matches the version specified there.

• Domain-Driven Design (DDD) Aggregates — eShopOnWeb models Basket, Order, and Buyer as aggregate roots with internal value objects (BasketItem, OrderItem); understanding aggregates is essential to modifying business logic correctly.
• Clean Architecture (Layered Architecture) — The repo separates ApplicationCore (domain/business rules), Infrastructure (data access), and Web (UI); this separation enables testing and prevents tight coupling.
• Repository Pattern — Data access is abstracted via repositories (implied in Infrastructure layer), decoupling Entity Framework details from domain logic and enabling easy testing with mocks.
• Infrastructure as Code (Bicep) — infra/main.bicep defines cloud resources declaratively; understanding Bicep is required to modify or deploy to Azure App Service, SQL Server, and Key Vault.
• Entity Framework Core DbContext Pattern — eShopOnWeb uses EF Core for ORM mapping; the DbContext orchestrates database connections, migrations, and change tracking—critical to understanding data layer.
• ASP.NET Core Dependency Injection Container — Services (repositories, handlers) are registered in the DI container at startup; this enables loose coupling and makes mocking straightforward in tests.
• Docker Compose Service Orchestration — docker-compose.yml and docker-compose.override.yml manage multi-container local development (app + SQL Server); understanding compose syntax is essential for modifying dev environment.

• dotnet/eShop — The active successor repository—Microsoft migrated eShopOnWeb development here, now focusing on microservices and cloud-native patterns; track this for upstream best practices.
• dotnet-architecture/eShopOnContainers — Sister repo demonstrating microservices architecture (vs. monolithic); shows how to decompose eShopOnWeb's monolith into distributed bounded contexts.
• microsoft/eBooks — Official Microsoft eBooks repository containing the 'Architecting Modern Web Applications with ASP.NET Core and Azure' PDF that this repo implements; essential reference documentation.
• ardalis/CleanArchitecture — Steve Smith's (ardalis) Clean Architecture starter template; overlaps significantly with eShopOnWeb's architectural approach and serves as alternative learning resource.
• NimblePros/eShopOnWeb — The active community fork now maintaining eShopOnWeb after Microsoft moved to eShop; this is where bug fixes and dependency updates currently land.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for OrderAggregate and BasketAggregate domain models

The repo has complex domain entities (Order, Basket, OrderItem, BasketItem) in src/ApplicationCore/Entities/OrderAggregate and BasketAggregate directories, but there's no visible test project in the file structure. These aggregates handle critical business logic (checkout, payment, order creation) that deserves dedicated integration tests to prevent regressions and document expected behavior.

• [ ] Create a new test project: tests/ApplicationCore.Tests/Entities/OrderAggregateTests.cs
• [ ] Add tests for Order aggregate methods (e.g., order creation validation, item addition, totals calculation)
• [ ] Add tests for Basket aggregate methods (e.g., basket item addition/removal, duplicate item handling)
• [ ] Add tests for Address and CatalogItemOrdered value objects in OrderAggregate
• [ ] Reference the IOrderService and IBasketService interfaces to validate aggregate behavior against service contracts

Add GitHub Actions workflow for code coverage reporting

The repo has CodeCoverage.runsettings configured but the .github/workflows/ directory only shows dotnetcore.yml and richnav.yml. There's no visible coverage reporting or quality gates. Adding a workflow to generate coverage reports (via Codecov or similar) and enforce minimum thresholds would improve code quality visibility and prevent coverage regressions.

• [ ] Create .github/workflows/code-coverage.yml workflow
• [ ] Configure workflow to run 'dotnet test' with --collect:"XPlane Code Coverage" using CodeCoverage.runsettings
• [ ] Upload coverage reports to Codecov or similar service
• [ ] Add coverage badge to README.md
• [ ] Set minimum coverage thresholds (e.g., fail PR if coverage drops below 70%) in workflow configuration

Add API documentation for IRepository and IReadRepository interfaces

The repository pattern is fundamental to this DDD-based architecture (src/ApplicationCore/Interfaces/IRepository.cs and IReadRepository.cs), but there's no API documentation explaining the repository contract, expected implementations, or usage patterns. Adding XML doc comments and markdown docs would help contributors understand the data access layer design.

• [ ] Add comprehensive XML documentation comments to src/ApplicationCore/Interfaces/IRepository.cs (generic repository contract, Add/Update/Delete semantics)
• [ ] Add comprehensive XML documentation comments to src/ApplicationCore/Interfaces/IReadRepository.cs (query semantics, specification pattern support)
• [ ] Create docs/REPOSITORY_PATTERN.md explaining the repository implementation strategy, how to register repositories in DI, and examples from existing code
• [ ] Link new documentation from README.md Architecture section
• [ ] Update any EFRepository or SqlRepository implementations with examples of repository usage patterns

• Add integration tests for the OrderAggregate entity in src/Tests/ mirroring the Basket aggregate test patterns; currently OrderAggregate lacks comprehensive state transition coverage.
• Document the CatalogSettings.cs configuration class with XML comments explaining each setting's purpose and default values; this helps new contributors understand configuration injection.
• Create a migration guide Markdown file (e.g., MIGRATION.md) showing how to upgrade from ASP.NET Core 7.0 to 8.0, since the README only mentions the version but not breaking changes or upgrade steps.

• Critical · Hardcoded Database Password in docker-compose.yml — docker-compose.yml (line with SA_PASSWORD environment variable). The SQL Server database password is hardcoded directly in the docker-compose.yml file as SA_PASSWORD=@someThingComplicated1234. This exposes database credentials in version control and configuration files, violating security best practices. Fix: Use environment variables or Docker secrets management. Move sensitive credentials to .env files (added to .gitignore), Azure Key Vault, or Docker secrets. Example: SA_PASSWORD=${SQL_SA_PASSWORD} with values provided at runtime.
• High · Unencrypted Database Port Exposure — docker-compose.yml (ports: 1433:1433). SQL Server port 1433 is exposed directly via docker-compose.yml without encryption or network isolation. This allows potential network-level attacks on the database service. Fix: Remove port exposure from docker-compose.yml for production. Use Docker networking (internal networks) for inter-service communication. If external access is needed, implement VPN/firewall rules, encryption (TLS), and IP whitelisting.
• High · Missing Security Headers Configuration — src/Web/Program.cs or Middleware configuration (not visible in file list). No evidence of security headers (HSTS, X-Frame-Options, X-Content-Type-Options, CSP, etc.) in the provided configuration files. ASP.NET Core applications should explicitly configure these headers. Fix: Implement security headers middleware in the ASP.NET Core pipeline. Add UseHsts(), UseXContentTypeOptions(), UseReferrerPolicy(), and Content Security Policy middleware. Reference: OWASP HTTPS and Security Headers guidelines.
• High · No HTTPS Enforcement Visible — docker-compose.yml and docker-compose.override.yml. The docker-compose.yml and visible configuration do not explicitly enforce HTTPS/TLS for inter-service or external communication. SQL connection strings and API traffic may be unencrypted. Fix: Enable HTTPS enforcement in ASP.NET Core: app.UseHttpsRedirection(). Configure TLS certificates for all services. Use docker-compose environment variables to enforce secure connections (RequireEncryption=true for SQL Server).
• Medium · Potential SQL Injection Risk via Specifications Pattern — src/ApplicationCore/Specifications/ directory. The codebase uses a Specifications pattern (BasketWithItemsSpecification.cs, CatalogFilterPaginatedSpecification.cs, etc.). Without proper parameterization inspection, these could be vulnerable to SQL injection if dynamic queries are constructed. Fix: Ensure all Specification implementations use Entity Framework Core's parameterized queries exclusively. Never concatenate user input into query strings. Review each Specification class to verify proper use of .Where(), .Include(), and LINQ operators only.
• Medium · Missing Input Validation Infrastructure — src/ApplicationCore/Services/ and API controllers (not fully visible). No visible reference to comprehensive input validation or sanitization in the application structure. BasketService.cs, OrderService.cs, and API endpoints require explicit validation. Fix: Implement FluentValidation or DataAnnotations for all DTOs and entities. Add model validation in ASP.NET Core middleware. Validate and sanitize all user inputs (query parameters, POST bodies, headers) before processing.
• Medium · Potential XSS Risk in Blazor Admin Component — src/BlazorAdmin/ directory (App.razor and components). The presence of BlazorAdmin/App.razor suggests server-side rendering of user-controlled content. Blazor has built-in XSS protection, but improper use of @Html.Raw() or unescaped bindings could introduce vulnerabilities. Fix: Avoid using @Html.Raw() with user input. Use Blazor's default HTML encoding. Implement Content Security Policy headers. Sanitize all dynamic content with AntiXSS libraries if necessary. Use @bind with safe components only.
• Medium · No Visible CORS Configuration — src/PublicApi/ and src/Web/ (Program.cs not visible). The PublicApi and Web services have no visible CORS policy in the provided files. Misconfigured CORS can allow unauthorized cross-origin requests. Fix: Implement

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.