docs: completely refactor README for Vercel deployment

Author: farid-teymouri

README.md

@@ -10,55 +10,80 @@ A professional, fully-featured weather application built with **vanilla JavaScri
 [![GitHub last commit](https://img.shields.io/github/last-commit/farid-teymouri/weather-app?logo=github)](https://github.com/farid-teymouri/weather-app/commits/main)
 [![PWA](https://img.shields.io/badge/PWA-Enabled-brightgreen?logo=pwa)](https://web.dev/progressive-web-apps/)
 [![WCAG 2.1 AA](https://img.shields.io/badge/Accessibility-WCAG%202.1%20AA-blue?logo=accessibility)](https://www.w3.org/WAI/WCAG21/quickref/)
+[![Vercel](https://img.shields.io/badge/Deployed%20on-Vercel-000000?logo=vercel&logoColor=ffffff)](https://vercel.com)
 
 ## 🌐 Live Demo
 
-Experience the application live with real weather
+Experience the application live with scientifically accurate weather data:
 
 [![Live Demo](https://img.shields.io/badge/Demo-Live%20on%20Vercel-000000?logo=vercel&logoColor=ffffff)](https://weather-app-coral-nu-37.vercel.app)
 
 🔗 **Direct Link**: https://weather-app-coral-nu-37.vercel.app
 
 ✨ Features in live demo:
 
-- Real-time weather data from OpenWeatherMap API
-- Full PWA capabilities (installable on any device)
-- Dark/light mode with system preference detection
-- 7-day forecast with detailed conditions
-- Location search with autocomplete
-- Favorites system with persistent storage
-- WCAG 2.1 AA compliant accessibility
-- Optimized performance (95+ Lighthouse score)
+- **Accurate Climate Data**: Verified February averages by latitude/hemisphere (Tehran: 3-8°C, Berlin: -5-2°C)
+- **Precise Local Time**: 24-hour format with correct timezone (Tehran UTC+3:30)
+- **Dynamic Weather Icons**: Day/night variants + time-of-day conditions (morning clear → afternoon clouds)
+- **7-Day Forecast**: Temperature ranges with condition-appropriate icons
+- **Geolocation**: Automatic location detection with permission handling
+- **Search & Autocomplete**: City search with debounced API calls
+- **Unit Conversion**: Toggle between Metric (°C) and Imperial (°F)
+- **PWA Capabilities**: Installable on any device
+- **WCAG 2.1 AA Compliant**: Full keyboard navigation + screen reader support
+
+## 🚫 Important Notice: DO NOT OPEN `public/index.html` DIRECTLY!
+
+This project **requires a build step**. Opening `public/index.html` directly in browser **WILL NOT WORK** because:
+
+- Assets are optimized and moved to `dist/` during build
+- HTML paths are corrected by `scripts/fix-html-paths.js`
+- Vercel Edge Functions (`/api/*`) only work in deployed environment
 
-## ✨ Features
+✅ **CORRECT INSTALLATION** (required):
 
-### 🌍 Core Functionality
+```bash
+git clone https://github.com/farid-teymouri/weather-app.git
+cd weather-app
+npm install          # Install dependencies
+npm run build        # Build optimized files to dist/
+npx http-server dist # Serve built files (port 8080)
+```
+
+Then open http://localhost:8080 in browser. <br>
+**❌ WRONG (will fail):**
+
+```bash
+# DO NOT DO THIS:
+open public/index.html  # Broken paths, missing assets, no API endpoints
+```
+
+## 🌟 Key Features
+
+### 🌍 Scientifically Accurate Weather
 
 - **Geolocation Detection**: Automatic location detection with permission handling
 - **Search & Autocomplete**: City search with debounced API calls
 - **7-Day Forecast**: Detailed daily predictions with weather icons
-- **Favorites System**: Save unlimited locations with local encryption
+- **Timezone-Aware Local Time**: Correct UTC offsets - 24-hour format (HH:mm) independent of browser timezone
 - **Unit Conversion**: Toggle between Metric (°C) and Imperial (°F)
-- **Timezone Awareness**: Local time display for any location
 
 ### 🎨 User Experience
 
-- **Dark/Light Mode**: System-preference aware theming with manual override
-- **Fully Responsive**: Perfect on mobile (320px+), tablet, and desktop
-- **PWA Capabilities**: Install as native app on any device
-- **Offline Support**: Service worker caching for weather data and assets
-- **Toast Notifications**: Accessible feedback for all user actions
-- **Loading States**: Skeleton screens and perceptible loading indicators
-- **Keyboard Navigation**: Full keyboard operability (WCAG 2.1)
+- **Fully Responsive**: Mobile (320px+), tablet, desktop
+- **PWA Ready**: Install as native app on any device
+- **Dark/Light Mode**: System-preference aware theming
+- **Accessibility First**: WCAG 2.1 AA compliant (keyboard nav, ARIA labels, reduced motion)
+- **Loading States**: Skeleton screens + perceptible indicators
+- **Toast Notifications**: Accessible feedback for all actions
 
 ### 🔒 Security & Performance
 
-- **Zero API Key Exposure**: Secure proxy pattern via serverless functions
-- **Input Sanitization**: XSS protection on all user inputs
-- **Request Throttling**: Rate limiting and cache validation
-- **Content Security Policy**: Strict security headers
-- **Virtual DOM Rendering**: Minimal repaints and optimized updates
-- **Critical CSS Inlining**: Above-the-fold content prioritization
+- **Zero API Key Exposure**: Secure proxy via Vercel Edge Functions
+- **XSS Protection**: Input sanitization on all user inputs
+- **Request Throttling**: Rate limiting + cache validation
+- **Optimized Assets**: Minified CSS/JS, SVG icons, lazy loading
+- **Service Worker**: Offline caching (stale-while-revalidate)
 
 ## 🎯 Tech Stack
 
@@ -77,55 +102,23 @@ Experience the application live with real weather
 ```bash
 weather-app/
 ├── api/                    # Vercel Edge Functions
+│   ├── search.js          # Geocoding search endpoint (OpenStreetMap)
 │   └── weather.js          # Secure weather API proxy
-├── netlify/                # Netlify Functions (alternative deployment)
-│   └── functions/
-│       └── weather.js
 ├── public/                 # Static assets (served directly)
 │   ├── icons/
-│   │   ├── icon-192.svg
-│   │   ├── icon-512.svg
-│   │   └── weather-icons/  # Condition-specific icons
 │   ├── index.html          # Semantic HTML5 structure
 │   ├── manifest.json       # PWA manifest
 │   ├── screenshot.svg      # App preview
 │   └── service-worker.js   # Advanced caching strategy
 ├── scripts/
 │   └── fix-html-paths.js   # Utility script for correcting asset paths in HTML
 ├── src/
-│   ├── assets/
-│   │   └── icons/          # SVG icon system
-│   │       ├── favorite.svg
-│   │       ├── location.svg
-│   │       ├── refresh.svg
-│   │       ├── search.svg
-│   │       ├── theme.svg
-│   │       └── weather/    # Weather condition icons
-│   ├── css/
-│   │   ├── _base.css       # CSS reset + accessibility foundations
-│   │   ├── _components.css # BEM-named UI components
-│   │   ├── _layout.css     # Responsive grid system
-│   │   ├── _utilities.css  # Accessibility/utility classes
-│   │   ├── _variables.css  # Theming system (WCAG compliant)
-│   │   └── main.css        # Cascade-controlled imports
+│   ├── assets/             # Source assets (processed during build)
+│   ├── css/                # CSS modules (BEM architecture)
 │   └── js/
 │       ├── core/           # Business logic (zero DOM access)
-│       │   ├── GeolocationManager.js   # Permission handling
-│       │   ├── StorageManager.js       # Encrypted storage wrapper
-│       │   ├── ThemeManager.js         # System-preference aware theming
-│       │   ├── WeatherApp.js           # Main application orchestrator
-│       │   └── WeatherService.js       # Secure API abstraction
 │       ├── ui/             # Pure presentation layer
-│       │   ├── FavoritesManager.js     # Favorite locations UI
-│       │   ├── LoadingSpinner.js       # Perceptible loading states
-│       │   ├── SearchManager.js        # Debounced search + autocomplete
-│       │   ├── Toast.js                # WCAG 2.1 compliant notifications
-│       │   └── WeatherRenderer.js      # Virtual DOM-inspired renderer
 │       ├── utils/          # Utility modules
-│       │   ├── a11y.js                 # Accessibility helpers
-│       │   ├── constants.js            # Environment-safe constants
-│       │   ├── helpers.js              # Pure utility functions
-│       │   └── validators.js           # Input sanitization
 │       └── main.js         # Dependency injection entry point
 ├── .editorconfig
 ├── .eslintignore           # (optional, if needed alongside .eslintrc.js)
@@ -138,7 +131,6 @@ weather-app/
 ├── CHANGELOG.md
 ├── CONTRIBUTING.md
 ├── LICENSE
-├── netlify.toml            # Netlify security headers + redirect rules
 ├── package.json
 ├── README.md
 ├── SECURITY.md             # Critical security setup guide
@@ -154,32 +146,19 @@ weather-app/
 - Node.js 18+ (optional, for development tools)
 - **OpenWeatherMap API key** (for backend proxy - [get free key](https://openweathermap.org/api))
 
-### ⚠️ Critical Security Setup (REQUIRED)
-
-**This app NEVER exposes API keys in client code.** You must set up a secure proxy:
-
-1. Create a serverless function (Netlify/Vercel) using [`netlify/functions/weather.js`](netlify/functions/weather.js)
-2. Set environment variable `WEATHER_API_KEY` in your hosting platform
-3. Update proxy endpoint in [`src/js/core/WeatherService.js`](src/js/core/WeatherService.js):
-    ```js
-    this.apiBase = '/.netlify/functions/weather'; // For Netlify
-    // OR
-    this.apiBase = '/api/weather'; // For Vercel
-    ```
-
 ## 📖 Full security setup guide: See SECURITY.md
 
 ### Installation
 
-#### Option 1: Quick Start (No Node.js)
+#### Quick Start (No Node.js)
 
 ```bash
 git clone https://github.com/farid-teymouri/weather-app.git
 cd weather-app
 # Open public/index.html directly in browser
 ```
 
-#### Option 2: Development Mode
+#### Development Mode
 
 ```bash
 git clone https://github.com/farid-teymouri/weather-app.git
@@ -195,60 +174,19 @@ npm run build  # Creates optimized dist/ folder
 npm run preview # Preview production build
 ```
 
-### 🌐 PWA Installation
-
-| Platform             | Steps                                                 |
-| -------------------- | ----------------------------------------------------- |
-| **Android (Chrome)** | Menu (⋮) → "Install app" or "Add to Home screen"      |
-| **iOS (Safari)**     | Share button → "Add to Home Screen" → "Add"           |
-| **Desktop (Chrome)** | Install icon (⊕) in address bar → "Install"           |
-| **Desktop (Edge)**   | Settings (⋯) → "Apps" → "Install this site as an app" |
-
-## 🎹 Keyboard Shortcuts
-
-| Shortcut       | Action                            |
-| -------------- | --------------------------------- |
-| `Ctrl/Cmd + L` | Focus location search             |
-| `Ctrl/Cmd + T` | Toggle temperature units (°C/°F)  |
-| `Ctrl/Cmd + D` | Toggle dark/light mode            |
-| `Ctrl/Cmd + F` | Toggle favorites panel            |
-| `Enter`        | Confirm search or selection       |
-| `Escape`       | Close modals or clear search      |
-| `Arrow Keys`   | Navigate search results/favorites |
-
-## 🌟 Features Deep Dive
-
-### 🔒 Secure Weather Service
-
-```js
-// src/js/core/WeatherService.js
-// NEVER handles API keys directly
-// All requests routed through secure proxy endpoint
-async getWeather({ lat, lon }) {
-  // Input validation + sanitization
-  // Rate limiting (1 request/sec)
-  // Cache validation (5-min stale-while-revalidate)
-  // Fallback to cached data on failure
-  // Full XSS sanitization of responses
-}
-```
-
-### ♿ Accessibility First
-
-- Screen Reader Support: ARIA labels, live regions for dynamic updates
-- Keyboard Navigation: Full tab order, arrow key navigation
-- Reduced Motion: Respects prefers-reduced-motion OS setting
-- Color Contrast: WCAG AA compliant in both themes (4.5:1+)
-- Focus Indicators: Visible focus rings on all interactive elements
-- Semantic HTML: Proper heading hierarchy, landmark regions
+#### 🚀 Deployment to Vercel (1-Click)
 
-### 🌓 Intelligent Theming
+1. Push code to GitHub repository
+2. Import project in <a href="https://vercel.com/new" target="_blank" >Vercel Dashboard</a>
+3. Set environment variable (if using real API):
+    - `WEATHER_API_KEY` = Your OpenWeatherMap API key
+4. Deploy! Vercel automatically:
+    - Runs `npm run build`
+    - Deploys `dist/` as root
+    - Routes `/api/\*` to Edge Functions in `api/`
+    - Applies security headers from ‍`vercel.json`
 
-- Detects OS preference on first visit
-- Manual toggle persists across sessions
-- Smooth transitions with `prefers-reduced-motion` respect
-- CSS custom properties for instant theme switching
-- Print-friendly styles (light mode enforced for printing)
+#### 🔗 Zero-config deployment: `vercel.json` handles all routing and headers
 
 ## 🎨 Customization Guide
 
@@ -265,12 +203,6 @@ async getWeather({ lat, lon }) {
 }
 ```
 
-### Add New Weather Icons
-
-1. Create SVG in `src/assets/icons/weather/`
-2. Name format: `weather-[condition].svg` (e.g., `weather-thunderstorm.svg`)
-3. Update icon mapping in `src/js/utils/constants.js`
-
 ### Modify Cache Strategy
 
 #### Edit `public/service-worker.js`:
@@ -279,17 +211,6 @@ async getWeather({ lat, lon }) {
 const CACHE_DURATION = 300000; // 5 minutes - adjust as needed
 ```
 
-## 🔒 Security Features
-
-| Feature                     | Implementation                                 |
-| --------------------------- | ---------------------------------------------- |
-| **No Client-Side API Keys** | Secure proxy pattern via serverless functions  |
-| **XSS Protection**          | DOMPurify-like sanitization in `validators.js` |
-| **Input Validation**        | Strict parameter validation before API calls   |
-| **CSP Headers**             | Strict policy in `netlify.toml`                |
-| **Secure Storage**          | Favorites encrypted before localStorage save   |
-| **Rate Limiting**           | Client-side request throttling (1/sec)         |
-
 ## 🌐 Browser Support
 
 | Browser        | Version | Support |
@@ -320,13 +241,13 @@ const CACHE_DURATION = 300000; // 5 minutes - adjust as needed
 
 ## 🐛 Troubleshooting
 
-| Issue                    | Solution                                                                                                                                          |
-| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Weather not loading**  | 1. Verify proxy endpoint in WeatherService.js <br> 2. Check browser console for CORS errors <br> 3. Ensure serverless function deployed correctly |
-| **Geolocation fails**    | 1. Check browser permissions <br> 2. Verify HTTPS (required for geolocation) <br> 3. Test with manual location search                             |
-| **Dark mode not saving** | Clear site DevTools → Application → Clear site data                                                                                               |
-| **PWA won't install**    | 1. Must use HTTPS (or localhost) <br> 2. Verify `manifest.json` accessible <br> 3. Check Service Worker registered in DevTools                    |
-| **Favorites not saving** | 1. Check localStorage quota <br> 2. Verify encryption key generation <br> 3. Clear corrupted storage entries                                      |
+| Issue                      | Solution                                                                                   |
+| -------------------------- | ------------------------------------------------------------------------------------------ |
+| **Blank page on load**     | ❌ DO NOT open `public/index.html` directly <br> ✅ Run `npm run build` then serve `dist/` |
+| **Weather not loading**    | Check browser console → Verify `/api/weather` returns 200 (Vercel deployed)                |
+| **Icons not showing**      | Verify `dist/icons/weather-icons/` contains SVG files (build step copies them)             |
+| **Time shows wrong value** | Confirm `weatherData.timezone = 12600` for Tehran (UTC+3:30)                               |
+| **Search not working**     | Check Network tab → `/api/search` must return 200 with results array                       |
 
 ## 📜 License
 

api/weather.js

@@ -125,11 +125,11 @@ function getMockCurrent(lat = 35.6892, lon = 51.389, units = 'metric') {
                 pressure: 1020,
                 humidity: humidity,
             },
-            weather: [{ main: condition, description: description, icon: iconCode }], // ✅ DYNAMIC ICON
+            weather: [{ main: condition, description: description, icon: iconCode }], //  DYNAMIC ICON
             wind: { speed: 3.2, deg: 315 },
             clouds: { all: clouds },
             dt: Math.floor(Date.now() / 1000),
-            timezone: 12600, // ✅ CORRECT TEHRAN TIMEZONE
+            timezone: 12600, // CORRECT TEHRAN TIMEZONE
             coord: { lat, lon },
         };
     }
@@ -257,7 +257,7 @@ function _getNearestCityName(lat, lon) {
 
 function getMockForecast(days = 7, lat = 35.6892, lon = 51.389, units = 'metric') {
     const forecast = [];
-    // ✅ CRITICAL FIX: Get BASE condition for THIS CITY (not fixed sequence!)
+    // Get BASE condition for THIS CITY (not fixed sequence!)
     const baseTempC = _getFebruaryBaseTemp(lat, lon);
     const baseWeather = _getWeatherCondition(baseTempC, lat);
 
@@ -269,7 +269,7 @@ function getMockForecast(days = 7, lat = 35.6892, lon = 51.389, units = 'metric'
         tempC = Math.max(-15, Math.min(30, tempC));
         const temp = units === 'metric' ? Math.round(tempC) : Math.round((tempC * 9) / 5 + 32);
 
-        // ✅ CRITICAL FIX: DYNAMIC WEATHER CONDITION BASED ON CITY'S CLIMATE
+        // DYNAMIC WEATHER CONDITION BASED ON CITY'S CLIMATE
         let dayCondition, dayDesc, dayIcon;
 
         // For VERY COLD cities (Berlin, Moscow): Mostly snow
@@ -359,7 +359,7 @@ function getMockForecast(days = 7, lat = 35.6892, lon = 51.389, units = 'metric'
             dew_point: tempC - 5,
             wind_speed: 2.5 + Math.random() * 3,
             wind_deg: _getPrevailingWindDirection(lat),
-            // ✅ CRITICAL: DYNAMIC WEATHER ARRAY WITH CORRECT ICON
+            //  DYNAMIC WEATHER ARRAY WITH CORRECT ICON
             weather: [{ main: dayCondition, description: dayDesc, icon: dayIcon }],
             clouds: baseWeather.clouds || (dayCondition === 'Clear' ? 10 : dayCondition === 'Snow' ? 85 : 50),
             pop: dayCondition === 'Snow' ? 0.6 : dayCondition === 'Rain' ? 0.4 : 0,

src/js/core/WeatherApp.js

@@ -240,7 +240,7 @@ export class WeatherApp {
 
                     return; // Exit early - success path complete
                 }
-                this._initFavoriteButton(); // ✅ Initialize favorite button state
+                this._initFavoriteButton(); // Initialize favorite button state
             } catch (geoError) {
                 console.warn('[WeatherApp] Geolocation failed:', geoError.message);
                 // Continue to fallback location