🌤️ WeatherSphere

Advanced Real-Time Weather Intelligence Platform

Live Demo • Documentation • Report Bug • Request Feature

📋 Table of Contents

About
Key Features
Tech Stack
Project Structure
Getting Started
Configuration
Usage
API Integration
Contributing
License
Contact

🌍 About

WeatherSphere is a cutting-edge weather intelligence platform that delivers hyperlocal, real-time meteorological data with advanced visualization capabilities. Built with modern web technologies, it provides comprehensive atmospheric insights through interactive maps, detailed forecasts, and air quality monitoring.

🎯 Mission

To democratize access to professional-grade weather intelligence through an intuitive, fast, and reliable web application.

✨ Highlights

🚀 Lightning Fast: Built with Vite for optimal performance
🗺️ Interactive Maps: Powered by Mapbox GL JS with multiple weather layers
📱 Responsive Design: Seamless experience across all devices
🌓 Theme Support: Dark and light modes for comfortable viewing
🔐 Type Safe: Structured with modern JavaScript patterns
♿ Accessible: WCAG 2.1 AA compliant

🎯 Key Features

🌡️ Core Weather Features

✅ Real-Time Weather Data - Current conditions updated every 15 minutes
✅ 24-Hour Forecast - Hourly temperature and precipitation predictions
✅ 7-Day Extended Forecast - Weekly weather planning at a glance
✅ Location Search - Search any city worldwide with autocomplete
✅ Geolocation Support - Automatic detection of user's location

🗺️ Advanced Visualizations

✅ Temperature Maps - Global heat maps with gradient visualization
✅ Wind Patterns - Real-time wind speed and direction analysis
✅ Air Quality Index (AQI) - Pollution levels with health recommendations
✅ Cloud Coverage - Satellite-based cloud layer visualization
✅ Interactive Radar - Zoom and pan across detailed weather layers

📊 Data Analytics

✅ Historical Trends - Average temperature analysis over time
✅ Weather Alerts - Severe weather notifications
✅ UV Index - Sun exposure safety guidelines
✅ Humidity & Pressure - Detailed atmospheric metrics

🛠️ Tech Stack

Frontend

Technology	Purpose	Version
	UI Framework	18.3.1
	Build Tool	6.3.5
	Routing	7.1.3
	Animations	11.20.0
	Styling	3.4.17

Maps & Visualization

Technology	Purpose
Mapbox GL JS	Interactive mapping engine
D3.js	Data visualization library
Chart.js	Chart rendering
Leaflet	Alternative mapping solution

APIs & Data

WeatherAPI.com - Primary weather data provider
OpenWeatherMap - Air quality and supplementary data
Mapbox - Geocoding and map tiles

Development Tools

ESLint - Code linting
Prettier - Code formatting
Git - Version control

📁 Project Structure

WeatherSphere/
├── 📂 public/                  # Static assets
│   ├── logo.png
│   └── favicon.ico
│
├── 📂 src/                     # Source code
│   ├── 📂 assets/              # Images, fonts, icons
│   │   └── react.svg
│   │
│   ├── 📂 components/          # Reusable UI components
│   │   ├── 📂 Footer/
│   │   │   └── Footer.jsx
│   │   └── 📂 Navbar/
│   │       └── Navbar.jsx
│   │
│   ├── 📂 contexts/            # React Context providers
│   │   └── ThemeContext.jsx   # Dark/Light theme management
│   │
│   ├── 📂 pages/               # Route-based page components
│   │   ├── AqiMap.jsx          # Air Quality Index visualization
│   │   ├── AverageTemperature.jsx  # Historical temp analysis
│   │   ├── CloudMap.jsx        # Cloud coverage maps
│   │   ├── ErrorPage.jsx       # 404 error handling
│   │   ├── HomePage.jsx        # Landing page
│   │   ├── Root.jsx            # Main layout wrapper
│   │   ├── TemperatureMap.jsx  # Temperature heatmaps
│   │   └── WindyMap.jsx        # Wind pattern visualization
│   │
│   ├── 📂 routes/              # Routing configuration
│   │   ├── PrivateRoute.jsx    # Protected route wrapper
│   │   └── router.jsx          # Main router setup
│   │
│   ├── App.css                 # Global styles
│   ├── App.jsx                 # Root application component
│   ├── index.css               # Base CSS & Tailwind imports
│   └── main.jsx                # Application entry point
│
├── 📄 .env.example             # Environment variables template
├── 📄 .gitignore               # Git ignore rules
├── 📄 eslint.config.js         # ESLint configuration
├── 📄 index.html               # HTML template
├── 📄 package.json             # Dependencies & scripts
├── 📄 README.md                # Project documentation
├── 📄 tailwind.config.js       # Tailwind configuration
└── 📄 vite.config.js           # Vite build configuration

📂 Directory Breakdown

`/src/components/`

Reusable UI components that can be used across multiple pages.

Footer - Application footer with links and branding
Navbar - Navigation bar with theme toggle

`/src/contexts/`

React Context API providers for global state management.

ThemeContext - Manages dark/light theme preferences

`/src/pages/`

Page-level components mapped to specific routes.

HomePage - Main landing page with weather overview
TemperatureMap - Interactive temperature visualization
WindyMap - Wind speed and direction maps
AqiMap - Air quality index display
CloudMap - Cloud coverage visualization
AverageTemperature - Historical temperature trends

`/src/routes/`

Application routing configuration.

router.jsx - Defines all application routes
PrivateRoute.jsx - Authentication wrapper for protected routes

🚀 Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

Node.js (v18.0.0 or higher) - Download
npm (v9.0.0 or higher) or yarn (v1.22.0 or higher)
Git - Download

API Keys Required

WeatherAPI - Get Free API Key
Mapbox - Get Free API Key
OpenWeatherMap (Optional) - Get Free API Key

📦 Installation

Clone the repository

git clone https://github.com/MRaysa/WeatherSphere.git
cd WeatherSphere

Install dependencies
```
npm install
# or
yarn install
```

Set up environment variables

Create a .env file in the root directory:

cp .env.example .env

Add your API keys:

VITE_WEATHER_API_KEY=your_weatherapi_key_here
VITE_MAPBOX_TOKEN=your_mapbox_token_here
VITE_OPENWEATHER_API_KEY=your_openweather_key_here

Start the development server
```
npm run dev
# or
yarn dev
```
Open your browser

Navigate to http://localhost:5173

⚙️ Configuration

Environment Variables

Variable	Description	Required	Default
`VITE_WEATHER_API_KEY`	WeatherAPI.com API key	Yes	-
`VITE_MAPBOX_TOKEN`	Mapbox GL JS access token	Yes	-
`VITE_OPENWEATHER_API_KEY`	OpenWeatherMap API key	No	-

Build Configuration

The project uses Vite for building. Configuration can be modified in vite.config.js:

export default defineConfig({
  plugins: [react()],
  server: {
    port: 5173,
    host: true
  },
  build: {
    outDir: 'dist',
    sourcemap: true
  }
})

📖 Usage

Development

# Start development server
npm run dev

# Run with specific port
npm run dev -- --port 3000

# Open in browser automatically
npm run dev -- --open

Production Build

# Create production build
npm run build

# Preview production build locally
npm run preview

# Analyze bundle size
npm run build -- --mode analyze

Code Quality

# Run ESLint
npm run lint

# Fix ESLint issues automatically
npm run lint:fix

# Format code with Prettier
npm run format

🔌 API Integration

WeatherAPI.com

const fetchWeather = async (location) => {
  const response = await fetch(
    `https://api.weatherapi.com/v1/forecast.json?key=${API_KEY}&q=${location}&days=7`
  );
  return response.json();
};

Mapbox GL JS

mapboxgl.accessToken = 'YOUR_MAPBOX_TOKEN';
const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v11',
  center: [lng, lat],
  zoom: 9
});

🤝 Contributing

We welcome contributions from the community! Here's how you can help:

How to Contribute

Fork the repository
Create a feature branch
```
git checkout -b feature/AmazingFeature
```
Commit your changes
```
git commit -m 'Add some AmazingFeature'
```
Push to the branch
```
git push origin feature/AmazingFeature
```
Open a Pull Request

Development Guidelines

Follow the existing code style
Write meaningful commit messages
Add comments for complex logic
Update documentation as needed
Test your changes thoroughly

Reporting Bugs

Found a bug? Open an issue with:

Clear description
Steps to reproduce
Expected vs actual behavior
Screenshots (if applicable)
Environment details

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2025 WeatherSphere

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...

📧 Contact

Project Maintainer - MRaysa

GitHub: @MRaysa
Project Link: https://github.com/MRaysa/WeatherSphere
Live Demo: https://weather-sphere-seven.vercel.app/

🙏 Acknowledgments

WeatherAPI.com - Weather data provider
Mapbox - Mapping platform
React - UI framework
Vite - Build tool
Vercel - Hosting platform
Icons by Heroicons

⭐ Star this repo if you find it helpful!

Made with ❤️ by MRaysa

Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
public		public
src		src
.gitignore		.gitignore
README.md		README.md
eslint.config.js		eslint.config.js
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
vite.config.js		vite.config.js

MRaysa/WeatherSphere

Folders and files

Latest commit

History

Repository files navigation