WeatherCard

A modern, full-stack weather application built with React and Express.js that provides real-time weather information with user authentication and personalized favorites.

🌟 Features

Real-time Weather Data: Get current weather conditions for any location worldwide
User Authentication: Secure user registration and login system
Favorite Locations: Save and manage your favorite weather locations
Progressive Web App (PWA): Install and use offline on any device
Responsive Design: Works seamlessly on desktop and mobile devices
Redis Caching: Fast weather data retrieval with intelligent caching
End-to-End Observability (OpenTelemetry): Full-stack distributed tracing and metrics from React UI down to Express, MongoDB, and Redis
REST API: Full-featured API with Swagger documentation

🚀 Live Demo

The application displays weather cards for different locations with temperature, humidity, wind speed, and other meteorological data.

🏗️ Architecture

System Overview

The application follows a microservices architecture with:

Frontend: React SPA with TypeScript and Material-UI
Backend: Express.js API server with TypeScript
Database: MongoDB for user data and favorites
Cache: Redis for weather data caching
External API: OpenWeatherMap for weather data
Deployment: Docker containers with Traefik reverse proxy

Component Structure

The React application is structured with reusable components for weather cards, user authentication, and navigation.

🛠️ Technology Stack

Frontend

React 19 with TypeScript
Material-UI (MUI) for UI components
Vite for build tooling and development
PWA support with service workers
Axios for API communication with W3C traceparent propagation
JWT for authentication
OpenTelemetry Web SDK (@opentelemetry/sdk-trace-web, @opentelemetry/auto-instrumentations-web)

Backend

Express.js with TypeScript
MongoDB with Mongoose ODM
Redis for caching
bcrypt for password hashing
JWT for authentication
Swagger for API documentation
express-validator for input validation
OpenTelemetry Node SDK (@opentelemetry/sdk-node, @opentelemetry/auto-instrumentations-node)

Observability & DevOps

OpenTelemetry Collector for trace & metric aggregation
Jaeger for distributed tracing visualization
Prometheus for metric collection and monitoring
Docker & Docker Compose
Traefik reverse proxy
Multi-stage Docker builds

📋 Prerequisites

Before running this application, make sure you have:

Node.js 22 or higher
Docker and Docker Compose
OpenWeatherMap API key (Get one free here)

🚀 Quick Start

Using Docker (Recommended)

Clone the repository

git clone https://github.com/devleesch001/weather-card.git
cd weather-card

Configure environment variables

# Backend configuration
cp back/.env.example back/.env
# Edit back/.env and add your OpenWeatherMap API key

# Frontend configuration  
cp front/.env.example front/.env
# Edit front/.env if needed (defaults should work for Docker setup)

Start the application
```
docker compose up -d
```
Access the application
- Frontend: http://localhost (or your configured domain)
- API Documentation: http://localhost/api/docs

Development Setup

Backend Development

cd back
npm install
npm run dev

Frontend Development

cd front
npm install
npm run dev

📡 API Documentation

The API provides the following endpoints:

Authentication

POST /api/auth/login - User login
POST /api/auth/register - User registration

User Management

GET /api/user - Get user information
POST /api/user - Create new user

Weather Data

GET /api/weather - Get weather data by coordinates
GET /api/geoCode - Get coordinates from location name

Favorites

GET /api/favorite - Get user's favorite locations
POST /api/favorite - Add location to favorites

Full API documentation is available at /api/docs when running the application.

🗄️ Data Model

User Schema

{
    username: 'john_doe',
    email: 'john@example.com',
    favorites: [
        'Paris',
        'New York',
        'Tokyo'
    ],
    hashedPassword: '$2b$10$...' // bcrypt hashed
}

Weather Data Structure

The application fetches and caches weather data from OpenWeatherMap API, including:

Current temperature and "feels like" temperature
Min/max temperatures
Humidity percentage
Wind speed and direction
Weather conditions and descriptions

⚡ Performance & Caching

The application uses Redis for efficient weather data caching:

Location-based caching: Weather data cached by coordinates
Search optimization: Frequently searched locations cached
Automatic expiration: Cache expires to ensure fresh data
Performance: Sub-second response times for cached data

📊 Observability & OpenTelemetry (OTel)

WeatherCard includes end-to-end distributed tracing and metrics powered by OpenTelemetry:

End-to-End Tracing: User actions in React (e.g. searching a location in MenuAppBar) generate an active span that propagates across HTTP calls to Express, MongoDB, and Redis using W3C traceparent headers.
Frontend Telemetry: Automated Web instrumentation collects user interactions, navigation timings, and fetch/XHR requests via @opentelemetry/sdk-trace-web.
Backend Telemetry: Node SDK auto-instruments Express routes, HTTP requests, MongoDB queries, and Redis commands.
Metrics & Traces Collection: Traces and metrics are proxied through /api/telemetry/* to the OpenTelemetry Collector, which routes them to Jaeger and Prometheus.

Starting the Observability Stack

Run the development observability stack (Jaeger, Prometheus, OTel Collector) with:

docker compose -f compose.dev.yaml up -d

Dashboards & Interfaces

Tool	URL	Description
Jaeger UI	http://localhost:16686	Distributed tracing UI to visualize request flows
Prometheus UI	http://localhost:9090	Metrics collection and PromQL querying
OTel Collector	`http://localhost:4318`	OpenTelemetry Collector OTLP HTTP receiver

🐳 Docker Architecture

The application is fully containerized with:

Multi-stage builds for optimized image sizes
Production-ready configurations
Traefik integration for automatic HTTPS and load balancing
Volume persistence for database data
Network isolation for security

Services

front: React application (served with Node.js serve)
back: Express.js API server
mongo: MongoDB database
cache: Redis cache
External: Traefik proxy (handles SSL and routing)

🔧 Configuration

Environment Variables

Backend (.env)

# Server Configuration
PORT=8080

# OpenWeatherMap API Configuration
API_KEY=your_openweathermap_api_key_here

# JWT Secrets for Authentication
ACCESS_TOKEN_SECRET=your_jwt_access_secret_here
REFRESH_TOKEN_SECRET=your_jwt_refresh_secret_here

# Database Configuration
MANGODB_URL=mongodb://root:example@mongo:27017

# Redis Cache Configuration
REDIS_URL=redis://cache:6379

# OpenTelemetry & Observability Configuration
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp

Frontend (.env)

# API Base URL
VITE_APP_API_URL=/api

🚀 Deployment

Production Deployment

# Pull latest changes
git pull origin main

# Build and start services
docker compose up -d --build

# Verify deployment
docker compose logs -f

SSL Configuration

The application is configured to work with Traefik for automatic SSL certificates using Let's Encrypt.

🐛 Troubleshooting

Common Issues

Docker build fails:

Ensure Docker and Docker Compose are installed and running
Check that ports 80 and 8080 are not already in use
Verify you have sufficient disk space

Weather data not loading:

Verify your OpenWeatherMap API key is correctly set in back/.env
Check that the API key is active and has remaining quota
Ensure Redis is running and accessible

Authentication issues:

Make sure JWT secrets are set in back/.env
Check that MongoDB is running and accessible
Verify the database connection string

Development server issues:

Run npm ci in both front/ and back/ directories
Ensure Node.js version is 22 or higher
Check that environment variables are properly configured

🤝 Contributing

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

📝 License

This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.

🙏 Acknowledgments

OpenWeatherMap for weather data API
Material-UI for React components
MongoDB for database solution
Redis for caching capabilities
OpenTelemetry for end-to-end distributed tracing & metrics framework
Jaeger & Prometheus for trace visualization and metrics collection

📞 Support

If you have any questions or need help with setup, please:

Check the Issues page
Create a new issue with detailed information
Contact the maintainers

Made with ❤️ by the WeatherCard team

Name		Name	Last commit message	Last commit date
Latest commit History 122 Commits
.github/workflows		.github/workflows
back		back
config		config
docs		docs
front		front
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
compose.dev.yaml		compose.dev.yaml
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation