Development Guide¶

Complete guide for developing, testing, and contributing to MSN Weather Wrapper.

Quick Start¶

Containerized Development (Recommended)¶

Get a complete development environment in containers:

git clone https://github.com/jim-wyatt/msn-weather-wrapper.git
cd msn-weather-wrapper

# One-time setup
./dev.sh setup

# Start development
./dev.sh start

# Access services:
# - Frontend: http://localhost:5173 (Vite dev server with HMR)
# - Backend API: http://localhost:5000
# - Health Check: http://localhost:5000/api/v1/health

Local Development¶

For direct local development without containers:

# Backend setup
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pre-commit install

# Start backend
python api.py

# Frontend setup (separate terminal)
cd frontend
npm install
npm run dev

Development Workflow¶

Container Development Commands¶

# Daily workflow
./dev.sh start    # Start all services
./dev.sh status   # Check service health
./dev.sh logs     # Watch logs
./dev.sh stop     # Stop all services
./dev.sh restart  # Restart services

# Testing
./dev.sh test     # Run all tests
./dev.sh shell-api      # Backend shell
./dev.sh shell-frontend # Frontend shell

# Maintenance
./dev.sh rebuild  # Rebuild from scratch
./dev.sh clean    # Remove containers & volumes
./dev.sh clean --gitignore  # Also clean git-ignored files (preview first)
./dev.sh docs     # Build & serve documentation

Making Code Changes¶

Backend Changes¶

Edit files in src/msn_weather_wrapper/ or api.py
Flask auto-reloads automatically
Test: pytest tests/test_*.py
Check types: mypy src/
Format: ruff format .

Frontend Changes¶

Edit files in frontend/src/
Vite HMR updates instantly
Test: npm run test:e2e
Type check: npm run type-check
Build: npm run build

Code Quality Tools¶

Python¶

# Format code
ruff format .

# Lint code
ruff check .
ruff check . --fix  # Auto-fix

# Type checking
mypy src/msn_weather_wrapper

# Run all checks
pre-commit run --all-files

TypeScript¶

cd frontend

# Type checking
npm run type-check

# Build (includes type checking)
npm run build

Testing¶

Backend Testing¶

# All tests
pytest

# Specific test file
pytest tests/test_api.py -v

# With coverage
pytest --cov=src --cov-report=html

# Security tests
pytest tests/test_security.py -v

Frontend Testing¶

cd frontend

# Install Playwright (first time)
npx playwright install

# Run E2E tests
npm run test:e2e

# Interactive mode
npm run test:e2e:ui

# Headed mode (see browser)
npm run test:e2e:headed

Integration Testing¶

# Start API first
python api.py

# Run integration tests
pytest tests/test_integration.py -v

Adding Features¶

Backend Feature¶

Write code in src/msn_weather_wrapper/
Add tests in tests/
Update types in models.py
Add API endpoint in api.py (if needed)
Update docs in docs/API.md

Frontend Feature¶

Create component in frontend/src/components/
Add types in frontend/src/types.ts
Add E2E test in frontend/tests/e2e/
Update styles as needed

Dependency Management¶

Python¶

# Edit pyproject.toml, then:
pip install -e ".[dev]"

Node.js¶

cd frontend
npm install package-name          # Production
npm install --save-dev package   # Development

Debugging¶

Backend¶

# Using logging
import structlog
logger = structlog.get_logger()
logger.info("debug message", variable=value)

# Using ipdb
import ipdb; ipdb.set_trace()

# In container
./dev.sh shell-api
ipython

Frontend¶

Open DevTools (F12)
Console tab for logs
Network tab for API calls
React DevTools extension

Common Tasks¶

Generate Documentation¶

mkdocs serve       # Local preview
mkdocs build       # Build static site
mkdocs gh-deploy   # Deploy to GitHub Pages

Generate SBOM¶

./tools/generate_sbom.sh
cat sbom_output/SBOM_SUMMARY_*.md

Update Dependencies¶

# Python
pip install --upgrade -e ".[dev]"

# Node.js
cd frontend && npm update

Containerized Development Details¶

Architecture¶

API Container: Python 3.12 slim (Trixie), port 5000, Flask with hot reload
Frontend Container: Node 22 Trixie slim, port 5173, Vite with HMR
Volumes: Source code mounted for hot reload

Environment Variables¶

API: FLASK_ENV=development, FLASK_DEBUG=1
Frontend: NODE_ENV=development

Troubleshooting¶

Tests fail with import errors¶

pip install -e ".[dev]"

Frontend won't start¶

cd frontend
rm -rf node_modules package-lock.json
npm install

Container won't build¶

./dev.sh clean
./dev.sh setup

Port already in use¶

# Find process
lsof -i :5000

# Kill process
kill -9 <PID>

Contributing Guidelines¶

Before submitting PR:

✅ All tests pass: pytest
✅ Code formatted: ruff format .
✅ No lint errors: ruff check .
✅ Types valid: mypy src/
✅ Coverage maintained: pytest --cov=src
✅ Frontend tests pass: npm run test:e2e
✅ Documentation updated
✅ CHANGELOG.md updated

See the Contributing Guidelines section above for full guidelines.

Project Structure¶

msn-weather-wrapper/
├── src/msn_weather_wrapper/    # Python package
│   ├── __init__.py             # Package exports
│   ├── client.py               # Weather client
│   ├── models.py               # Pydantic models
│   └── py.typed                # Type marker
├── tests/                      # Test suite
│   ├── test_api.py             # API tests
│   ├── test_client.py          # Client tests
│   ├── test_models.py          # Model tests
│   ├── test_security.py        # Security tests
│   └── test_integration.py     # Integration tests
├── frontend/                   # React application
│   ├── src/                    # TypeScript source
│   │   ├── components/         # React components
│   │   ├── data/               # City database
│   │   ├── App.tsx             # Main app
│   │   └── main.tsx            # Entry point
│   └── tests/e2e/              # Playwright tests
├── api.py                      # Flask REST API
├── docs/                       # Documentation
├── Containerfile               # Production container
├── Containerfile.dev           # Dev container
├── podman-compose.yml          # Production compose
└── pyproject.toml              # Python config

Resources¶

Need Help? - 🐛 Report Issues - 💬 Discussions