development

Developer Documentation

Essential guides for contributing to Meteo Weather App

---

📚 Getting Started

New to the project? Start here:

1. Setup Guide - Complete installation and setup instructions
2. Architecture Walkthrough - Codebase tour for new developers
3. Developer Cheat Sheet - Quick reference for common tasks

---

📖 Documentation Index

For New Contributors

• Setup Guide - Prerequisites, installation, and first run
• Contributing Guide - How to contribute code
• Architecture Walkthrough - Understanding the codebase
• Developer Cheat Sheet - Quick command reference

Project Documentation

• Architecture - System design and diagrams
• Troubleshooting - Common issues and solutions
• Regression Prevention - Critical bug prevention

Specialized Guides

• AGENTS.md - Working with AI agents
• API Architecture Improvements - Centralized API client (P0-P3A)
• Build Validation - Build configuration validation
• Security Audit - Security implementation
• Error Message Style Guide - Error handling standards

---

🚀 Quick Start

# Clone and setup
git clone https://github.com/mbuckingham74/meteo-weather.git
cd meteo-weather
npm run install:all

# Configure environment
cp .env.example backend/.env
# Edit backend/.env with your API keys

# Start development
npm run dev

Access at:

• Frontend: http://localhost:3000
• Backend: http://localhost:5001

---

📋 Common Commands

# Development
npm run dev                  # Start full stack
npm run dev:frontend         # Frontend only
npm run dev:backend          # Backend only

# Testing
npm test                     # Run all tests
npm run lint                 # Check code style
npm run format               # Format code

# Database
npm run db:init              # Initialize database
npm run db:seed              # Load sample data

See Developer Cheat Sheet for complete command reference

---

🏗️ Architecture Overview

Frontend (React + Vite) ──► Backend (Express) ──► Database (MySQL)
     Port 3000                 Port 5001            Port 3307

Read Architecture Walkthrough for detailed explanation

---

📝 Code Style

• Frontend: React functional components, ES6+ modules
• Backend: Node.js/Express, CommonJS modules
• Linting: ESLint + Prettier (auto-format on commit)
• Testing: Vitest (frontend), Jest (backend)

See Contributing Guide for detailed style guidelines

---

⚠️ Before You Start

Critical Files with Regression Tests

If you modify these files, regression tests run automatically:

• frontend/src/services/geolocationService.js
• frontend/src/contexts/LocationContext.jsx
• backend/services/weatherService.js

Read Regression Prevention before modifying these files

---

🤝 Contributing Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting (npm test && npm run lint)
5. Commit with conventional commits (feat:, fix:, etc.)
6. Push to your fork
7. Open a Pull Request

See Contributing Guide for detailed workflow

---

🐛 Troubleshooting

Common issues and solutions:

• Port conflicts - Use lsof -i :PORT to find and kill processes
• Docker issues - Run docker-compose down -v to clean up
• Module errors - Run npm run install:all to reinstall dependencies
• Database errors - Run npm run db:init to reinitialize

See Troubleshooting Guide for more solutions

---

💬 Getting Help

• Setup Issues: Check Setup Guide and Troubleshooting
• Architecture Questions: Read Architecture Walkthrough
• Bug Reports: GitHub Issues
• General Questions: GitHub Discussions

---

📚 External Resources

• React Docs: https://react.dev/
• Vite Docs: https://vitejs.dev/
• Express Docs: https://expressjs.com/
• MySQL Docs: https://dev.mysql.com/doc/

---

Happy coding! 🌦️

Last Updated: November 14, 2025