PoPunkouterSoftware

PoPunkouterSoftware is a .NET 10 Blazor Web App with a server host, a WebAssembly client, and operational endpoints for the Azure inventory report, the app portfolio, and diagnostics.

Solution Layout

• src/PoPunkouterSoftware.API/: ASP.NET Core host + BFF. Feature slices under Features/<Area>/ (Config, Diag, Portfolio, SignIns); host-level plumbing that belongs to no slice lives in Host/. Hosts the Blazor WASM shell.
• src/PoPunkouterSoftware.Client/: WASM UI, layouts, pages, and static assets.
• src/PoPunkouterSoftware.Shared/: contracts and models shared between the host and client.
• src/PoPunkouterSoftware.Infrastructure/: Azure and integration adapters.
• tests/PoPunkouterSoftware.Unit/: xUnit, strictly no-I/O.
• tests/PoPunkouterSoftware.Integration/: WebApplicationFactory + Azurite Testcontainers.
• tests/PoPunkouterSoftware.E2EAPI/: pure-HTTP contract tests against a live instance.
• tests/PoPunkouterSoftware.E2EUI/: C# Playwright browser tests (run on demand against a live instance).
• SCRIPTS/: setup and automation helpers.

Local Development

Prerequisites:

• .NET SDK from global.json
• Node.js for Playwright tests
• Docker Desktop for Azurite-backed integration scenarios

Common commands:

dotnet build .\PoPunkouterSoftware.sln
dotnet test .\tests\PoPunkouterSoftware.Unit
dotnet test .\tests\PoPunkouterSoftware.Integration

Available VS Code tasks in this workspace include:

• build
• test-unit
• start-azurite
• start-api-server
• deep-clean (removes every bin/ and obj/; dotnet clean leaves obj/ behind)

The app runs locally on HTTP port 8000.

Runtime Notes

• /health is the deep probe (Key Vault, Table Storage); /healthz is a static liveness ping.
• /api/diag/* (summary, report, refresh, cancel-refresh, restart/{name}, ai) expose diagnostics; /diag itself was removed 2026-09-04 — diagnostics surface in the /azure Advanced diagnostics drawer. restart/{name} restarts (or starts) one scanned App Service and sits behind the same management gate as refresh; in Azure it also needs Website Contributor, which infra does not grant.
• Each scan also reads Azure Resource Health (for down apps), Azure Advisor, 24h exception counts per app from the shared Application Insights component (SignIns:ResourceId), and open Dependabot alerts per matched repo (needs Dependabot enabled on the repo and a PAT with "Dependabot alerts: read").
• Push alerts go through ntfy (Alerts:NtfyTopic): app down/up, failed scan, spend spike, an SSL certificate crossing 14 days, the month-end forecast crossing the budget. deploy.yml (rollback) and screenshots.yml (Lighthouse drop of 15+ points) send to the same topic via the optional NTFY_TOPIC GitHub secret, falling back to the Key Vault secret.
• deploy.yml backs up the live site, smoke-tests /healthz, /health and /api/diag/summary after deploying, and redeploys the backup if the smoke test fails.
• Azure behavior prefers Key Vault and managed identity when available, with local fallback configuration for development.
• The client dashboard consumes the shared Azure report models generated by the server and infrastructure layers.
• /settings holds every visitor preference — theme, density, sound and effects — in localStorage, each defaulting to the simplest option. Full effects (fluid, flocks, scars, the health orb, the palette jump) are opt-in.

Testing Strategy

• Unit tests (PoPunkouterSoftware.Unit) cover pure logic and API helpers, no I/O.
• Integration tests (PoPunkouterSoftware.Integration) cover host configuration, diagnostics endpoints, and Azure Table Storage behavior via WebApplicationFactory + Testcontainers Azurite.
• E2E tests (PoPunkouterSoftware.E2EAPI, PoPunkouterSoftware.E2EUI) cover the HTTP contract and browser flows against a live instance; on demand, not in CI. E2EUI runs axe-core's WCAG 2.1 A/AA rules over every page (Deque.AxeCore.Playwright) and fails on serious or critical violations.
• Each tier has a hard test budget — 100 Unit, 50 Integration, 25 E2E-API, 25 E2E-UI. Adding a test means removing one; prefer widening an existing test's assertions.

Developer Guidance

• Read CLAUDE.md before broad changes — it is the single context map. (AGENT.MD was merged into it and deleted; AGENTS.md only points there.)
• Keep /api/diag/* available but do not link them from the UI — diagnostics surface only in the /azure Advanced diagnostics drawer.
• Preserve Po-prefixed naming and strict build quality defaults from Directory.Build.props.