Calendar Invite Server (CIS) Architecture

NFL Game Calendar: System Design Document

This document provides the formal system design for the NFL Game Calendar platform. It serves as a technical blueprint for development teams and stakeholders, outlining the core architecture, data models, and operational principles that govern the system.

https://nfl2025.31events.com/docs/architecture

1.0 System Overview and Core Principles

This section outlines the system’s fundamental purpose and the core architectural principles that guide its design, ensuring reliability, consistency, and interoperability. The primary objective of the system is to represent every NFL game as a consistent, portable, and automatically updatable calendar-native (iCalendar, or ICS) event using the Calendar Invite Server (CIS).

The following guiding principles govern the design:

1. Consistency, Uniform fields, and a standardized data structure are mandated for every event. This ensures that all calendar clients can reliably parse event information, resulting in a predictable and accurate display for the end-user.

2. Portability: The system exclusively uses the standards-compliant iCalendar (ICS) format. This guarantees that generated calendar invites are compatible with all major calendar systems, including Google Calendar, Microsoft Outlook, and Apple Calendar, without requiring platform-specific logic.

3. Updatability: A core feature of the system is the ability to propagate changes to users’ calendars. This ensures that critical updates—including time changes, flexing, and cancellations—are automatically propagated to subscribed calendars, maintaining data accuracy long after the initial invitation is accepted.

These principles inform a concrete system architecture designed for reliability and scalability, which is detailed in the following sections.

2.0 High-Level System Architecture

Understanding the end-to-end data flow is crucial for developers and stakeholders. This section provides a high-level overview of the system’s components, illustrating the data journey from its raw source to its final presentation in the user-facing application.

The system is composed of three distinct layers, each with a specific responsibility in the data lifecycle:

• Data Ingestion Layer

  • Authoritative Data Sources (JSON files, Game Feeds)

• Data Processing & Persistence Layer

  • Quality Gates (Validation, De-duplication, Enrichment)

  • Normalization Engine

  • Calendar Invite Server (CIS) - Canonical Event Store

• Presentation Layer

  • API Endpoints (GET-only)

  • Frontend Vue 3 SPA (Client-side Rendering)

This architectural overview provides the context for a more detailed examination of the data sources and processing logic that underpin the system.

3.0 Data Ingestion and Processing

The integrity and reliability of the entire system depend on well-defined data sources and rigorous quality control during ingestion. This section details the authoritative sources of game data and the automated quality gates that ensure only validated and enriched data is persisted.

3.1 Authoritative Data Sources

The system aggregates data from multiple structured sources to build a complete and context-rich representation of each game.

3.2 Data Quality Gates

Before any data is persisted, it must pass through a series of automated checks. These gates are critical for maintaining system integrity and preventing data corruption.

1. Schema Checks: Each incoming record is validated against a strict schema to confirm the presence of all required fields. Records failing this check are rejected, preventing incomplete data from being entered into the system.

2. De-duplication: To prevent duplicate entries, a composite key comprising the game date, home team, and away team is used to uniquely identify each matchup. This composite key strategy is critical for idempotent data ingestion, preventing the creation of ambiguous duplicate events if a game feed is processed multiple times.

3. Automatic Enrichment Once validated, the raw game data is enriched with contextual information. This includes adding the correct week number (derived from nflweeks.json) and associated team metadata (from teamData.json) to the event record.

After passing through these quality gates, the processed data is ready for the critical step of normalization.

4.0 Data Model and Normalization Strategy

A standardized, normalized data model is the cornerstone of the system. This model ensures that all game data is structured according to iCalendar specifications, allowing it to be reliably interpreted by any compatible calendar client.

The NFL Demo site is designed for third-party vendors to use for promotions

4.1 Standardized Event Schema

Every game event is transformed into a canonical JSON structure before being persisted. This standardized schema directly maps to iCalendar VEVENT properties.

{
  “UID”: “string”,
  “SUMMARY”: “Away (TRI) at Home (TRI) — NFL 2025 Week N”,
  “DTSTART”: “unix seconds (UTC)”,
  “DTEND”: “unix seconds (UTC)”,
  “LOCATION”: “Venue, City, ST”,
  “DESCRIPTION”: “Date + time (UTC)\nVenue\nTeam links (Home & Away)\nAdditional notes”
}

The strategic rationale behind the key fields is detailed below:

4.2 Timezone Management Strategy

To ensure game times are displayed accurately to a global audience, the system employs a robust, two-part timezone management strategy.

• Storage: All event times (DTSTART and DTEND) are persisted as UTC-normalized integers (unix seconds). This creates a single, unambiguous source of truth for event timing, independent of any specific timezone. This UTC model enables the Updatability principle; when a game time is adjusted, the new time overwrites the stored integer, and the change propagates globally to all subscribers.

• Display: The frontend application is solely responsible for rendering event times. It uses client-side libraries like Day.js or the native. Intl API to convert the UTC timestamp into the user’s local timezone, applying locale-aware formatting for a natural display.

This strategy effectively eliminates ambiguity and potential bugs related to daylight saving time drift. It simplifies the backend logic and ensures that every fan sees the kickoff time correctly in their local time zone. This standardized data model allows events to be accessed predictably via the system’s API.

5.0 API and Endpoint Design

The API serves as the formal contract between the backend Calendar Invite Server (CIS) and the frontend application. It is designed for stability, predictability, and data integrity, ensuring that the client can retrieve event data in a structured and reliable manner.

The Calendar Client is used for creating, reading, updating, and deleting data injection in the Calendar Invite Server (CIS) by sending calendar invites to an email address for ETL disassembly, storage, and insertion into the database for retrieval later by the Calendar Invite Send API Endpoint.

Mandy’s NFL Demo Site is using the same data in her account that she loaded into the Calendar Invite Server with her calendar client.

Greg, the customer, places the email in the box and receives a calendar invite in one click that utilizes the Calendar Invite REST endpoint for sending and tracking calendar invite data in the CIS Console.

The Calendar Invite Endpoint API Codes are generated, displayed, and updated in the CIS Event Dashboard for use in Web Pages, Emails, and Applications, any time event data is sent to the email drop-off box for processing.

These API codes, when invoked, send the calendar invitations to the email address specified in the API call. The Organizer’s calendar client can update the data for a Calendar Event in the CIS by modifying Calendar Invite data and saving the changes in the Calendar Client.

This forces the new data to be sent to the mailbox and updates the data fields for the calendar event UID in the CIS storage layer. If a customer already has the calendar invite from the API, the updated calendar invite will be sent to anyone with a Y or M status. It will be tracked from the customer’s calendar receipts.

5.1 UIDs and Stable Links

Durable Unique Identifiers (UIDs) and predictable URL patterns are fundamental to the system’s design. This stability is crucial for enabling several key features, including deep links that never break, reliable search engine indexing, and precise API fetches that facilitate effective caching. For data lineage and debugging, the CIS also preserves the organizer’s original UID for provenance.

The architecture mandates the following stable routing patterns:

• Game-specific links: /game/:uid

• Team pages: /team/:altName

5.2 API Endpoints

The system exposes a minimal set of GET-only endpoints for data retrieval, reflecting a read-only architectural pattern for the public-facing client.

This API design enforces a strong data integrity model. All data-retrieving APIs are exclusively GET request-based. The CIS does not expose POST or UPDATE APIs to the frontend. This deliberate choice reinforces the Organizer’s Calendar as the single system of record, ensuring that event data can only be modified through the authoritative backend ingestion process, not by client-side actions.

The frontend architecture is designed to consume this API efficiently and present the data to the user.

The Well-crafted Calendar Invite sent by the API Endpoint

6.0 Frontend Architecture (Vue 3 SPA)

The frontend is a Vue 3 Single-Page Application (SPA) architected to provide a fast, responsive, and trustworthy user experience. Its primary responsibilities are to facilitate game discovery, display event details accurately, and provide seamless integration with the user’s calendar.

The Customer uses the Email Box and clicks one button to get the Calendar Invite

6.1 Core Technologies and User Flow

The application is built with modern, efficient technologies and follows a logical user navigation pattern.

• Routing: The primary user flow is simple and intuitive, progressing from a high-level view to specific details: /(home) → /team/:altName (team schedule) → /game/:uid (game details).

• Styling: The user interface is constructed entirely with Tailwind utility classes. This approach eliminates the need for custom CSS files, promoting consistency and maintainability while ensuring a clean, responsive design.

• Date & Time Formatting: As defined in the timezone strategy, the frontend utilizes client-side libraries (Day.js or native Intl) to render all game times in a locale-aware and time zone-correct format for the end-user.

6.2 State Management and Performance

A thin and predictable state management layer is provided by Pinia stores, which handle data fetching, caching, and exposing data to UI components.

• multiple Store: This store is responsible for managing the collection of an organizer’s games. It fetches the complete list of events and exposes computed properties for sorted views (getOrgEventsSorted) and filtered views (getEventsByWeek).

• single Store: This store manages the state for individual game pages. It fetches a single game by itself UID and caches the result. This caching is crucial for enabling quick back-and-forth navigation between game pages without re-fetching data.

The application’s caching strategy is designed for performance. While the CIS remains the canonical persistence layer, the SPA caches API route results in memory. This in-memory cache is keyed by the durable UIDs described in Section 5.1, ensuring cache integrity and precise data retrieval.

This strategy minimizes redundant network requests, ensuring that UI transitions are snappy and responsive.

The ultimate goal of this architecture is to minimize friction in the user journey—from discovering a game to committing it to their personal calendar—while guaranteeing that all subsequent updates are delivered automatically and reliably.

7. Updating Data in the Calendar Invite Server

8. NFL Game Data Injection - How did Mandy do it?

NFL Demo Game Data at https://fixturedownload.com was loaded onto Mandy’s calendar and sent to the calendar invite server (CIS) using the drop-off box set up by the administrator of the AWS account.

Mandy sent the individual games from her calendar client to be processed using the email box on the calendar invite server, which serves as an API endpoint that ETLs calendar event data into the storage and database messaging pipeline that sends, tracks, and updates calendar invites sent by the API in Web, Email, and Apps.