RpgRoller/README.md

RpgRoller

Fresh full-stack starter scaffold:

• RpgRoller/: ASP.NET Core backend + Blazor frontend host (Components + wwwroot)
• RpgRoller.Tests/: xUnit integration-heavy test project
• RpgRoller.sln: solution used by local CI script
• UX.md: frontend UX and interaction design specification (pre-implementation baseline)
• FRONTEND_PROGRESS.md: implementation tracking (Implemented / Partially implemented / Not yet implemented)

Test layout:

• RpgRoller.Tests/Api/: API integration tests grouped by feature concern
• RpgRoller.Tests/Services/: service-level tests grouped by domain concern
• RpgRoller.Tests/Support/: shared test harnesses/builders/helpers

Code Organization

Backend:

• RpgRoller/Program.cs: thin app bootstrap only
• RpgRoller/Hosting/: service registration + startup initialization
• RpgRoller/Api/: endpoint mapping modules and auth/session filter helpers
• RpgRoller/Services/: game workflows with explicit method parameters (no API DTO dependencies)

Frontend:

• RpgRoller/Components/: Blazor root app, routes, layout and page components
• RpgRoller/Components/Pages/Home.razor: top-level page composition using concern-focused child controls
• RpgRoller/Components/Pages/Home.*.cs: concern-based partial class split (State, Lifecycle, Auth, Campaign, Character, Skill, Realtime, Api, Presentation, Validation)
• RpgRoller/Components/Pages/Home.Models.cs: reusable FormState<TModel> + page form models
• RpgRoller/Components/Pages/HomeControls/: auth, campaign management, play-screen, and modal controls extracted from Home.razor
• Form ownership model: controls own transient form/error state and execute their concern-specific API mutations directly
• RpgRoller/Components/RpgRollerApiClient.cs: shared browser API client used by Home and leaf controls
• RpgRoller/wwwroot/js/rpgroller-api.js: browser-side API + SSE + session storage interop for Blazor
• RpgRoller/wwwroot/styles.css: responsive UX styling and theme tokens

Backend state persistence:

• EF Core with SQLite (Microsoft.EntityFrameworkCore.Sqlite)
• Development DB: RpgRoller/App_Data/rpgroller.development.db
• Default DB: RpgRoller/App_Data/rpgroller.db
• Database schema is created/upgraded automatically on startup via EF Core migrations (Database.Migrate)
• Runtime state is loaded once at startup into memory and written back to SQLite on successful state changes

Prerequisites

• .NET SDK 10.0+
• PowerShell 7+
• Run dotnet tool restore once to enable the repo-local dotnet-ef command.

Local Development

1. Run the local CI parity script:

   pwsh ./scripts/ci-local.ps1
   

2. Start the backend:

   dotnet run --project RpgRoller/RpgRoller.csproj
   

3. Open http://localhost:5000 (or the port shown in the console).

VS Code F5 debug profiles are available in .vscode/launch.json:

• RpgRoller: Server
• RpgRoller: Server + Edge (F5)
• RpgRoller: Server + Firefox (F5)

To use a custom SQLite database path, set ConnectionStrings__RpgRoller.

For migration authoring, use the local tool command form:

dotnet dotnet-ef migrations add <MigrationName> --project RpgRoller/RpgRoller.csproj --startup-project RpgRoller/RpgRoller.csproj

Frontend Runtime

• Runtime frontend is Blazor Server with interactive components.
• Browser interop is in RpgRoller/wwwroot/js/rpgroller-api.js.
• OpenAPI contract source remains at openapi/RpgRoller.json.

Test and Coverage

• Tests:

  dotnet test RpgRoller.Tests/RpgRoller.Tests.csproj --collect:"XPlat Code Coverage" --settings RpgRoller.Tests/coverlet.runsettings
  

• Coverage gate:

  pwsh ./scripts/check-coverage.ps1 -MinLineRate 0.90 -MinBranchRate 0.70
  

• Coverage collector scope:
  • RpgRoller.Tests/coverlet.runsettings now measures the full backend assembly (RpgRoller), not only service namespace files.

Implemented Backend Scope

• Auth: register, login, logout, current user context
• Session cookie: HttpOnly, SameSite=Strict, Secure when served over HTTPS
• Rulesets: d6 and dnd5e validation rules
• Campaigns: create/list/read
• Characters: create/update/activate/current-campaign list
• Skills: create/update with ruleset-aware dice expression validation and d6 wild-dice/fumble options
• Rolls: public/private skill rolls with append-only campaign log; d6 rolls include wild/crit/fumble/add/remove die-state payloads
• State stream: SSE endpoint for campaign version updates

Implemented Frontend Scope

• Blazor-driven UI for:
  • registration, login, logout
  • play screen and campaign management screen switch
  • campaign creation and selection
  • character create/edit via modal forms, with picker selection treated as active character context
  • skill create/edit via modal forms including d6 wild dice + allow-fumble controls
  • public/private rolling and campaign log viewing
  • die-state visualization in Last Roll and Campaign Log (critical, fumble, wild, removed, added)
• responsive play UX:
  • desktop two-column (character + log)
  • tablet/mobile panel switching with bottom tab bar (Character / Log)
• SSE-backed live refresh with reconnect status + manual refresh fallback