ShopStack

ShopStack is a .NET 10 distributed e-commerce demo under active implementation. The repository now contains working shopper checkout, admin management, and admin observability flows on top of the Phase 1 and Phase 2 foundations defined in specs/001-shopstack-ecommerce/.

Current Status

• Distributed-app runtime: AppHost, ServiceDefaults, Api, DbMigrator, Application, Domain, and Infrastructure
• Persistence foundation: ASP.NET Core Identity on EF Core 10 with a generated SQLite migration and refresh-token persistence
• Shopper flow: seeded catalog browse, guest cart, login-gated checkout, order confirmation, and order history
• Admin flow: seeded admin sign-in, user-state changes, product create-edit-deactivate actions, order-status updates, report summaries, audit history, and weather monitoring
• Test coverage: xUnit unit and integration suites plus Vitest and Playwright coverage for shopper, admin management, and admin observability flows

Stack

• Orchestration: .NET Aspire AppHost
• Backend: ASP.NET Core 10 REST API, EF Core 10, SQLite, JWT auth foundation, ASP.NET Core Identity
• Frontend: React 19, Vite 8, Bun, Tailwind CSS v4, shadcn/ui-compatible source setup
• Tests: xUnit, Vitest, Playwright

Local Prerequisites

• .NET SDK 10.0.201
• Aspire templates via dotnet new install Aspire.ProjectTemplates
• Bun 1.3.x
• Playwright browser binaries via bunx playwright install

Environment Variables

Recommended for local development:

• Jwt__SigningKey
• Seed__DefaultPassword
• Weather__ApiKey

Optional with current local defaults:

• ConnectionStrings__shopstack defaults to Data Source=shopstack.db
• Jwt__Issuer defaults to ShopStack
• Jwt__Audience defaults to ShopStack.Clients
• Jwt__SigningKey currently falls back to a development-only scaffold key and should be overridden locally
• Seed__DefaultPassword currently falls back to ShopStack!123 and should be overridden locally
• Weather__DefaultStorefrontLocation defaults to Santo Domingo,DO
• Weather__DefaultAdminLocation defaults to Santo Domingo,DO
• Weather__PerMinuteLimit defaults to 60
• Weather__MonthlyLimit defaults to 1000000
• Weather__CacheDurationMinutes defaults to 5

Repository Layout

src/
  ShopStack.AppHost/
  ShopStack.ServiceDefaults/
  ShopStack.Api/
  ShopStack.DbMigrator/
  ShopStack.Application/
  ShopStack.Domain/
  ShopStack.Infrastructure/
tests/
  ShopStack.Api.UnitTests/
  ShopStack.Api.IntegrationTests/
  ShopStack.AppHost.Tests/
  ShopStack.E2E/
web/
  shopstack-web/

Local Commands

Restore and build the .NET solution:

dotnet restore ShopStack.sln
dotnet build ShopStack.sln

Install frontend dependencies:

Push-Location web/shopstack-web
bun install
Pop-Location

Install end-to-end dependencies and Playwright browsers:

Push-Location tests/ShopStack.E2E
bun install
bunx playwright install
Pop-Location

Apply migrations and seed the current demo dataset:

dotnet run --project src/ShopStack.DbMigrator

Run the distributed app host:

dotnet run --project src/ShopStack.AppHost

Run the API directly during early development:

dotnet run --project src/ShopStack.Api

Build the frontend shell:

Push-Location web/shopstack-web
bun run build
Pop-Location

Run the current test commands:

dotnet test ShopStack.sln

Push-Location web/shopstack-web
bun run test
Pop-Location

Push-Location tests/ShopStack.E2E
bunx playwright test tests/shopper-checkout.spec.ts tests/admin-management.spec.ts tests/admin-monitoring.spec.ts tests/startup.spec.ts
Pop-Location

Validation Evidence

• 2026-03-16: final validation passed with dotnet test ShopStack.sln --no-restore reporting 51 passed tests, bun run test reporting 14 passing files and 24 passing tests, bunx playwright test reporting 4 passing end-to-end scenarios, and dotnet run --project src/ShopStack.AppHost successfully starting the AppHost and dashboard.
• 2026-03-16: dotnet build src/ShopStack.Api/ShopStack.Api.csproj --no-restore succeeded.
• 2026-03-16: targeted operational backend validation passed with 18 tests and 0 failures across report, audit-log, weather, readiness, and AppHost smoke coverage.
• 2026-03-16: bun run test in web/shopstack-web passed with 14 files and 24 tests. The run still emits React act(...) warnings in existing admin route tests, but no assertions failed.
• 2026-03-16: tests/shopper-checkout.spec.ts passed in isolation and serves as evidence for SC-001 and SC-002. The warmed explore-page reload and warmed product-detail transition both satisfied the under-2-second threshold used in the spec validation.
• 2026-03-16: tests/admin-management.spec.ts passed in isolation and serves as evidence for SC-003.
• 2026-03-16: tests/admin-monitoring.spec.ts passed in isolation and serves as evidence for SC-004 and SC-007. The warmed reporting, audit-log, and weather-monitoring route transitions satisfied the under-2-second threshold used in the spec validation.
• 2026-03-16: tests/startup.spec.ts passed in isolation and complements the xUnit AppHost/readiness smoke checks for startup coverage.

Current Seeded Dataset

• 1 seeded customer account
• 1 seeded admin account
• 1 seeded suspended customer account for admin state-transition demos
• 14 seeded products with active and inactive catalog cases
• guest and authenticated carts
• saved addresses and masked payment profiles for the seeded customer
• 2 seeded orders, including a mutable submitted order for admin workflows
• seeded audit-log history covering authentication, administration, catalog, orders, and weather events
• seeded storefront and admin weather snapshots plus usage-ledger records for stale/fallback demos
• foundational Identity roles and refresh-token storage

Startup Order

1. ShopStack.DbMigrator applies migrations and seeds the foundational platform data.
2. The API waits for the migrator before serving traffic inside the AppHost.
3. The Bun frontend executable starts after the API resource is ready inside the AppHost.
4. The frontend shell reads VITE_API_BASE_URL when supplied and otherwise uses its local default configuration.

Reset Behavior

Resetting the demo environment clears the local SQLite database, reapplies migrations, and reseeds the documented shopper and admin demo data. The reset workflow is designed to remain idempotent across repeated local demos.

Seeded Credentials Strategy

• Customer email: customer@shopstack.local
• Admin email: admin@shopstack.local
• Both seeded accounts use the local-only password supplied through Seed__DefaultPassword, or ShopStack!123 if no override is set yet

The seeded password must never be treated as production-safe. Override it in local secrets or environment configuration during development.

Phase 3 And 4 Flows

The current shopper flow supports:

• browsing the seeded catalog from /
• adding items to a guest cart and carrying that cart into checkout
• signing in as customer@shopstack.local to merge the guest cart
• placing an order and verifying the result in /account

The current admin flow supports:

• signing in as admin@shopstack.local
• visiting /admin/users to change seeded user state, including the suspended demo customer example
• visiting /admin/products to create, edit, or deactivate catalog entries against seeded active and inactive product cases
• visiting /admin/orders to update non-terminal order statuses on the seeded submitted order
• visiting /admin/reports to review order, catalog, customer, and weather-usage summary metrics
• visiting /admin/audit-logs to review newest-first operational history with category filters
• visiting /admin/weather to verify fresh, stale, and unavailable weather states alongside quota usage and cache-hit visibility

Redesign Details

The UI has been completely refreshed based on the 002-ui-redesign specs. Reviewer flow and routes are strictly preserved against V1 boundaries. Playwright E2E handles validation.