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/simplcommerce/SimplCommerce 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 the board

• Last commit 3w ago
• 26+ active contributors
• Distributed ownership (top contributor 34% of recent commits)
• Apache-2.0 licensed
• CI configured
• ⚠ No test directory detected

_{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 simplcommerce/SimplCommerce repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/simplcommerce/SimplCommerce.

What it runs against: a local clone of simplcommerce/SimplCommerce — 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 simplcommerce/SimplCommerce | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 51 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of simplcommerce/SimplCommerce. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/simplcommerce/SimplCommerce.git
#   cd SimplCommerce
#
# 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 simplcommerce/SimplCommerce and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "SimplCommerce.sln" \\
  && ok "SimplCommerce.sln" \\
  || miss "missing critical file: SimplCommerce.sln"
test -f "src/Modules/Directory.Build.props" \\
  && ok "src/Modules/Directory.Build.props" \\
  || miss "missing critical file: src/Modules/Directory.Build.props"
test -f "build/SimplCommerce.MSBuildTasks/CopyModuleTask.cs" \\
  && ok "build/SimplCommerce.MSBuildTasks/CopyModuleTask.cs" \\
  || miss "missing critical file: build/SimplCommerce.MSBuildTasks/CopyModuleTask.cs"
test -f "src/Modules/SimplCommerce.Module.ActivityLog/ModuleInitializer.cs" \\
  && ok "src/Modules/SimplCommerce.Module.ActivityLog/ModuleInitializer.cs" \\
  || miss "missing critical file: src/Modules/SimplCommerce.Module.ActivityLog/ModuleInitializer.cs"
test -f "azure-pipelines.yml" \\
  && ok "azure-pipelines.yml" \\
  || miss "missing critical file: azure-pipelines.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 51 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~21d)"
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/simplcommerce/SimplCommerce"
  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).

SimplCommerce is a cross-platform, modular ecommerce system built on .NET 8 and ASP.NET Core that runs on Windows, Mac, and Linux with SQL Server or PostgreSQL backends. It implements a modulith architecture—a single codebase split into feature modules (Catalog, Cart, Orders, WishList, etc.) that share a core data layer—allowing teams to develop ecommerce features independently while deploying as one application. Modulith monolith: src/Database contains shared EF Core migrations; src/ holds feature modules (SimplCommerce.Module.Catalog, SimplCommerce.Module.Orders, etc.) each with Controllers/, Services/, and Models/ folders; SimplCommerce.WebHost is the entry point; build/SimplCommerce.MSBuildTasks handles module assembly at compile time via CopyModuleTask.cs.

.NET backend developers and full-stack engineers building or extending ecommerce platforms who want a production-ready, self-hosted alternative to Shopify or WooCommerce. Also appeals to organizations needing a white-label storefront with customizable admin panels and extensible module architecture.

Production-ready and actively maintained: the repo demonstrates mature CI/CD (Azure Pipelines, Travis CI, GitHub Actions CodeQL), comprehensive test coverage (see SimplCommerce.Module.WishList.Tests.Controllers), and documented deployment to AWS Elastic Beanstalk and Docker. Recent commits and passing builds indicate active development; online demo at demo.simplcommerce.com shows stability.

Low-to-medium risk: single maintainer organization (simplcommerce GitHub org) and no visible recent breaking-change changelog increase upgrade friction. Dependency surface is large (1.6M lines C#, JavaScript frontend, SQL T-SQL—three separate tech stacks to maintain), but modular structure isolates impact. No visible open-issue backlog metrics in provided data.

Active development on .NET 8 migration (visible in global.json and README targeting .NET 8). Testing framework modernization in progress (GlobalUsings.cs pattern in test projects). CI/CD pipeline maintained across Azure, Travis, and GitHub Actions with CodeQL security scanning enabled.

git clone https://github.com/simplcommerce/SimplCommerce.git && cd SimplCommerce && dotnet build && dotnet ef database update (after setting DefaultConnection in src/SimplCommerce.WebHost/appsettings.json)

Daily commands: Windows/LocalDB: Update appsettings.json connection string → dotnet build → Open Package Manager Console, set Default Project to SimplCommerce.WebHost → Update-Database → dotnet run. Mac/Linux: Same, but use PostgreSQL and ensure .NET 8 SDK installed. Docker: docker run -p 5000:80 simplcommerce/ci-build. Admin login: admin@simplcommerce.com / 1qazZAQ!

• SimplCommerce.sln — Root solution file that orchestrates all modules and the main application; required entry point for building the entire system.
• src/Modules/Directory.Build.props — Centralized MSBuild properties for all modules; controls compilation, versioning, and module-level dependencies across the codebase.
• build/SimplCommerce.MSBuildTasks/CopyModuleTask.cs — Custom MSBuild task that handles modular architecture assembly—copies and registers modules into the main application at build time.
• src/Modules/SimplCommerce.Module.ActivityLog/ModuleInitializer.cs — Exemplar module initializer pattern; demonstrates how each module registers services, routes, and event handlers on application startup.
• azure-pipelines.yml — CI/CD pipeline configuration for the entire system; orchestrates build, test, and deployment across all platforms.
• global.json — Specifies .NET SDK version and solution-wide language features; ensures consistent build environment across all contributors.

Add a New Feature Module

1. Create a new folder under src/Modules/ named SimplCommerce.Module.YourFeature with .csproj referencing the module framework. (src/Modules/SimplCommerce.Module.ActivityLog/SimplCommerce.Module.ActivityLog.csproj)
2. Create ModuleInitializer.cs in your module root; add ConfigureServices() to register EF Core DbContext and dependency injection. (src/Modules/SimplCommerce.Module.ActivityLog/ModuleInitializer.cs)
3. Create domain models in Models/ and EF Core configuration in Data/; inherit from BaseEntity and use CustomModelBuilder pattern. (src/Modules/SimplCommerce.Module.ActivityLog/Models/Activity.cs)
4. Create API controllers in Areas/YourFeature/Controllers/ extending ControllerBase; use Area routing and DI for repositories. (src/Modules/SimplCommerce.Module.Catalog/Areas/Catalog/Controllers/BrandApiController.cs)
5. Create module.json manifest in the root declaring module name, version, and required dependencies. (src/Modules/SimplCommerce.Module.ActivityLog/module.json)
6. Reference your module in SimplCommerce.sln and ensure CopyModuleTask copies it to wwwroot/modules on build. (build/SimplCommerce.MSBuildTasks/CopyModuleTask.cs)

Add a New API Endpoint to a Module

1. Create a new API controller in Areas/ModuleName/Controllers/ named XyzApiController, inheriting from ControllerBase with [ApiController] and [Area("ModuleName")] attributes. (src/Modules/SimplCommerce.Module.Catalog/Areas/Catalog/Controllers/BrandApiController.cs)
2. Inject the repository and any required services via constructor dependency injection. (src/Modules/SimplCommerce.Module.ActivityLog/Data/ActivityRepository.cs)
3. Define public async action methods with proper HTTP verbs (GET, POST, PUT, DELETE) and return appropriate status codes (200 Ok, 201 Created, 404 NotFound). (src/Modules/SimplCommerce.Module.Catalog/Areas/Catalog/Controllers/BrandApiController.cs)
4. Register the API in a AngularJS service under wwwroot/admin/ (e.g., xyz-service.js) to enable admin panel integration. (src/Modules/SimplCommerce.Module.ActivityLog/wwwroot/admin/activitylog-service.js)

Add a New View Component for the Storefront

1. Create a new class in Areas/ModuleName/Components/ named XyzViewComponent, inheriting from ViewComponent with public IViewComponentResult Invoke() method. (src/Modules/SimplCommerce.Module.Catalog/Areas/Catalog/Components/CategoryMenuViewComponent.cs)
2. Create a corresponding .cshtml partial view in Areas/ModuleName/Components/Xyz/ named Default.cshtml. (src/Modules/SimplCommerce.Module.Catalog/Areas/Catalog/Components/CategoryBreadcrumbViewComponent.cs)
3. Inject repository and render data; return View() with a ViewModel. (src/Modules/SimplCommerce.Module.Catalog/Areas/Catalog/Components/ProductWidgetViewComponent.cs)
4. Invoke the component in layout files using @await Component.InvokeAsync("Xyz") syntax. (src/Modules/SimplCommerce.Module.Catalog/Areas/Catalog/Components/CategoryWidgetViewComponent.cs)

Handle Domain Events Between Modules

1. Define a domain event class (e.g., ProductViewedEvent) in the publishing module's Events/ folder. (src/Modules/SimplCommerce.Module.ActivityLog/Events/EntityViewedHandler.cs)
2. Create an event handler class implementing INotificationHandler<YourEvent> in the subscribing module's Events/ folder. (src/Modules/SimplCommerce.Module.ActivityLog/Events/EntityViewedHandler.cs)
3. Register the handler in ModuleInitializer.cs using services.AddScoped(typeof(INotificationHandler<>), handlerType). (src/Modules/SimplCommerce.Module.ActivityLog/ModuleInitializer.cs)
4. Dispatch the event from domain aggregates using MediatR's Publish(); the framework will invoke all registered handlers asynchronously. (src/Modules/SimplCommerce.Module.ActivityLog/Events/EntityViewedHandler.cs)

• .NET / ASP.NET Core — Cross-platform, high-performance server framework; unified C# codebase for backend and strong typing.
• Entity Framework Core — ORM for multi-database support (SQL Server, MySQL, SQLite); module-level DbContext composition enables loose coupling.
• MediatR —

1. Connection string must exist before Update-Database—the script won't create the database automatically; you must pre-create SimplCommerce DB in SQL Server. 2) Module discovery is compile-time via CopyModuleTask; adding a new module .csproj requires Solution reload + Clean + Rebuild, not just dotnet build. 3) LocalDB connection string requires MultipleActiveResultSets=true and TrustServerCertificate=true on Windows; omitting these causes concurrent-request failures. 4) Docker image uses relative paths for migrations; running migrations inside container requires proper working directory setup in docker-entrypoint.sh. 5) SQL Server login mode (Trusted_Connection=True) only works on Windows domain-joined machines; non-Windows requires SQL auth (User Id=sa;Password=...).

• Modulith (Monolith + Modules) — SimplCommerce's core design pattern: single codebase deployed as one app, but split into independently-developed feature modules to avoid monolith coupling hell while keeping deployment overhead low
• Entity Framework Core Code-First Migrations — All database schema changes (src/Database/Migrations/) are versioned as C# code, allowing rollback, branching, and multi-environment consistency without hand-written SQL
• Custom MSBuild Tasks — SimplCommerce.MSBuildTasks/CopyModuleTask.cs runs at compile-time to auto-discover and wire up modules; understanding this is critical to extending the architecture
• Dependency Injection (ASP.NET Core built-in) — All module services and controllers use constructor injection via IServiceCollection; no external DI container, reducing complexity but requiring careful Startup.cs registration
• Multi-database support (SQL Server, PostgreSQL, SQLite) — SimplCommerce abstracts database provider via EF Core DbContext; migrations work across all three, but provider-specific SQL (T-SQL in StaticData-RO.sql) requires parallel maintenance
• Docker multi-stage builds — Dockerfile uses separate build and runtime stages to minimize image size; understanding this is needed for production deployments and CI/CD optimization
• Azure Pipelines YAML CI/CD — azure-pipelines.yml orchestrates builds, tests, and Docker image pushes; modifying deployment flows requires editing this file, not UI configuration

• NopCommerce/nopCommerce — Competing .NET ecommerce platform with plugins instead of modules; shares similar architecture goals but tighter coupling
• smartstore/SmartStore — German-origin .NET ecommerce fork; modular plugin system; more mature but less actively maintained than SimplCommerce
• dotnet/aspnetcore — Upstream dependency; SimplCommerce tracks ASP.NET Core LTS versions and uses newer DI/middleware patterns
• dotnet/efcore — Database ORM dependency; all migrations and schema versioning relies on EF Core's change-tracking and Sql generation
• docker/docker-ce — Deployment target; Dockerfile and docker-entrypoint.sh are critical for cloud deployments; base image stability impacts release cycle

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 comprehensive unit tests for SimplCommerce.MSBuildTasks

The build/SimplCommerce.MSBuildTasks project contains critical custom MSBuild tasks (CopyModuleTask.cs, ModuleManifest.cs) that handle module discovery and copying in this modulith architecture, but there are no corresponding test files visible in the repo. These custom build tasks are fundamental to the modular architecture working correctly, yet they lack test coverage. This is high-risk code that should have unit tests.

• [ ] Create build/SimplCommerce.MSBuildTasks.Tests/SimplCommerce.MSBuildTasks.Tests.csproj with xUnit or NUnit
• [ ] Add tests for CopyModuleTask.cs covering module discovery, validation, and file copying scenarios
• [ ] Add tests for ModuleManifest.cs covering manifest parsing and module metadata extraction
• [ ] Integrate the new test project into run-tests.sh and run-tests.ps1 scripts
• [ ] Add test execution step to azure-pipelines.yml for build validation

Add CodeQL and SAST scanning GitHub Actions workflow

The repo has a codeql-analysis.yml workflow stub (.github/workflows/codeql-analysis.yml) but based on the file listing, it appears incomplete or not properly configured. Given this is an ecommerce system handling sensitive data (payments, user info), automated security scanning is critical. The repo should have mature SAST/DAST workflows configured in CI/CD.

• [ ] Review and complete .github/workflows/codeql-analysis.yml with proper C# scanning configuration
• [ ] Add a new workflow file .github/workflows/dotnet-security-scan.yml for additional SAST tools (Semgrep, Snyk, or similar)
• [ ] Configure the workflow to run on pull_request and push to master
• [ ] Add security scan results as required checks in branch protection rules documentation
• [ ] Update SECURITY.md with information about security scanning and vulnerability disclosure process

Add integration tests for module loading and inter-module communication

The SimplCommerce.Module.WishList.Tests.Controllers directory shows unit tests exist for individual modules, but there are no visible integration tests verifying that the modulith architecture works correctly—that modules load in correct order, dependencies are resolved, and inter-module communication functions. Given this is the core architectural pattern, integration tests validating module initialization and communication are critical.

• [ ] Create src/Tests/SimplCommerce.Integration.Tests/SimplCommerce.Integration.Tests.csproj
• [ ] Add ModuleLoadingIntegrationTests.cs verifying all modules in src/Modules can be discovered and loaded correctly
• [ ] Add ModuleDependencyResolutionTests.cs validating dependency injection container resolves cross-module dependencies
• [ ] Add end-to-end tests for a complete request flow through multiple modules (e.g., Product → Cart → Wishlist)
• [ ] Integrate into run-tests.sh and azure-pipelines.yml and ensure they run on every PR

• Add unit tests to SimplCommerce.Module.{CatalogOrders}/Controllers/ mirroring the existing SimplCommerce.Module.WishList.Tests.Controllers pattern—currently many controllers lack test coverage
• Document the module creation workflow: write a MODULES.md guide explaining folder structure, migration registration, and DI setup with a concrete example (e.g., 'Creating SimplCommerce.Module.Reviews from scratch')
• Standardize logging: add ILogger dependency injection to all service classes that currently use Console.WriteLine or no logging—start with src/SimplCommerce.Infrastructure/ services

• Critical · Incomplete Docker Build Command — Dockerfile, line: dotnet ef migrations scrip. The Dockerfile contains an incomplete dotnet ef migrations scrip command (missing 't' at the end). This will cause the build to fail silently or produce incomplete migrations, potentially leaving the database in an inconsistent state. This is a critical infrastructure issue that could compromise data integrity. Fix: Complete the command to dotnet ef migrations script or the intended command. Ensure all build steps are validated and tested before deployment.
• High · Insecure Dockerfile Pattern - Direct sed Modifications — Dockerfile, lines with sed commands. The Dockerfile uses sed commands to modify source code for database provider switching (SqlServer to PostgreSQL). This approach is fragile, error-prone, and makes it difficult to track actual codebase state. It couples infrastructure concerns with application code and makes version control difficult. Fix: Use environment-based configuration (appsettings.{env}.json) and conditional code in Program.cs to select the database provider. Build separate Docker images or use configuration management instead of modifying source files at build time.
• High · Hardcoded Database Configuration in Docker — Dockerfile, line: cp -f src/SimplCommerce.WebHost/appsettings.docker.json src/SimplCommerce.WebHost/appsettings.json. The Dockerfile copies appsettings.docker.json directly, which likely contains database connection strings and other sensitive configuration. If this file is committed to the repository (as the file structure suggests), credentials may be exposed. Fix: Use Docker secrets or environment variables for sensitive configuration. Never commit appsettings files with real credentials to version control. Use .gitignore to exclude environment-specific configuration files.
• High · Incomplete Vulnerability Reporting Process — SECURITY.md. SECURITY.md provides only a single email contact (thienn@outlook.com) for security reports with no SLA, confirmation process, or PGP key for encrypted communication. This is insufficient for responsible disclosure. Fix: Establish a proper security vulnerability disclosure program including: response time SLA, PGP key for encrypted submission, acknowledgment process, responsible disclosure timeline, and consider using a bug bounty platform or security.txt standard.
• High · Outdated .NET 5.0 in Docker Base Image — Dockerfile, line: FROM mcr.microsoft.com/dotnet/sdk:5.0 AS build-env. .NET 5.0 reached end-of-life on May 10, 2022. Using an EOL runtime means no security patches are available. This exposes the application to known vulnerabilities. Fix: Update to a currently supported .NET version (.NET 6.0 LTS, .NET 7.0, or .NET 8.0 LTS). Update all package references accordingly and test thoroughly.
• High · Deprecated EF Core 5.0 Package — Dockerfile, line: RUN dotnet tool install --global dotnet-ef --version 5.0.0. The Dockerfile installs dotnet-ef version 5.0.0, which is outdated and no longer receives security updates. Older EF Core versions may have known vulnerabilities. Fix: Update dotnet-ef to match the current .NET runtime version (remove explicit version pinning to get the latest compatible version, or specify a supported LTS version).
• Medium · Database Initialization in Docker Build Stage — Dockerfile, lines with ef migrations commands. Running EF Core migrations during the Docker build stage (RUN dotnet ef migrations add initialSchema) couples build-time and runtime concerns. This makes the build dependent on a database existing and can fail unpredictably. Fix: Move database initialization to a separate initialization script or container. Use a migration runner container or implement migrations in the application startup code with proper error handling.
• Medium · Missing Security Headers Configuration — aws-beanstalk/.ebextensions/01_nginx.config. No evidence of security headers configuration (Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, etc.) in visible files. The nginx configuration file is minimal and likely lacks security hardening. Fix: Add comprehensive security headers in nginx configuration. Implement CSP, HSTS

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.