WeatherTunes Documentation Wiki 🌪️🎸😎👍

WeatherTunes is a React-based web application that combines weather data with music streaming. This documentation provides comprehensive technical guidance for developers working with the codebase.

Quick Start

New to web development? React applications use components as building blocks that manage their own state and render UI elements. WeatherTunes follows modern React patterns with TypeScript for type safety.

• First time setup: Getting Started
• Development environment: Development Setup
• System architecture: Architecture Overview

Documentation Structure

Architecture

• Overview - System design and technology stack
• Components - React component organization and patterns
• State Management - Data flow and React Context usage

Features

• Weather System - OpenWeatherMap API integration
• Settings System - User preferences and localStorage
• Video Backgrounds - Dynamic weather-based videos
• Music Integration - Spotify Web API preparation

Development

• Getting Started - Installation and first run
• Setup Guide - Environment configuration and tools

Backend Integration

• API Requirements - Spotify Web API specifications

Implementation Status

Production Ready Features

The following features are fully implemented and functional:

• Weather data integration: Real-time weather using OpenWeatherMap API
• Location-based settings: Automatic temperature and speed unit selection
• Responsive design: Mobile-first layout with glassmorphism styling
• Video backgrounds: 24 weather and time-specific background videos
• TypeScript coverage: Complete type safety throughout the application

UI Components Ready for Backend

These components have complete user interfaces but display placeholder data:

• Music player controls: Play, pause, skip buttons in CurrentlyPlaying component
• Queue display: UpNext component shows mock upcoming tracks
• User authentication: Login page and navigation bar login button

Components Using Placeholder Data

• Music player controls: CurrentlyPlaying component displays static music data
• Queue display: UpNext component shows hardcoded track list
• Authentication flow: Login page exists but connects to no backend service

Technology Stack

WeatherTunes uses modern web development technologies:

• React 19.1.0: Component-based UI library for building user interfaces
• TypeScript 5.8.3: JavaScript with static type definitions for better developer experience
• Vite 6.3.5: Build tool that provides fast development server and optimized production builds
• Tailwind CSS 4.1.8: Utility-first CSS framework for rapid styling
• Radix UI: Accessible component primitives for complex UI elements

Development Tools

• ESLint: Code linting for consistent style and error detection
• Prettier: Code formatting for consistent appearance
• React Router: Client-side routing for single-page application navigation

Project Structure

The codebase follows standard React application organization:

src/
├── components/     # Reusable UI components
├── contexts/       # React Context providers for global state
├── hooks/          # Custom React hooks for business logic
├── lib/            # Utility functions and API clients
├── pages/          # Top-level page components
├── types/          # TypeScript type definitions
└── assets/         # Static files including background videos

Environment Requirements

WeatherTunes requires specific environment variables and development tools:

• Node.js 18+: JavaScript runtime for development and build processes
• OpenWeatherMap API key: Required for weather data (set as VITE_PUBLIC_OPENWEATHER_API_KEY)
• Modern web browser: Supports ES2020 features and CSS backdrop-filter

Documentation Philosophy

This documentation explains both project-specific implementation and general web development concepts. Each section includes working code examples extracted from the actual codebase.

For rapid codebase context during development, reference the Codebase Index.