How taylorleprechaun/cfbpollui works
Purpose and entry points
CFB Poll is a college-football ranking and game-prediction system. It publishes historical and current FBS rankings, trends, team detail, prediction results, and an authenticated administration workflow for calculating, reviewing, and publishing snapshots.
Backend entry point: src/CFBPoll.API/Program.cs. Browser entry point: src/cfbpoll-web/src/main.tsx, with application routing/composition in src/cfbpoll-web/src/App.tsx.
API presentation boundary
ASP.NET Core controllers expose versioned REST endpoints and translate module results to API DTOs. Controllers do not access persistence directly; validation, JWT auth, request logging, and exception handling sit at this boundary.
Key paths: src/CFBPoll.API/Controllers/AdminController.cs, src/CFBPoll.API/Controllers/RankingsController.cs, src/CFBPoll.API/Extensions/AuthenticationServiceExtensions.cs.
Core module layer
CFBPoll.Core is the domain/application layer, organized around interfaces and modules. Modules coordinate external season data, calculations, persistence-backed snapshots, and derived views. This is the principal backend control-flow boundary: controllers → interfaces/modules → data services/data repositories.
Key paths: src/CFBPoll.Core/Modules/RankingsModule.cs, src/CFBPoll.Core/Modules/PredictionsModule.cs, src/CFBPoll.Core/Interfaces/IRankingsModule.cs.
Ranking and prediction pipeline
Admin operations calculate rankings and predictions into draft snapshots, then separately publish them. Rankings combine assembled season data with the rating algorithm; predictions combine ratings, schedules, and betting lines, and can later be graded against actual scores. The rating and prediction-calculator implementations are a private git submodule extension point, so a fresh public clone needs replacements.
Key paths: src/CFBPoll.Core/Modules/AdminModule.cs, src/CFBPoll.Core/Modules/PredictionGradingModule.cs, src/CFBPoll.Core/Modules/Proprietary/.
Data acquisition, assembly, and caching
CFBDataService integrates with the external College Football Data API. SeasonDataAssembler shapes source responses into season-domain input. A caching decorator plus persistent SQLite/GZip cache reduces repeated upstream requests; cleanup runs as a hosted service. Cache invalidation is available through admin operations.
Key paths: src/CFBPoll.Core/Services/CFBDataService.cs, src/CFBPoll.Core/Services/CachingCFBDataService.cs, src/CFBPoll.Core/Services/SeasonDataAssembler.cs.
Persistence and publication views
SQLite stores ranking snapshots, predictions, page visibility, and persistent cache records. Repository-like data classes are intentionally owned by their corresponding module only: rankings, predictions, cache, and page visibility. Public analytical views—All Time, Poll Leaders, Season Trends, Track Record, and Teams—derive from published snapshots plus fetched data/caches.
Key paths: src/CFBPoll.Core/Data/RankingsData.cs, src/CFBPoll.Core/Data/PredictionsData.cs, src/CFBPoll.Core/Modules/SeasonTrendsModule.cs.
React client
The React 19/Vite SPA uses React Router for pages, TanStack Query hooks for API lifecycle, Zod validation at response boundaries, and context for auth, selected season, page visibility, and theme. Public routes present rankings and analysis; guarded routes support login and administration. The client calls the API through centralized services rather than embedding endpoint logic in components.
Key paths: src/cfbpoll-web/src/services/api.ts, src/cfbpoll-web/src/contexts/auth-context.tsx, src/cfbpoll-web/src/pages/rankings-page.tsx.
Runtime and delivery
The system requires .NET 10, Node.js 18+, a College Football Data API key, SQLite storage, and JWT secrets/credentials. Swagger is hosted by the API. Excel export is supplied by the backend module. Deployment automation is defined in GitHub Actions with a PowerShell API deployment script.
Key paths: .github/workflows/deploy.yml, scripts/Deploy-API.ps1, src/CFBPoll.Core/Modules/ExcelExportModule.cs.
Main entry points: AdminModule.cs Admin snapshot pipeline · Program.cs ASP.NET Core API · RankingsData.cs SQLite snapshots and cache · App.tsx Routes and providers
Components 18
React client
- React/Vite SPA · Public analysis and guarded admin routes.
src/cfbpoll-web/src/main.tsx - Routes and providers · Router and shared client contexts.
src/cfbpoll-web/src/App.tsx - API service layer · Centralizes API calls, query lifecycle, and response validation.
src/cfbpoll-web/src/services/api.ts - Auth context
src/cfbpoll-web/src/contexts/auth-context.tsx
API boundary
- ASP.NET Core API · Hosts versioned REST, Swagger, middleware, and dependency wiring.
src/CFBPoll.API/Program.cs - REST controllers · Translate admin and ranking requests into module calls and DTOs.
src/CFBPoll.API/Controllers/RankingsController.cs - JWT authentication · Authenticates protected administration operations.
src/CFBPoll.API/Extensions/AuthenticationServiceExtensions.cs
Core application
- Core modules · Interface-driven orchestration for rankings, predictions, publication, and views.
src/CFBPoll.Core/Modules/RankingsModule.cs - Admin snapshot pipeline · Calculates draft rankings and predictions, publishes snapshots, and invalidates cache.
src/CFBPoll.Core/Modules/AdminModule.cs - Prediction grading · Grades published predictions against actual scores.
src/CFBPoll.Core/Modules/PredictionGradingModule.cs - Rating and prediction algorithms · Private git submodule requiring replacement in a fresh public clone.
- Published analytical views · Builds trends and other public analysis from published snapshots and season data.
src/CFBPoll.Core/Modules/SeasonTrendsModule.cs
Data and integrations
- Season data assembler · Shapes upstream responses into season input for calculations.
src/CFBPoll.Core/Services/SeasonDataAssembler.cs - College Football Data client · Integrates with the College Football Data API.
src/CFBPoll.Core/Services/CFBDataService.cs - Caching data service · Avoids repeated upstream season-data requests.
src/CFBPoll.Core/Services/CachingCFBDataService.cs - SQLite snapshots and cache · Stores ranking snapshots, predictions, visibility, and persistent cached records.
src/CFBPoll.Core/Data/RankingsData.cs - Predictions repository
src/CFBPoll.Core/Data/PredictionsData.cs
Operations
- Deployment automation · GitHub Actions deploys the API via PowerShell.
.github/workflows/deploy.yml
Connections 20
- React/Vite SPA → Routes and providers: boots
- Routes and providers → API service layer: uses
- Routes and providers → Auth context: provides
- API service layer → ASP.NET Core API: REST requests
- ASP.NET Core API → REST controllers: routes to
- ASP.NET Core API → JWT authentication: enforces
- REST controllers → Core modules: invokes interfaces
- REST controllers → Admin snapshot pipeline: admin operations
- Admin snapshot pipeline → Season data assembler: assembles season data
- Admin snapshot pipeline → Rating and prediction algorithms: calculates ratings and predictions
- Admin snapshot pipeline → SQLite snapshots and cache: writes drafts and publication
- Admin snapshot pipeline → Predictions repository: writes predictions
- Prediction grading → Predictions repository: reads and grades
- Core modules → SQLite snapshots and cache: reads published snapshots
- Published analytical views → SQLite snapshots and cache: derives from published data
- Core modules → Published analytical views: serves analysis
- Season data assembler → Caching data service: requests source data
- Caching data service → College Football Data client: cache miss
- Caching data service → SQLite snapshots and cache: persists cache
- Deployment automation → ASP.NET Core API: deploys