Skip to content

README.md

Latest commit

 

History

History
222 lines (175 loc) · 6.2 KB

README.md

File metadata and controls

222 lines (175 loc) · 6.2 KB
Raw

Real-Time Weather Forecasting System

A professional, real-world weather forecasting application with interactive 3D globe UI built using Java Spring Boot backend and modern frontend technologies.

🌟 Features

Core Functionality

  • Real-time weather data for any city
  • 3-day weather forecast
  • Detailed weather information (temperature, humidity, wind, pressure, etc.)
  • Weather condition icons

Interactive Globe UI

  • Rotating 3D Earth visualization using Three.js and Globe.gl
  • Click anywhere on the globe to get weather for that location
  • Smooth animations and dark space theme

Frontend Features

  • Responsive design for mobile and desktop
  • City search with real-time validation
  • Loading animations during data fetch
  • Error handling for invalid cities/API failures
  • Temperature unit toggle (Celsius ↔ Fahrenheit)
  • Clean dashboard cards for weather display

🏗️ Technology Stack

Backend

  • Java 17+
  • Spring Boot 3.x
  • Maven
  • REST APIs
  • OpenWeatherMap API

Frontend

  • HTML5
  • CSS3 (Flexbox & Grid)
  • JavaScript ES6+
  • Three.js for 3D graphics
  • Globe.gl for globe visualization

📁 Project Structure

Weather/
├── src/
│   ├── main/
│   │   ├── java/com/weatherapp/
│   │   │   ├── WeatherApplication.java
│   │   │   ├── controller/
│   │   │   │   └── WeatherController.java
│   │   │   ├── service/
│   │   │   │   └── WeatherService.java
│   │   │   ├── client/
│   │   │   │   └── WeatherClient.java
│   │   │   ├── dto/
│   │   │   │   ├── WeatherResponseDTO.java
│   │   │   │   └── ForecastResponseDTO.java
│   │   │   ├── config/
│   │   │   │   ├── WeatherApiConfig.java
│   │   │   │   ├── RestTemplateConfig.java
│   │   │   │   └── CacheConfig.java
│   │   │   ├── exception/
│   │   │   │   ├── WeatherApiException.java
│   │   │   │   └── CityNotFoundException.java
│   │   │   └── util/
│   │   │       └── TemperatureConverter.java
│   │   └── resources/
│   │       ├── application.properties
│   │       └── static/
│   │           ├── index.html
│   │           ├── styles.css
│   │           └── script.js
├── pom.xml
└── README.md

🧱 Architecture Overview

Backend Layers

  1. Controller Layer: Handles HTTP requests and responses (WeatherController)
  2. Service Layer: Contains business logic (WeatherService)
  3. Client Layer: Communicates with external APIs (WeatherClient)
  4. DTO Layer: Data transfer objects for API responses
  5. Configuration: Application and API configurations

OOP Concepts Used

  • Encapsulation: Private fields with public getters/setters
  • Abstraction: Interfaces and abstract classes for extensibility
  • Inheritance: Extension of base classes
  • Polymorphism: Method overriding in exception handling

🚀 API Endpoints

Endpoint Method Description
/api/weather/today?city={city} GET Get current weather for a city
/api/weather/forecast?city={city} GET Get 3-day forecast for a city
/api/weather/by-coordinates?lat={lat}&lon={lon} GET Get current weather by coordinates

⚙️ Setup and Configuration

Prerequisites

  • Java 17 or higher
  • Maven 3.6+
  • OpenWeatherMap API Key

Installation Steps

  1. Clone the repository

    git clone <repository-url>
cd Weather

  2. Configure API Key

    • Sign up at OpenWeatherMap to get a free API key
    • Update src/main/resources/application.properties: 
      weather.api.key=YOUR_API_KEY_HERE

  3. Build the project

    mvn clean install

  4. Run the application

    mvn spring-boot:run

  5. Access the application Open your browser and navigate to http://localhost:8080

🎨 UI Components

Homepage

  • Interactive 3D globe visualization
  • City search bar
  • Weather information panels

Weather Display

  • Current weather conditions
  • Temperature with unit toggle
  • Weather icons
  • Detailed metrics (humidity, wind, pressure)
  • 3-day forecast cards

🔧 Technical Features

Caching

  • Implements in-memory caching for weather data
  • Reduces API calls and improves response times
  • Configurable cache expiration

Error Handling

  • Comprehensive exception handling
  • User-friendly error messages
  • Graceful degradation for API failures

Security

  • CORS enabled for frontend access
  • Secure API key management

Logging

  • Detailed application logging
  • Request/response tracking
  • Error diagnostics

📱 Responsive Design

The application is fully responsive and works on:

  • Desktop browsers
  • Tablet devices
  • Mobile phones

🌋 Future Enhancements

  1. Advanced Features

    • Historical weather data
    • Weather alerts and notifications
    • Multiple location tracking
    • Weather maps and radar

  2. UI Improvements

    • Animated weather effects
    • Dark/light theme toggle
    • Location autocomplete

  3. Technical Enhancements

    • Database integration for user preferences
    • WebSocket for real-time updates
    • Microservices architecture
    • Docker containerization

📸 Sample Screenshots

Homepage with Interactive Globe

Homepage Interactive 3D globe with dark space theme

Weather Dashboard

Weather Dashboard Detailed weather information with temperature toggle

Mobile View

Mobile View Responsive design for mobile devices

📄 License

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

👥 Authors

  • Created as a educational project demonstrating full-stack development with Spring Boot and modern frontend technologies

🙏 Acknowledgments