D2. Design Document

Platform Selection

Given that this is the project’s current tech stack, we agreed it’s best to retain the bulk of the existing tech stack rather than making unnecessary changes. In addition to the obvious duplication of effort in overhauling everything, we believe the following is also the best possible configuration of technologies after comparing with alternatives. 

Frontend: React (with Vite) and Mantine

Justification:

• React’s component-based architecture and Context API efficiently manage the complex, highly interactive global state required for the dashboard and URL-syncing.

• Mantine provides a comprehensive, pre-built, and accessible component library, significantly speeding up UI development compared to writing custom CSS.

• A key specification of the client entails changing the UI for a few features. Changing the current tools would require an overhaul, which is unnecessary. 

Alternatives:

• Angular: Heavier framework; unnecessary for a highly visual, single-page dashboard.

• Plain HTML/CSS/JS: Would quickly become unmaintainable given the complex state management, data fetching, and URL parameter syncing required.

• Tailwind CSS (instead of Mantine): Requires building UI components completely from scratch; Mantine’s pre-built elements (modals, complex inputs) save significant development time.

Backend / Data Processing: Python Scripts via GitHub Actions

Justification:

• Python offers robust data manipulation libraries (like pandas) that are ideal for aggregating and standardizing the complex CSV data from various CDC Hubverse repositories.

• Utilizing GitHub Actions for nightly cron jobs eliminates the need for a dedicated backend server, reducing infrastructure costs to zero.

• Generating static JSON files pre-computationally ensures lightning-fast frontend load times by removing database query latency.

Alternatives:

• Node.js/Express Server: Would require persistent hosting costs and introduce runtime latency when querying and aggregating forecast data on the fly.

• R: While an R script exists for parity in this project, Python is more universally adopted for full-stack build orchestration and general-purpose pipeline scripting.

• AWS Lambda: Overkill and introduces potential cold-start latency; a daily static generation suffices.

Database / Storage: Pre-computed Static JSON & LocalStorage

Justification:

• Storing aggregated data as static JSON files in the public directory guarantees high availability, version control, and immutability.

• Browser LocalStorage perfectly handles user-specific state (like Forecastle game submissions) while protecting user privacy and avoiding backend compliance issues.

Alternatives:

• PostgreSQL / MySQL: Requires a persistent server, increasing costs and maintenance for data that is essentially static and read-only for 24-hour periods.

• MongoDB: While excellent for JSON documents, it still requires a runtime connection and database hosting, which defeats the zero-cost static architecture.

• Firebase: Great for real-time data syncing, but unnecessary for the main dashboard and overkill for simple tournament leaderboards.

Data Visualization: Plotly.js

Justification:

• Offers out-of-the-box support for complex scientific charting, including the confidence intervals (quantile bands) that are strictly required for epidemiological forecasts.

• Provides high interactivity (zoom, pan, hover tooltips, legend toggling) with minimal custom configuration.

• Handles responsive resizing automatically for both mobile and desktop viewing environments.

Alternatives:

• D3.js: Highly customizable but has a massive learning curve; requires building standard chart features (like axes, legends, and tooltips) completely from scratch.

• Chart.js: Easier to use for basic charts, but less robust for rendering complex, multi-trace scientific data with asymmetric confidence intervals.

• Recharts: Built specifically for React, but can struggle with performance when rendering the sheer volume of data points and complex statistical bands needed for RespiLens.