# Development Guidelines

## Project Overview
This is a personal agenda web application built with Flask that tracks various events and important dates:
- Events: birthdays, holidays, travel itineraries, conferences, waste collection schedules
- Space launches, meteor showers, astronomical events
- Financial information (FX rates, stock market)
- UK-specific features (holidays, waste collection, railway schedules)
- Authentication via UniAuth
- Frontend uses Bootstrap 5, Leaflet for maps, FullCalendar for calendar views

## Python Environment
- Always use `python3` directly, never `python`
- All Python code should include type annotations
- Use `typing.Any` instead of `Any` in type hints (import from typing module)
- Run `mypy --strict` (fix any type errors in the file) and `black` on modified code after creating or modifying Python files
- Avoid running `black .`
- Main entry point: `python3 web_view.py` (Flask app on port 5000)
- Tests: Use `pytest` (tests in `/tests/` directory)

## Project Structure
- `agenda/` - Main Python package with modules for different event types
- `web_view.py` - Flask web application entry point
- `templates/` - Jinja2 HTML templates
- `static/` - CSS, JS, and frontend assets
- `config/` - Configuration files
- `personal-data/` - User's personal data (not in git)

## Git Workflow
- Avoid committing unrelated untracked files (e.g., `node_modules/`, build artifacts)
- Only commit relevant project files
- Personal data directory (`personal-data/`) is excluded from git

## Notes
- Trip stats new-country badges come from `agenda.stats.calculate_yearly_stats` via `year_stats.new_countries` (first-visit year, excluding `PREVIOUSLY_VISITED`).
- Trip stats are calculated in `agenda/stats.py`:
  - `travel_legs()` extracts airlines, airports, and stations from individual trip travel legs
  - `calculate_yearly_stats()` aggregates stats per year including flight/train counts, airlines, airports, stations
  - `calculate_overall_stats()` aggregates yearly stats into overall totals for the summary section