SameDay

A simple, focused web application that compares weather data for any given date across multiple years. Select a date and location to see how the weather varied on that same date over the past years.

Features

Core Functionality

Simple Inline Controls: Clean, minimal interface with inline buttons for quick access
- Today/Date Dropdown: Quick access to today's date or select a custom date
- City Dropdown: Searchable list of cities with quick-select options
- Year Range Dropdown: Choose from 10y, 20y, 30y, or 50y ranges
- Random Button: Instantly randomize date, location, and year range
- Search Modal: Comprehensive search with all inputs in one place
Historical Comparison: View temperature, conditions, and precipitation for the selected date across multiple years
Multiple View Modes:
- Grid View: Card-based layout with individual year cards
- Table View: Tabular data display
- Chart View: Visual chart/graph representation with color-coded bars
- Emoji View: Canonical format display matching share copy

UI/UX Features

Single Column Layout: Clean, focused vertical layout
Responsive Design: Optimized for desktop and mobile devices (breakpoints: 768px, 640px, 480px, 375px)
Dynamic Weather Colors: Entire UI color scheme adapts to current weather conditions
- Temperature-based hue mapping (cold→blue/purple, warm→orange/red)
- Weather condition modifiers (sunny=vibrant, rainy=muted)
- Smooth transitions when changing selections
Dark Mode: Toggle between light and dark themes with system preference detection
Temperature Units: Switch between Celsius and Fahrenheit
Loading States: Simple skeleton placeholders
Error Handling: Retry buttons and user-friendly error messages
Toast Notifications: CSS-only notifications for critical errors

Export & Share

CSV Export: Download weather comparison data
Share Feature: Copy canonical format with emoji grid to clipboard
- Format: <MM/DD> <LOCATION> <N>Y <AVG_TEMP><UNIT> + emoji grid
- Color-coded emojis show temperature deviation from average
- Emoji grid order matches card display (newest year first)
- Supports both Fahrenheit and Celsius

Special Features

White Christmas Mode: Toggle to explore Christmas Day weather history
- Automatically sets date to December 25th
- Special Christmas card view showing snow status for each year
- Snow effect animation when enabled
- Statistics showing years with/without snow
- Works in all view modes (Grid, Table, Chart, Emoji)
- Uses accurate snowfall data from Open-Meteo API
- Shows "Unknown" when snowfall data is unavailable
Mobile Swipe Gestures: Navigate between days with swipe gestures
- Swipe left to go to next day
- Swipe right to go to previous day
- Only active on mobile devices

Progressive Web App (PWA)

Installable: Add to home screen on mobile and desktop
Offline Support: Works offline after first load with service worker caching
Standalone Mode: Runs as standalone app when installed
Safe Area Support: Full iOS safe area support (notch, dynamic island, home indicator)
Service Worker: Automatic updates with Workbox
PWA Icons: 192x192 and 512x512 icons for app installation

Performance

Optimized API Calls: 90-99% reduction in API requests through batching
In-Memory Caching: 24-hour TTL cache for faster repeated queries
Fast Load Times: 5-45x faster depending on feature

Technology Stack

Frontend: React with TypeScript, Vite
Backend: Node.js with Express and TypeScript
Weather API: Open-Meteo Historical Weather API (free, no API key required)
Styling: CSS with responsive design

Prerequisites

Node.js (v18 or higher)
npm or yarn

Setup Instructions

1. Clone the Repository

git clone <repository-url>
cd SameDay

2. Backend Setup

cd backend
npm install

Create a .env file in the backend directory (optional):

PORT=3001

Note: No API key is required as the app uses the free Open-Meteo Historical Weather API.

Start the backend server:

npm run dev

The backend will run on http://localhost:3001

3. Frontend Setup

Open a new terminal:

cd frontend
npm install

Create a .env file in the frontend directory (optional, defaults to localhost:3001):

VITE_API_URL=http://localhost:3001

Start the frontend development server:

npm run dev

The frontend will run on http://localhost:5173 (or another port if 5173 is busy)

Project Structure

SameDay/
├── frontend/           # React frontend application
│   ├── src/
│   │   ├── components/ # React components
│   │   ├── utils/      # Utility functions
│   │   │   ├── weatherBackground.ts  # Dynamic color system
│   │   │   ├── exportUtils.ts        # CSV/share exports
│   │   │   ├── temperatureUtils.tsx  # Temperature conversion
│   │   │   └── trendAnalysis.ts      # Weather trend analysis
│   │   ├── App.tsx     # Main app component
│   │   ├── App.css     # App styles & dynamic backgrounds
│   │   ├── index.css   # Design system tokens
│   │   └── types.ts    # TypeScript type definitions
│   └── package.json
├── backend/            # Express backend API
│   ├── src/
│   │   ├── routes/     # API routes
│   │   ├── services/   # Weather service logic
│   │   └── server.ts   # Express server
│   └── package.json
└── README.md

API Documentation

Endpoint: GET `/api/weather/historical`

Fetches historical weather data for a specific date across multiple years.

Query Parameters:

location (required): City name or coordinates (lat,lon)
month (required): Month number (1-12)
day (required): Day number (1-31)
years (optional): Comma-separated list of years (defaults to last 10 years)

Example Request:

GET /api/weather/historical?location=New York&month=3&day=15&years=2020,2021,2022

Example Response:

{
  "data": [
    {
      "year": 2020,
      "date": "2020-03-15",
      "temperature": {
        "high": 65,
        "low": 45
      },
      "condition": "Clear",
      "precipitation": 0
    }
  ],
  "location": "New York"
}

Environment Variables

Backend (.env)

PORT: Server port (default: 3001)

Frontend (.env)

VITE_API_URL: Backend API URL (default: http://localhost:3001)

Usage

Start both the backend and frontend servers
Open your browser to the frontend URL (typically http://localhost:5173)
The app loads with "Today" and "New York" preselected
Use the inline controls to:
- Today/Date: Click to open dropdown - select "Today" or "Select Date..." for custom date
- City: Click to open dropdown - search or select from quick options
- Year Range: Click to select 10y, 20y, 30y, or 50y
- 🎲: Randomize all settings (date, location, year range)
- 🔍: Open comprehensive search modal with all inputs
Weather comparison results appear automatically when location is selected

Weather API Notes

This application uses the Open-Meteo Historical Weather API, which is free and requires no API key. The API provides historical weather data going back to 1940.

Development

Backend Scripts

npm run dev: Start development server with hot reload
npm run build: Build for production
npm start: Start production server

Frontend Scripts

npm run dev: Start development server
npm run build: Build for production
npm run preview: Preview production build

Features Included

Core Features

✅ Simplified inline control bar (Today/Date, City, Year Range, Random, Search)
✅ Date comparison across multiple years
✅ Searchable city dropdown with quick-select options
✅ Year range selection (10y, 20y, 30y, 50y)
✅ Random button for instant exploration
✅ Comprehensive search modal with all inputs

View Modes

✅ Grid view (card-based layout)
✅ Table view (tabular data)
✅ Chart view (visual charts with color-coded bars)
✅ Emoji view (canonical format matching share copy)

Export & Share

✅ CSV export functionality
✅ Share feature with canonical format and emoji grid
✅ Clipboard copy with toast notifications

UI/UX

✅ Dynamic weather-based color system (entire UI adapts to weather conditions)
✅ Dark mode support with system preference detection
✅ Temperature unit toggle (Celsius/Fahrenheit)
✅ Responsive single-column layout (mobile-optimized)
✅ Loading states with skeleton placeholders
✅ Error handling with retry buttons
✅ Toast notifications for critical errors
✅ Temperature trend analysis
✅ Accessibility features (ARIA labels, keyboard navigation)
✅ Default location setting (persisted in localStorage)
✅ Mobile swipe gestures for day navigation

Performance

✅ Optimized API calls (90-99% reduction)
✅ In-memory caching (24-hour TTL)
✅ Fast load times (5-45x faster)

PWA Features

✅ Service worker with Workbox
✅ Web app manifest
✅ PWA icons (192x192, 512x512)
✅ Offline support with API caching
✅ Safe area support for iOS devices
✅ Standalone mode support

Special Features

✅ White Christmas mode with snow detection
✅ Christmas card view for December 25th
✅ Snow effect animation
✅ Mobile swipe gestures

License

ISC

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Name		Name	Last commit message	Last commit date
.cursor/plans		.cursor/plans
.github/workflows		.github/workflows
api		api
backend		backend
frontend		frontend
.gitignore		.gitignore
DEPLOYMENT.md		DEPLOYMENT.md
DEPLOYMENT_QUICK_START.md		DEPLOYMENT_QUICK_START.md
PWA_TEST_RESULTS.md		PWA_TEST_RESULTS.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
test-pwa-checklist.md		test-pwa-checklist.md
vercel.json		vercel.json

Latest commit

History

Folders and files

Repository files navigation

SameDay

Features

Core Functionality

UI/UX Features

Export & Share

Special Features

Progressive Web App (PWA)

Performance

Technology Stack

Prerequisites

Setup Instructions

1. Clone the Repository

2. Backend Setup

3. Frontend Setup

Project Structure

API Documentation

Endpoint: GET /api/weather/historical

Environment Variables

Backend (.env)

Frontend (.env)

Usage

Weather API Notes

Development

Backend Scripts

Frontend Scripts

Features Included

Core Features

View Modes

Export & Share

UI/UX

Performance

PWA Features

Special Features

License

Contributing

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Endpoint: GET `/api/weather/historical`