Technical Documentation

Illustrated Stats Wiki

This documentation covers the real product as it exists today: public discovery pages, the Try Me sandbox, team and season management, live stat workflows, account self-service, exports, and the core ASP.NET Core MVC structure behind the app.

App Type ASP.NET Core MVC web app with mobile-friendly layouts and installable web support.
Primary Use Basketball stat keeping, team management, season history, reports, and shared player records.
Access Paths Persistent live accounts for real work, plus a disposable Try Me sandbox for guided exploration.
Core Areas Teams, seasons, live games, player profiles, exports, owner tools, and account safeguards.

System Overview

Illustrated Stats is a basketball team management and stat-collection platform built around fast game-night usage. The app supports public product discovery, seeded demo access, team setup, roster management, seasonal organization, real-time collaborative stat entry, post-game reporting, printable summaries, and CSV exports.

Public-facing value

Visitors can learn the product, launch a real sandbox, and understand the workflow before creating a permanent account.

Operational value

Coaches, scorekeepers, players, and owners can work from one shared system without splitting live game data across tools.

Primary user journeys

Launch the Try Me sandboxVisitors can enter a disposable seeded workspace and experience the real dashboard and reporting flow without creating permanent data.
Create and manage a teamOwners or authorized users configure team identity, players, staff, branding, and season structure.
Start and run a gameUsers create a game, choose Classic or Dynamic stat keeping, join the lobby, and keep live totals synchronized.
Claim and manage identityUsers can manage account details, claim matching player profiles, and keep team access tied to the right login.
Finish and distribute resultsGame detail pages support PDF output, CSV downloads, post-game reports, edits, and guarded deletion.

Try Me Sandbox

Try Me is the guided demo path into the real application. It provisions a disposable account, team, roster, season, and game history so visitors can experience the real dashboard without affecting permanent customer data.

Real app, not a mockup

The sandbox uses the live UI and working workflows. The difference is that the seeded data is temporary and isolated for demo use.

Disposable session model

Demo sessions expire automatically after 10 minutes, and the layout shows a visible countdown with an Exit Try Me action.

Sandbox behavior

Launch flowThe Try Me entry point opens a branded loading experience, provisions demo data, signs the visitor into a temporary account, and redirects into the standalone team dashboard.
Demo bannerA persistent header banner identifies sandbox mode, shows the remaining time, and reminds visitors that the data will reset itself.
GuardrailsPermanent-account actions such as deeper team setup or ownership changes stay locked behind a live account so the demo remains safe and disposable.
Exit and restoreIf a signed-in user launches Try Me, exiting the sandbox restores the original account session instead of leaving the visitor signed out.

Roles And Access

The application behavior changes based on authentication state, demo mode, and elevated privileges. Several screens expose owner-only or admin-only actions while keeping public discovery pages open to everyone.

Anonymous visitors

Can browse the landing page, instructions, documentation, donation flow, sign-in, and the Try Me entry point.

Demo visitors

Receive a disposable seeded workspace with real navigation and reporting, but without permanent team-creation authority.

Authenticated users

Can access their teams, account area, assigned game workflows, and linked player tools based on team permissions.

Owners and elevated admins

Can access owner tools, approvals, impersonation support, and organization-level administrative workflows.

Impersonation support

The shared layout includes a visible impersonation banner and a return action when the relevant claim is present. This allows elevated operators to help another user while keeping the active context obvious on screen.

Teams, Rosters, Seasons

Team management is the foundation of the app. Teams hold identity, branding, roster membership, staff, and seasonal grouping. Team and season dashboards organize upcoming games, completed results, and reporting windows.

Core team concepts

Team profileName, icon, color, location, status, and ownership metadata.
RosterPlayers, jersey numbers, positions, profile links, and season-specific participation.
SeasonA dated context used to group games, standings, player stats, and historical outputs.
Management viewsThe standalone dashboard, team detail pages, and management screens support day-to-day maintenance.

Game creation

When creating a new game, the operator selects the stat-keeping model up front. This is where the workflow branches into Classic or Dynamic live stat behavior.

Live Stat Workflows

The live game experience is centered around the LiveStats screen. It provides the scoreboard, player selection, stat-entry sheet, correction and undo controls, lobby access, and cross-browser coordination signals.

Real-time philosophy

Recorded stats belong to the player and game, not to the specific scorekeeper currently holding that player or stat family.

Multi-user safety

The system prevents overlapping ownership in Classic mode and stat-family conflicts in Dynamic mode.

Live screen responsibilities

Open a player stat sheetDisplays player identity, quick stat buttons, running totals, and correction tools.
Record a statPosts to the backend quick-stat flow and refreshes local and shared totals.
Undo or direct adjustSupports correction paths without forcing the operator to rebuild the entire stat line.
Lobby accessLets users coordinate who is tracking players or stat families before and during the game.

Classic Mode

Classic mode is the original workflow. A scorekeeper claims one or more players and is responsible for all supported stats for those claimed players.

How Classic works

Player ownershipOnly one scorekeeper can actively track a player at a time.
Live handoffIf ownership changes from one scorekeeper to another, the player's existing stat totals carry over instead of resetting.
Main use caseSimple volunteer workflows where one person handles everything for a subset of players.

Correction behavior

Operators can directly adjust stat counts, undo the most recent change, or clear a player's collected game stats using the in-screen tools and confirmation flow.

Dynamic Mode

Dynamic mode is a second live-stat workflow designed for families or staff who want to split work by stat type instead of by player.

Stat-family model

PointsCovers 2-point makes and misses, 3-point makes and misses, and free throws.
Individual categoriesRebounds, assists, blocks, turnovers, steals, and fouls can each be assigned independently.
Coverage ruleThe game cannot start until all required Dynamic stat families are claimed by someone.

Dynamic interaction model

In Dynamic mode, anyone can open any player. The live stat tiles only stay active for the stat families currently claimed by that user, while unowned categories stay greyed out and blocked.

Dynamic families: points rebounds assists blocks turnovers steals fouls

Lobby And Presence

The lobby is the coordination layer for both live workflows. It shows who is present, what they are responsible for, and whether the game is ready to begin.

Classic lobby

Classic mode shows who is tracking which players. It supports player claiming, saving selections, and scheduled-game startup.

Dynamic lobby

Dynamic mode shows who is covering what, current coverage completeness, and role-selection actions. The UI emphasizes visible presence, clearer labels, and easier claim controls so scorekeepers can coordinate quickly.

Presence polling

Browsers refresh presence and assignment data to keep lobby state synchronized across users.

Start-game gate

Scheduled Dynamic games stay blocked until all required stat jobs are covered.

Post-Game, CSV, Reports

After a game is completed, the game detail page becomes the source of truth for final outputs and administrative follow-up.

Printable PDFDesigned for sharing, printing, or archiving game results.
CSV exportProvides a tabular backup and downstream data portability.
Post-game reportSupports recap and communication workflows after the final whistle.
Edit statsAllows post-game data corrections when needed.

Delete game safeguard

The completed-game delete flow nudges users to export first and keeps confirmation guardrails in front of final removal so historical data is not lost casually.

Accounts, Profiles, And Self-Service

The account area now handles more than simple profile edits. It ties together sign-in identity, team access, player profile linking, owner-controlled email changes, and destructive account cleanup.

Identity and profile management

Users can edit profile details from the account dashboard while keeping their team access and login context in one place.

Claimable player profiles

If a coach-created player record matches the signed-in email, the dashboard can surface a claim flow so the player can take ownership of that profile.

Self-service flows

Request email changeUsers can submit a new email request while keeping their current sign-in email active until an owner approves the change.
Claim player profileMatching player records can be linked to the signed-in account so the user can manage the correct player page.
Linked player and delegate contextPlayer-facing experiences can carry linked-login and delegate access information for families, staff, and support scenarios.
Delete accountThe delete flow now requires typing DELETE, keeps the action disabled until confirmed, and removes related memberships, tokens, linked player access, owned teams, and the user account itself.

Application Architecture

The app follows an ASP.NET Core MVC structure with controllers, Razor views, shared layout composition, service-layer helpers, and SQL-backed storage. Most game-night interactivity is implemented with Razor-rendered HTML plus client-side JavaScript inside the relevant views.

Key controllers and services

HomeControllerLanding pages, utility pages, privacy, instructions, and documentation content.
TeamsControllerTeam management, seasons, dashboards, game creation, and start-game entry points.
GameStatsControllerLive stats, game detail, CSV export, quick stat recording, join and lobby flows, and deletion workflows.
AccountController and AdminControllerAuthentication, account tools, owner console, impersonation, approvals, and user-level operations.
DemoController and DemoProvisioningServiceProvision the Try Me sandbox, issue demo claims, restore prior sessions, and clean up expired demo data.

View responsibilities

Large interaction-heavy views such as LiveStats.cshtml, account surfaces, and dashboard pages hold significant UI logic, live polling, and client-side state management. Shared navigation and cross-app messaging live in Views/Shared/_Layout.cshtml.

Data And Storage

The application uses SQL-backed entities and runtime schema checks for newer features. Live stat mode selection, demo provisioning, account cleanup, and player-link flows all depend on persisted relational data.

Important persisted concepts

Games.StatKeepingModeStores whether a game uses Classic or Dynamic live-stat behavior.
GameDynamicStatAssignmentsMaps game, user, and stat-family ownership for Dynamic mode.
Lobby presence and assignmentsTracks live participant presence and current ownership state used by the lobby UI.
Player game statsCanonical live stat records attach to the player and game identity rather than the current scorekeeper session.
Demo session recordsSandbox provisioning stores disposable session data and asset mappings so expired demo workspaces can be cleaned up safely.
Account cleanup dependenciesUser memberships, permissions, invites, tokens, linked player references, and owned-team relationships are explicitly cleaned when destructive account actions run.

Data safety patterns

Deletion flows explicitly clean up related rows, and export-first safeguards reduce the risk of losing final game history without an offline backup.

Operations And Support

From an operating perspective, the app is optimized for gym usage, phone entry, onboarding new scorekeepers quickly, and preserving clean account ownership over time.

Recommended support checklist

Before a gameConfirm the correct team, season, roster, opponent, and stat-keeping mode. Use Try Me when training a new operator without risking production data.
During a gameUse the lobby to verify assignments, watch presence updates, and confirm operators are recording in the proper mode.
After a gameReview final totals, export CSV or PDF, send post-game reports, and only then use deletion options if necessary.
Account hygieneOwners should review email-change requests, claim-profile situations, delegate access, and account removal requests so identity stays aligned with the right teams and players.