Weekly Matchups
Relevant source files
The following files were used as context for generating this wiki page:
The Weekly Matchups system is a core engagement feature of the Lou Gehrig Fan Club (LGFC) website. It allows users to view and vote for their favorite historical photos or items in a head-to-head comparison format. The system is designed to facilitate weekly participation, tracking current votes while also displaying historical results from previous weeks.
The feature is implemented as a React client component integrated into the homepage, supported by a backend architecture utilizing Cloudflare Pages Functions for API endpoints and Cloudflare D1 for relational data storage.
Sources: src/app/page.tsx:29-33, src/components/WeeklyMatchup.tsx:1-12, context.md
Data Model and Schema
The persistence layer for Weekly Matchups is defined by two primary tables in the SQLite-based D1 database. These tables manage the scheduling of matchups and the individual votes cast by users.
Database Tables
| Table Name | Field | Type | Constraints | Description |
|---|---|---|---|---|
weekly_matchups | id | INTEGER | PRIMARY KEY | Unique identifier for the matchup |
week_start | TEXT | NOT NULL, UNIQUE | Date format YYYY-MM-DD (Monday) | |
photo_a_id | INTEGER | NOT NULL | Foreign key reference to photo A | |
photo_b_id | INTEGER | NOT NULL | Foreign key reference to photo B | |
status | TEXT | DEFAULT 'active' | Status of the week (active/closed) | |
weekly_votes | id | INTEGER | PRIMARY KEY | Unique identifier for the vote |
week_start | TEXT | NOT NULL | Associated week for the vote | |
choice | TEXT | NOT NULL | User selection ('a' or 'b') | |
source_hash | TEXT | NOT NULL, UNIQUE | Prevents duplicate voting per user/week |
Sources: migrations/0018_matchups.sql:2-20
Relationships and Indexes
The schema includes a unique index on weekly_matchups(week_start) to ensure only one matchup exists per week. Additionally, weekly_votes utilizes a unique index on (week_start, source_hash) to enforce a "one vote per user per week" policy at the database level.
Sources: migrations/0018_matchups.sql:10-21
System Architecture and Data Flow
The system operates through a cycle of fetching active matchups, submitting user votes, and retrieving real-time or historical results.
Vote Submission Flow
When a user selects a photo, the client component triggers a POST request. Upon success, the vote is recorded locally in localStorage to provide immediate UI feedback and prevent further voting attempts in the current session.
The diagram shows the logic path from a user interaction to data persistence and UI update.
Sources: src/components/WeeklyMatchup.tsx:103-121
Data Fetching Sequence
The WeeklyMatchup component initializes by fetching the current week's metadata and items. If a vote is detected in localStorage, it automatically fetches results to reveal the current standings.
The sequence diagram illustrates the conditional fetching logic based on the user's voting history.
Sources: src/components/WeeklyMatchup.tsx:64-90
API Endpoints
The system relies on specific endpoints to manage state and data retrieval.
| Endpoint | Method | Description |
|---|---|---|
/api/matchup/current | GET | Returns the items (Photo A and Photo B) and week_start for the active week. |
/api/matchup/vote | POST | Submits a vote. Requires week_start and choice ('a' or 'b'). |
/api/matchup/results | GET | Returns current vote totals for a specific week and data for the last_week (winner/totals). |
Sources: src/components/WeeklyMatchup.tsx:17-43, functions/api/matchup/results.ts:1-12
Results Logic
The results API calculates the winner of the previously closed week. A tie is declared if the vote counts for 'a' and 'b' are equal.
// Example winner calculation in results.ts
const winner = la === lb ? 'tie' : (la > lb ? 'a' : 'b');
last_week = { week_start: lws, totals: { a: la, b: lb }, winner };
Sources: functions/api/matchup/results.ts:37-43
Frontend Implementation
The UI is implemented as a responsive grid containing two "photo frames." It uses a specific styling system to maintain design consistency with the "V6" project specification.
Component Features
- Loading State: Displays a "Loading matchup..." message for up to 10 seconds before timing out.
- Photo Rendering: Photos are displayed in a centered frame with
object-fit: containto preserve aspect ratios. - Result Revelation: Vote totals are only shown after a user has voted.
- Historical Context: Displays the winner and totals of the last closed week (e.g., "Winner: A").
Sources: src/components/WeeklyMatchup.tsx:45-62, src/components/WeeklyMatchup.tsx:158-212
Styling Constants
The layout uses a standard grid structure and specific color tokens defined in the project's global CSS.
| Class/Style | Attribute | Value |
|---|---|---|
gridStyle | gridTemplateColumns | repeat(2, minmax(0, 1fr)) |
photoFrameStyle | height | 440px |
.title-lgfc | color | var(--lgfc-blue) (#0033cc) |
.matchup .tile | border | 1px solid var(--lgfc-border-light) |
Sources: src/components/WeeklyMatchup.tsx:45-62, src/styles/weekly.css:20-30, fix_v6_finalize.sh:31-35
Summary
The Weekly Matchups feature provides a robust mechanism for fan engagement through a scheduled voting system. By combining Cloudflare D1's relational capabilities with a stateful React frontend, the system ensures data integrity (preventing duplicate votes) while delivering a performant, responsive user experience. The integration of historical results further incentivizes recurring weekly visits by club members.