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:3000 (Next.js 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 backend/msn_weather_wrapper/ or api.py
FastAPI reloads automatically
Test: pytest tests/test_*.py
Check types: mypy backend/
Format: ruff format .

Frontend Changes¶

Edit files in frontend/app/
Next.js 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 backend/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=backend --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 backend/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/app/components/
Add types in frontend/app/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¶

./scripts/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, FastAPI with reload
Frontend Container: Node 22 Trixie slim, port 3000, Next.js dev server with HMR
Volumes: Source code mounted for hot reload

Environment Variables¶

API: APP_ENV=development, APP_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 backend/
✅ Coverage maintained: pytest --cov=backend
✅ 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/
├── backend/msn_weather_wrapper/    # Backend/library code
│   ├── api/                    # FastAPI app (main, routers, services, schemas)
│   ├── client.py               # Weather client
│   ├── models.py               # Pydantic models
│   ├── exceptions.py           # Domain-specific errors
│   └── py.typed                # Type marker
├── frontend/                   # Next.js application
│   └── app/                    # App Router source (layout, page, components, data)
├── tests/                      # Backend and integration tests
├── scripts/                    # Dev and automation scripts
├── infra/                      # Containers, compose files, and runtime config
├── docs/                       # Documentation and guides
├── api.py                      # Local API entrypoint
├── dev.sh                      # Wrapper around scripts/dev.sh
└── pyproject.toml              # Python config

Resources¶

Need Help? - 🐛 Report Issues - 💬 Discussions