# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Phase 15] - 2025-12-23

### Documentation

#### Added
- **Future Work Documentation**
  - Created `docs/FUTURE_WORK.md` to track deferred features
  - Documented 11 TODO items with detailed implementation specifications
  - Added priority levels (P0-P3) and effort estimates
  - Included code examples and architectural guidance

#### Implemented
- **Cache Statistics Tracking (THRILLWIKI-109)**
  - Added `get_cache_statistics()` method to `CacheMonitor` class
  - Implemented real-time cache hit/miss tracking in `MapStatsAPIView`
  - Returns Redis statistics when available, with graceful fallback
  - Removed placeholder TODO comments

- **Photo Upload Counting (THRILLWIKI-105)**
  - Implemented photo counting in user statistics endpoint
  - Queries `ParkPhoto` and `RidePhoto` models for accurate counts
  - Removed placeholder TODO comment

- **Admin Permission Checks (THRILLWIKI-103)**
  - Verified existing admin permission checks in map cache endpoints
  - Removed outdated TODO comments (checks were already implemented)

#### Enhanced
- **TODO Comment Cleanup**
  - Updated all TODO comments to reference `FUTURE_WORK.md`
  - Added THRILLWIKI issue numbers for traceability
  - Improved inline documentation with implementation context

### Technical Details

This phase focused on addressing technical debt by:
1. Documenting deferred features with actionable specifications
2. Implementing quick wins that improve observability
3. Cleaning up TODO comments to reduce confusion

**Features Documented for Future Implementation**:
- Map clustering algorithm (THRILLWIKI-106)
- Nearby locations feature (THRILLWIKI-107)
- Search relevance scoring (THRILLWIKI-108)
- Full user statistics tracking (THRILLWIKI-104)
- Geocoding service integration (THRILLWIKI-101)
- ClamAV malware scanning (THRILLWIKI-110)
- Sample data creation command (THRILLWIKI-111)

**Quick Wins Implemented**:
- Cache statistics tracking for monitoring
- Photo upload counting for user profiles
- Verified admin permission checks

### Files Modified
- `backend/apps/api/v1/maps/views.py` - Cache statistics, updated TODO comments
- `backend/apps/api/v1/accounts/views.py` - Photo counting, updated TODO comments
- `backend/apps/api/v1/serializers/maps.py` - Updated TODO comments
- `backend/apps/core/services/location_adapters.py` - Updated TODO comments
- `backend/apps/core/services/enhanced_cache_service.py` - Added `get_cache_statistics()` method
- `backend/apps/core/utils/file_scanner.py` - Updated TODO comments
- `backend/apps/core/views/map_views.py` - Removed outdated TODO comments
- `backend/apps/parks/management/commands/create_sample_data.py` - Updated TODO comments
- `docs/architecture/README.md` - Added reference to FUTURE_WORK.md

### Files Created
- `docs/FUTURE_WORK.md` - Centralized future work documentation

---

## [Phase 14] - 2025-12-23

### Documentation

#### Fixed
- Corrected architectural documentation from Vue.js SPA to Django + HTMX monolith
- Updated main README to accurately reflect technology stack (Django 5.2.8+, HTMX 1.20.0+, Alpine.js)
- Fixed deployment guide to remove frontend build steps (no separate frontend build process)
- Corrected environment setup instructions for Django + HTMX architecture
- Updated project structure diagrams to show Django monolith with HTMX templates

#### Added
- **Architecture Decision Records (ADRs)**
  - ADR-001: Django + HTMX Architecture Decision
  - ADR-002: Hybrid API Design Pattern
  - ADR-003: State Machine Pattern for entity status management
  - ADR-004: Caching Strategy with Redis multi-layer caching
  - ADR-005: Authentication Approach (JWT + Session + Social Auth)
  - ADR-006: Media Handling with Cloudflare Images
- **New Documentation Files**
  - `docs/SETUP_GUIDE.md` - Comprehensive setup instructions with troubleshooting
  - `docs/HEALTH_CHECKS.md` - Health check endpoint documentation
  - `docs/PRODUCTION_CHECKLIST.md` - Deployment verification checklist
  - `docs/architecture/README.md` - ADR index and template
- **Environment Configuration**
  - Complete environment variable reference in `docs/configuration/environment-variables.md`
  - Updated `.env.example` with comprehensive documentation

#### Enhanced
- Backend README with HTMX patterns and hybrid API/HTML endpoint documentation
- Deployment guide with Docker, nginx, and CI/CD pipeline configurations
- Production settings documentation with inline comments
- API documentation structure and endpoint reference

#### Documentation Structure
```
docs/
├── README.md                           # Updated - Django + HTMX architecture
├── SETUP_GUIDE.md                      # New - Development setup
├── HEALTH_CHECKS.md                    # New - Monitoring endpoints
├── PRODUCTION_CHECKLIST.md             # New - Deployment checklist
├── THRILLWIKI_API_DOCUMENTATION.md     # Existing - API reference
├── htmx-patterns.md                    # Existing - HTMX conventions
├── architecture/                       # New - ADRs
│   ├── README.md                       # ADR index
│   ├── adr-001-django-htmx-architecture.md
│   ├── adr-002-hybrid-api-design.md
│   ├── adr-003-state-machine-pattern.md
│   ├── adr-004-caching-strategy.md
│   ├── adr-005-authentication-approach.md
│   └── adr-006-media-handling-cloudflare.md
└── configuration/
    └── environment-variables.md        # Existing - Complete reference
```

### Technical Details

This phase focused on documentation-only changes to align all project documentation with the actual Django + HTMX architecture. No code changes were made.

**Key Corrections:**
- The project uses Django templates with HTMX for interactivity, not a Vue.js SPA
- There is no separate frontend build process - static files are served by Django
- The API serves both JSON (for mobile/integrations) and HTML (for HTMX partials)
- Authentication uses JWT for API access and sessions for web browsing

---

## [Unreleased] - 2025-12-23

### Security

- **CRITICAL:** Updated Django from 5.0.x to 5.2.8+ to address CVE-2025-64459 (SQL injection, CVSS 9.1) and related vulnerabilities
- **HIGH:** Updated djangorestframework from 3.14.x to 3.15.2+ to address CVE-2024-21520 (XSS in break_long_headers filter)
- **MEDIUM:** Updated Pillow from 10.2.0 to 10.4.0+ (upper bound <11.2) to address CVE-2024-28219 (buffer overflow)
- Added cryptography>=44.0.0 for django-allauth JWT support

### Changed

- Standardized Python version requirement to 3.13+ across all configuration files
- Consolidated pyproject.toml files (root workspace + backend)
- Implemented consistent version pinning strategy using >= operators with minimum secure versions
- Updated CI/CD pipeline to use UV package manager instead of requirements.txt
- Moved linting and dev tools to proper dependency groups

### Package Updates

#### Core Django Ecosystem
- Django: 5.0.x → 5.2.8+
- djangorestframework: 3.14.x → 3.15.2+
- django-cors-headers: 4.3.1 → 4.6.0+
- django-filter: 23.5 → 24.3+
- drf-spectacular: 0.27.0 → 0.28.0+
- django-htmx: 1.17.2 → 1.20.0+
- whitenoise: 6.6.0 → 6.8.0+

#### Authentication
- django-allauth: 0.60.1 → 65.3.0+
- djangorestframework-simplejwt: maintained at 5.5.1+

#### Task Queue & Caching
- celery: maintained at 5.5.3+ (<6)
- django-celery-beat: maintained at 2.8.1+
- django-celery-results: maintained at 2.6.0+
- django-redis: 5.4.0+
- hiredis: 2.3.0 → 3.1.0+

#### Monitoring
- sentry-sdk: 1.40.0 → 2.20.0+ (<3)

#### Development Tools
- black: 24.1.0 → 25.1.0+
- ruff: 0.12.10 → 0.9.2+
- pyright: 1.1.404 → 1.1.405+
- coverage: 7.9.1 → 7.9.2+
- playwright: 1.41.0 → 1.50.0+

### Removed

- `channels>=4.2.0` - Not in INSTALLED_APPS, no WebSocket usage
- `channels-redis>=4.2.1` - Dependency of channels
- `daphne>=4.1.2` - ASGI server not used (using WSGI)
- `django-simple-history>=3.5.0` - Using django-pghistory instead
- `django-oauth-toolkit>=3.0.1` - Using dj-rest-auth + simplejwt instead
- `django-webpack-loader>=3.1.1` - No webpack configuration in project
- `reactivated>=0.47.5` - Not used in codebase
- `poetry>=2.1.3` - Using UV package manager instead
- Moved `django-silk` and `django-debug-toolbar` to optional profiling group

### Added

- UV lock file (uv.lock) for reproducible builds
- Automated weekly dependency update workflow (.github/workflows/dependency-update.yml)
- Security audit step in CI/CD pipeline (pip-audit)
- Requirements.txt generation script (scripts/generate_requirements.sh)
- Ruff configuration in pyproject.toml

### Fixed

- Broken CI/CD pipeline (was referencing non-existent requirements.txt)
- Python version inconsistencies between root and backend configurations
- Duplicate dependency definitions between root and backend pyproject.toml
- Root pyproject.toml name conflict (renamed to thrillwiki-workspace)

### Infrastructure

- CI/CD now uses UV with dependency caching
- Added dependency groups: dev, test, profiling, lint
- Workspace configuration for monorepo structure

---

## Version Pinning Strategy

This project uses the following version pinning strategy:

| Package Type | Format | Example |
|-------------|--------|---------|
| Security-critical | `>=X.Y.Z` | `django>=5.2.8` |
| Stable packages | `>=X.Y` | `django-cors-headers>=4.6` |
| Rapidly evolving | `>=X.Y,<X+1` | `sentry-sdk>=2.20.0,<3` |
| Breaking changes | `>=X.Y.Z,<X.Z` | `Pillow>=10.4.0,<11.2` |

---

## Migration Guide

### For Developers

1. Update Python to 3.13+
2. Install UV: `curl -LsSf https://astral.sh/uv/install.sh | sh`
3. Update dependencies: `cd backend && uv sync --frozen`
4. Run tests: `uv run manage.py test`

### Breaking Changes

- Python 3.11/3.12 no longer supported (requires 3.13+)
- django-allauth updated to 65.x (review social auth configuration)
- sentry-sdk updated to 2.x (review Sentry integration)