# taylorleprechaun/cfbpollui architecture

> Architecture diagram of the GitHub repository taylorleprechaun/cfbpollui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/taylorleprechaun/cfbpollui
- Repository: https://github.com/taylorleprechaun/cfbpollui

## Overview

#### 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: [`src/CFBPoll.Core/Modules/AdminModule.cs`](https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.Core/Modules/AdminModule.cs) (Admin snapshot pipeline), [`src/CFBPoll.API/Program.cs`](https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.API/Program.cs) (ASP.NET Core API), [`src/CFBPoll.Core/Data/RankingsData.cs`](https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.Core/Data/RankingsData.cs) (SQLite snapshots and cache), [`src/cfbpoll-web/src/App.tsx`](https://github.com/taylorleprechaun/cfbpollui/blob/main/src/cfbpoll-web/src/App.tsx) (Routes and providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_spa["React/Vite SPA<br/>browser application<br/>[main.tsx]"]
  node_client_composition["Routes and providers<br/>client composition<br/>[App.tsx]"]
  node_client_api["API service layer<br/>client service<br/>[api.ts]"]
  node_auth_context["Auth context<br/>client context<br/>[auth-context.tsx]"]
end

subgraph group_api["API boundary"]
  node_api_host["ASP.NET Core API<br/>API host<br/>[Program.cs]"]
  node_controllers["REST controllers<br/>API controllers"]
  node_api_auth["JWT authentication<br/>API security"]
end

subgraph group_core["Core application"]
  node_modules["Core modules<br/>application layer<br/>[RankingsModule.cs]"]
  node_admin_pipeline["Admin snapshot pipeline<br/>administration module<br/>[AdminModule.cs]"]
  node_grading["Prediction grading<br/>application module"]
  node_proprietary_algorithms{{"Rating and prediction algorithms<br/>private submodule extension"}}
  node_analytical_views["Published analytical views<br/>derived view modules"]
end

subgraph group_data["Data and integrations"]
  node_season_assembler["Season data assembler<br/>domain assembly service"]
  node_cfb_data["College Football Data client<br/>external data service<br/>[CFBDataService.cs]"]
  node_cached_data["Caching data service<br/>cache decorator"]
  node_sqlite[("SQLite snapshots and cache<br/>persistence<br/>[RankingsData.cs]")]
  node_prediction_data["Predictions repository<br/>module-owned data access<br/>[PredictionsData.cs]"]
end

subgraph group_runtime["Operations"]
  node_deployment["Deployment automation<br/>CI/CD<br/>[deploy.yml]"]
end

node_spa -->|"boots"| node_client_composition
node_client_composition -->|"uses"| node_client_api
node_client_composition -->|"provides"| node_auth_context
node_client_api -->|"REST requests"| node_api_host
node_api_host -->|"routes to"| node_controllers
node_api_host -->|"enforces"| node_api_auth
node_controllers -->|"invokes interfaces"| node_modules
node_controllers -->|"admin operations"| node_admin_pipeline
node_admin_pipeline -->|"assembles season data"| node_season_assembler
node_admin_pipeline -->|"calculates ratings and predictions"| node_proprietary_algorithms
node_admin_pipeline -->|"writes drafts and publication"| node_sqlite
node_admin_pipeline -->|"writes predictions"| node_prediction_data
node_grading -->|"reads and grades"| node_prediction_data
node_modules -->|"reads published snapshots"| node_sqlite
node_analytical_views -->|"derives from published data"| node_sqlite
node_modules -->|"serves analysis"| node_analytical_views
node_season_assembler -->|"requests source data"| node_cached_data
node_cached_data -.->|"cache miss"| node_cfb_data
node_cached_data -->|"persists cache"| node_sqlite
node_deployment -->|"deploys"| node_api_host

click node_spa "https://github.com/taylorleprechaun/cfbpollui/blob/main/src/cfbpoll-web/src/main.tsx"
click node_client_composition "https://github.com/taylorleprechaun/cfbpollui/blob/main/src/cfbpoll-web/src/App.tsx"
click node_client_api "https://github.com/taylorleprechaun/cfbpollui/blob/main/src/cfbpoll-web/src/services/api.ts"
click node_auth_context "https://github.com/taylorleprechaun/cfbpollui/blob/main/src/cfbpoll-web/src/contexts/auth-context.tsx"
click node_api_host "https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.API/Program.cs"
click node_controllers "https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.API/Controllers/RankingsController.cs"
click node_api_auth "https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.API/Extensions/AuthenticationServiceExtensions.cs"
click node_modules "https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.Core/Modules/RankingsModule.cs"
click node_admin_pipeline "https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.Core/Modules/AdminModule.cs"
click node_grading "https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.Core/Modules/PredictionGradingModule.cs"
click node_season_assembler "https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.Core/Services/SeasonDataAssembler.cs"
click node_cfb_data "https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.Core/Services/CFBDataService.cs"
click node_cached_data "https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.Core/Services/CachingCFBDataService.cs"
click node_sqlite "https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.Core/Data/RankingsData.cs"
click node_prediction_data "https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.Core/Data/PredictionsData.cs"
click node_analytical_views "https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.Core/Modules/SeasonTrendsModule.cs"
click node_deployment "https://github.com/taylorleprechaun/cfbpollui/blob/main/.github/workflows/deploy.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_spa,node_client_composition,node_client_api,node_auth_context toneBlue
class node_api_host,node_controllers,node_api_auth toneAmber
class node_modules,node_admin_pipeline,node_grading,node_proprietary_algorithms,node_analytical_views toneMint
class node_season_assembler,node_cfb_data,node_cached_data,node_sqlite,node_prediction_data toneRose
class node_deployment toneIndigo
```

## Components

### React client

- [React/Vite SPA](https://github.com/taylorleprechaun/cfbpollui/blob/main/src/cfbpoll-web/src/main.tsx): browser application · Public analysis and guarded admin routes. · `src/cfbpoll-web/src/main.tsx`
- [Routes and providers](https://github.com/taylorleprechaun/cfbpollui/blob/main/src/cfbpoll-web/src/App.tsx): client composition · Router and shared client contexts. · `src/cfbpoll-web/src/App.tsx`
- [API service layer](https://github.com/taylorleprechaun/cfbpollui/blob/main/src/cfbpoll-web/src/services/api.ts): client service · Centralizes API calls, query lifecycle, and response validation. · `src/cfbpoll-web/src/services/api.ts`
- [Auth context](https://github.com/taylorleprechaun/cfbpollui/blob/main/src/cfbpoll-web/src/contexts/auth-context.tsx): client context · `src/cfbpoll-web/src/contexts/auth-context.tsx`

### API boundary

- [ASP.NET Core API](https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.API/Program.cs): API host · Hosts versioned REST, Swagger, middleware, and dependency wiring. · `src/CFBPoll.API/Program.cs`
- [REST controllers](https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.API/Controllers/RankingsController.cs): API controllers · Translate admin and ranking requests into module calls and DTOs. · `src/CFBPoll.API/Controllers/RankingsController.cs`
- [JWT authentication](https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.API/Extensions/AuthenticationServiceExtensions.cs): API security · Authenticates protected administration operations. · `src/CFBPoll.API/Extensions/AuthenticationServiceExtensions.cs`

### Core application

- [Core modules](https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.Core/Modules/RankingsModule.cs): application layer · Interface-driven orchestration for rankings, predictions, publication, and views. · `src/CFBPoll.Core/Modules/RankingsModule.cs`
- [Admin snapshot pipeline](https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.Core/Modules/AdminModule.cs): administration module · Calculates draft rankings and predictions, publishes snapshots, and invalidates cache. · `src/CFBPoll.Core/Modules/AdminModule.cs`
- [Prediction grading](https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.Core/Modules/PredictionGradingModule.cs): application module · Grades published predictions against actual scores. · `src/CFBPoll.Core/Modules/PredictionGradingModule.cs`
- **Rating and prediction algorithms**: private submodule extension · Private git submodule requiring replacement in a fresh public clone.
- [Published analytical views](https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.Core/Modules/SeasonTrendsModule.cs): derived view modules · Builds trends and other public analysis from published snapshots and season data. · `src/CFBPoll.Core/Modules/SeasonTrendsModule.cs`

### Data and integrations

- [Season data assembler](https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.Core/Services/SeasonDataAssembler.cs): domain assembly service · Shapes upstream responses into season input for calculations. · `src/CFBPoll.Core/Services/SeasonDataAssembler.cs`
- [College Football Data client](https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.Core/Services/CFBDataService.cs): external data service · Integrates with the College Football Data API. · `src/CFBPoll.Core/Services/CFBDataService.cs`
- [Caching data service](https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.Core/Services/CachingCFBDataService.cs): cache decorator · Avoids repeated upstream season-data requests. · `src/CFBPoll.Core/Services/CachingCFBDataService.cs`
- [SQLite snapshots and cache](https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.Core/Data/RankingsData.cs): persistence · Stores ranking snapshots, predictions, visibility, and persistent cached records. · `src/CFBPoll.Core/Data/RankingsData.cs`
- [Predictions repository](https://github.com/taylorleprechaun/cfbpollui/blob/main/src/CFBPoll.Core/Data/PredictionsData.cs): module-owned data access · `src/CFBPoll.Core/Data/PredictionsData.cs`

### Operations

- [Deployment automation](https://github.com/taylorleprechaun/cfbpollui/blob/main/.github/workflows/deploy.yml): CI/CD · GitHub Actions deploys the API via PowerShell. · `.github/workflows/deploy.yml`

## Connections

- 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