Events & Calendar System
Relevant source files
The following files were used as context for generating this wiki page:
The Events & Calendar System provides a comprehensive framework for managing and displaying community activities within the Lou Gehrig Fan Club (LGFC) platform. It encompasses administrative interfaces for event creation, public-facing monthly calendar views, and "Upcoming Events" widgets integrated across the site.
The system relies on a unified data structure for events, utilizing Next.js client components for interactive UI elements and Cloudflare Pages Functions for backend API interactions. These components facilitate a "live" schedule experience by fetching real-time data from a D1 database.
Sources: src/app/admin/events/page.tsx, src/components/CalendarSection.tsx:162-164, context.md
Architecture and Data Flow
The system is split into an administrative management layer and a multi-tiered public display layer. Data flows from the administrative UI through API endpoints into a persistent storage layer, which is then queried by various frontend components.
System Interaction Flow
The following diagram illustrates the lifecycle of an event from creation by an administrator to its display on the public calendar.
The flow ensures that administrative actions immediately update the data available to public components like the CalendarSection or EventsMonth.
Sources: src/app/admin/events/page.tsx:43-58, src/components/CalendarSection.tsx:166-175, src/components/calendar/EventsMonth.tsx:82-95
Component Overview
The system utilizes several specialized components to display event data in different contexts:
| Component | Purpose | Location |
|---|---|---|
CalendarSection | Main interactive grid calendar with day selection and event details. | src/components/CalendarSection.tsx |
EventsMonth | A paginated monthly list view of events with Prev/Next navigation. | src/components/calendar/EventsMonth.tsx |
EventsNextTen | A simple list showing the next 10 upcoming events. | src/components/calendar/EventsNextTen.tsx |
EventsBanner | A high-level promotional banner for upcoming events (utilizes mock data). | src/components/EventsBanner.tsx |
AdminEventsPage | Management dashboard for administrators to create and list events. | src/app/admin/events/page.tsx |
Sources: src/components/CalendarSection.tsx:120, src/components/calendar/EventsMonth.tsx:75, src/components/calendar/EventsNextTen.tsx:16, src/components/EventsBanner.tsx:28, src/app/admin/events/page.tsx:16
Data Models and Normalization
The system defines a strict EventRow (or CalendarEvent) type to ensure consistency across the application.
Event Data Structure
The fields below represent the standard properties of an event object used in the system.
| Field | Type | Description |
|---|---|---|
id | number | Unique identifier for the event. |
title | string | Name of the event. |
start_date | string | Primary date in YYYY-MM-DD format. |
end_date | string (opt) | Optional conclusion date for multi-day events. |
location | string (opt) | Physical or virtual venue. |
host | string (opt) | Organizer or host name. |
fees | string (opt) | Cost information. |
description | string (opt) | Detailed text about the event. |
external_url | string (opt) | Link to external registration or details. |
Sources: src/components/CalendarSection.tsx:6-16, src/components/calendar/EventsMonth.tsx:5-15
Normalization Logic
The EventsMonth component implements a normalizeEvent function to handle variations in API responses (e.g., mapping starts_at to start_date) and to provide safe defaults for missing fields.
function normalizeEvent(raw: unknown): CalendarEvent | null {
if (!isRecord(raw)) return null;
const id = asNumber(raw.id);
const title = asString(raw.title) ?? null;
const start_date = asString(raw.start_date) ?? asString(raw.starts_at) ?? null;
// ... validation and mapping
if (id === null || !title || !start_date) return null;
return { id, title, start_date, ... };
}
Sources: src/components/calendar/EventsMonth.tsx:34-54
Administrative Management
The administrative interface allows for simple CRUD operations. Administrators can create events via the /api/admin/events/create endpoint.
Logic Flow for Admin Creation
The admin page reuses the public listing endpoint /api/events/month to display existing events while using a specialized admin endpoint for mutations.
Sources: src/app/admin/events/page.tsx:26-30, src/app/admin/events/page.tsx:43-63
Public Display Logic
Interactive Calendar Grid
The CalendarSection generates a standard 7-column grid of days. It uses a calendarCells helper function to pad the start and end of the month grid to maintain visual alignment.
function calendarCells(year: number, month0: number): Array<{ key: string; dayNum: number; inMonth: boolean }> {
const first = new Date(year, month0, 1);
const startPad = first.getDay();
// ... padding logic
for (let day = 1; day <= lastDate; day++) {
cells.push({ key: ymdKey(year, month0, day), dayNum: day, inMonth: true });
}
// ... end padding logic
return cells;
}
Days with events are highlighted with an eventDot class, and selecting a day updates the selectedEvents view.
Sources: src/components/CalendarSection.tsx:60-88, src/components/CalendarSection.tsx:265-275
Upcoming Events Logic
The EventsNextTen component and CalendarSection fetch upcoming events using the /api/events/next endpoint with a limit parameter.
Conclusion
The Events & Calendar System provides a robust mechanism for tracking club activities. By leveraging standardized data models and flexible API endpoints, the system supports both high-level summaries (banners and "Next 10" lists) and deep-dive interactive calendars, all while maintaining an administrative path for content updates.