# TECH - Kickoff Blueprint from Pick'n'Play

This document extracts the implementation patterns, conventions, and guardrails from the current codebase so a new webapp can start with proven structure and avoid known pitfalls.

Scope covered:
- Backend (`Program.cs`, `Endpoints/*`, `Infrastructure/*`, `Data/*`, `Domain/*`, `Contracts/*`)
- Frontend (`wwwroot/*`)
- Tooling and CI (`scripts/*`, `.github/workflows/ci.yml`, npm tooling)
- Tests (`GameList.Tests/*`)
- Review carryover (`REVIEW.md` unresolved topics)

## 1) Stack and baseline choices

- ASP.NET Core Minimal API on .NET 10.
- EF Core + SQLite in current project (single-node deployment).
- Cookie authentication (`HttpOnly`, `SameSite=Strict`, secure in production).
- Static frontend (HTML/CSS/JS modules), no frontend framework.
- OpenAPI generated from backend and consumed by generated JS client.
- xUnit integration-heavy test suite with in-memory SQLite and coverage gates.

## 2) Architecture patterns to keep

### 2.1 API shape and layering

- Route mapping in thin endpoint modules (`MapXEndpoints` per feature area).
- Domain logic in workflow services (`*WorkflowService`) instead of endpoint lambdas.
- Service responses normalized via `ServiceResult<T>` + `ServiceError`, then mapped to HTTP at the edge.
- Consistent `ProblemDetails` payloads with `error` extension for machine-usable errors.
- Endpoint-level concerns handled by endpoint filters (`AdminOnlyFilter`, `PhaseRequirementFilter`, `PhaseOrJokerFilter`).

Keep this split:
- Endpoint adapters: auth, deserialization, HTTP mapping only.
- Workflow services: validation, query/update rules, transactions.
- Helpers: shared utility and security-sensitive routines.

### 2.2 Middleware pipeline discipline

- Security and behavior depend on middleware ordering; keep explicit ordering.
- Important current order:
  1. Forwarded headers
  2. Rate limiter
  3. HSTS + HTTPS redirect (prod)
  4. Security headers writer
  5. Base path
  6. Global exception handling
  7. Authentication
  8. Ensure player still exists
  9. CSRF origin/referer checks
  10. Authorization
  11. State change notifier middleware
  12. Static files
  13. Endpoint mapping

### 2.3 State synchronization

- Event-driven invalidation with SSE (`/api/events/state`) plus heartbeats.
- Conditional reads for state (`ETag` + `If-None-Match`) to return `304`.
- In-process notifier (`StateChangeNotifier`) with monotonic version and etag stamp.
- Mutation middleware (`StateChangeNotificationMiddleware`) emits invalidation only for successful mutating API calls.

This pattern is a strong baseline for low to medium scale and should be the default in the new app.

### 2.4 Security baseline

- Cookie auth with short/medium session sliding expiration plus absolute lifetime cap.
- Explicit same-origin CSRF checks for authenticated mutating API calls.
- Rate limiting on auth-sensitive and admin-sensitive surfaces with custom `429` payload.
- Security headers on all responses (`CSP`, `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, `Permissions-Policy`).
- Forwarded headers restricted to configured trusted proxies/networks only.
- Owner/admin protection rules enforced in business logic and DB constraints.
- Destructive admin operations require password re-confirmation.
- Password hashing is versioned and supports transparent upgrade on successful auth.
- Current hash defaults to Argon2id, with legacy compatibility retained.

### 2.5 Data and invariants

- Strong DB model with explicit constraints:
  - Unique normalized username
  - Unique owner partial index
  - Unique vote key `(PlayerId, SuggestionId)`
  - Seeded singleton app state row
- DB-level guardrails (trigger) complement app-level checks:
  - Suggestion limit enforced in DB (`suggestion_limit_exceeded`) to survive concurrent writes.
- EF patterns:
  - `AsNoTracking()` for read-only queries
  - `ExecuteUpdateAsync` / `ExecuteDeleteAsync` for efficient bulk operations
  - Explicit transactions for multi-step destructive/admin operations
  - Conflict handling around unique constraints

### 2.6 Workflow and permission model

- Phases (`Suggest`, `Vote`, `Results`) drive endpoint access and UX behavior.
- Effective phase can be derived from persisted phase + global `resultsOpen`.
- Reconciliation helper functions centralize phase alignment rules.
- Admin abilities are intentionally constrained per operation (e.g., only specific transitions allowed).

Keep centralization of workflow rules. Avoid spreading phase/permission checks inline.

### 2.7 Frontend architecture

- ES module split by concern:
  - API wrapper
  - Data loaders
  - UI composition
  - Feature-specific renderers/handlers
  - Shared utils and runtime dependency injection
- Single runtime state object with deliberate clear/reset logic.
- Refresh scheduler:
  - Serialized refreshes (no overlap)
  - Adaptive polling backoff
  - SSE-triggered immediate refresh for state mutations
  - Visibility-aware refresh suppression
- API client is generated from OpenAPI operation ids, not handwritten endpoints.
- Internationalization:
  - translation file validation at startup
  - language-specific FAQ markdown loading with fallback to default language

### 2.8 Frontend safety and rendering hygiene

- Safe rendering helpers:
  - `escapeHtml` for template interpolation
  - `safeUrl` for links/media
- Sensitive modal content set via `textContent`, not interpolated HTML.
- Trusted output patterns covered by regression tests.

Maintain this as a non-negotiable standard for any user-supplied content path.

### 2.9 Testing strategy patterns

- Full-stack integration tests via `WebApplicationFactory`.
- Real migrations applied to in-memory SQLite during test host startup.
- HTTP side effects mocked deterministically (`StubHttpMessageHandler` and `IHttpClientFactory` replacement).
- Coverage-focused tests for:
  - auth/security rules
  - middleware behavior
  - filter behavior
  - link/vote/result edge cases
  - OpenAPI operation id stability
- CI-local parity script (`scripts/ci-local.ps1`) mirrors pipeline flow.

### 2.10 Tooling and contract discipline

- OpenAPI generated during build (`openapi/GameList.json`).
- JS client generated from OpenAPI with required operation-id checks.
- Separate lint + format + tests + coverage threshold checks.
- Build configured with warnings as errors in CI/local script.

## 3) Concrete feature set currently implemented

Use this as a reusable "starter scope menu" for the new app:

- Auth:
  - register/login/logout
  - owner bootstrap via admin key
  - immutable display name post-registration
  - auth options endpoint for registration UX
- Identity/session:
  - cookie claim identity with admin claim
  - stale/deleted-account cookie invalidation
  - absolute session lifetime enforcement
- State:
  - `/api/state`, `/api/me`
  - phase next/prev
  - SSE state invalidation
  - etag conditional state reads
- Suggestions:
  - create/update/delete/mine/all
  - phase gating + admin override behavior
  - suggestion cap + joker path
  - link metadata exposure
  - screenshot URL and reachability validation
- Votes:
  - vote upsert
  - finalize/unfinalize
  - linked suggestion vote fan-out
  - conflict handling on concurrent insert/update
- Results:
  - gated by phase + admin-open flag
  - ordered leaderboard with aggregates and voter metadata
  - per-user own vote context
- Admin:
  - results open/close toggle with phase realignment
  - vote status panel
  - joker grant
  - player phase correction
  - admin role grant/revoke (owner protected)
  - player delete with cascades and password confirmation
  - link/unlink suggestions with vote reset and unfinalize behavior
  - reset/factory reset with password confirmation

## 4) REVIEW.md unresolved topics -> new-project design defaults

This section translates outstanding review risks into early decisions for the new app.

### 4.1 Data store scalability

Review concern:
- SQLite bottlenecks under higher write concurrency and multi-node scaling.

New-project default:
- Start with PostgreSQL (or SQL Server) for production profile.
- Keep provider abstraction and provider-specific migration strategy from day one.
- Keep SQLite only as local dev/test convenience if needed.

### 4.2 Workflow extensibility

Review concern:
- Workflow transitions are hard-coded in many places.

New-project default:
- Define transitions in a single state-machine table/model.
- Drive backend authorization and frontend navigation from same transition metadata.
- Add tests that validate the transition table itself.

### 4.3 Authorization model growth

Review concern:
- Role booleans (`IsAdmin`, `IsOwner`) limit future permission expansion.

New-project default:
- Use role/permission tables or claims-based capabilities.
- Keep owner as a protected capability, not a special-case boolean spread across code.
- Use policy-based authorization with explicit capability names.

### 4.4 Frontend maintainability

Review concern:
- String-template-heavy UI + global mutable state can become fragile.

New-project default:
- Move to TypeScript (or strict JSDoc typing) early.
- Keep module boundaries by feature.
- Keep explicit escaping/safe-url guards and DOM `textContent` standards.
- If not using framework, introduce a small typed view-model layer.

### 4.5 In-memory cache bounds

Review concern:
- Unbounded dictionaries may grow under high-cardinality traffic.

New-project default:
- Replace unbounded maps with bounded `MemoryCache` (size + TTL + eviction).
- For distributed deployments, use Redis with cardinality and TTL controls.

### 4.6 Linking/results query scaling

Review concern:
- Link and result workflows currently pull full sets into memory.

New-project default:
- Persist link-group ids and compute aggregates in SQL.
- Add pagination/windowing for large result sets.
- Benchmark query plans on realistic volumes.

### 4.7 External URL validation latency

Review concern:
- Reachability validation happens synchronously on write path.

New-project default:
- Accept user URL quickly, validate asynchronously (job queue/background worker), store validation status.
- Optionally proxy or prefetch media through controlled media service.

## 5) Topics from REVIEW that are already fixed and should be carried forward

- Polling amplification has been reduced through SSE + etag conditional reads.
- CSRF protection is explicit (same-origin validation for authenticated mutating requests).
- Password hashing is versioned and modernized (Argon2id current, transparent upgrades).
- CSP is tightened compared to prior permissive baseline (no inline style allowance, no insecure image origins).
- API drift risk reduced with OpenAPI generation + generated frontend client.

These are not optional add-ons; they should be baseline in the new app.

## 6) New-project starter checklist

- Bootstrap:
  - choose production DB provider first
  - define transition/state-machine model before endpoint coding
  - define permission/capability model before admin features
- Security:
  - cookie or token strategy finalized with CSRF model
  - rate limiting partitions and thresholds defined
  - strict CSP and security headers in first commit
  - versioned password hashing with migration strategy
  - trusted proxy/host settings explicit
- Contract:
  - OpenAPI generation enabled in build
  - generated client wired into frontend
  - operation-id stability tested
- Data integrity:
  - enforce critical invariants both app-side and DB-side
  - transaction boundaries for multi-entity admin actions
- Frontend:
  - module boundaries and state refresh model defined
  - escaping/url-safe helpers mandatory
  - i18n structure and fallback behavior in place
- Testing:
  - integration test host with real migrations
  - deterministic stubs for network dependencies
  - coverage gate enforced in local + CI scripts

## 7) Keep/avoid quick reference

Keep:
- Thin endpoints + workflow services.
- Shared service result abstraction.
- Explicit middleware order.
- SSE + ETag state sync.
- Generated API client from OpenAPI.
- DB-enforced invariants.
- Regression tests for security-sensitive UI rendering.

Avoid:
- Hard-coded workflow transitions scattered in backend/frontend.
- Boolean-only role model for long-term products.
- Unbounded in-memory caches.
- Synchronous external network checks on hot write paths.
- Manual API contract duplication between docs/frontend/backend.