Enhance documentation and management commands for ThrillWiki

- Updated backend README.md to include detailed management commands for configuration, database operations, cache management, data management, user authentication, content/media handling, trending/discovery, testing/development, and security/auditing. - Added a new MANAGEMENT_COMMANDS.md file for comprehensive command reference. - Included logging standardization details in architecture documentation (ADR-007). - Improved production checklist with configuration validation and cache verification steps. - Expanded API documentation to include error logging details. - Created a documentation review checklist to ensure completeness and accuracy.
2025-12-24 09:51:09 -05:00 · 2025-12-23 21:28:14 -05:00
parent edcd8f2076
commit ca770d76ff
10 changed files with 1649 additions and 13 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,254 @@ 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 7] - 2025-12-24
+
+### Testing
+
+#### Added
+- **Comprehensive Test Coverage Improvements**
+  - Added 30+ new test files across all apps
+  - API endpoint tests with authentication, error handling, pagination, and response format validation
+  - E2E tests for FSM workflows (parks, rides, moderation)
+  - Integration tests for FSM transition workflows
+  - Unit tests for managers, serializers, and services
+  - Accessibility tests for WCAG 2.1 AA compliance
+  - Form validation tests for all major forms
+
+#### Test Files Added
+- `backend/tests/api/` - API endpoint tests (8 files)
+- `backend/tests/e2e/` - End-to-end FSM workflow tests (3 files)
+- `backend/tests/integration/` - Integration tests (1 file)
+- `backend/tests/managers/` - Manager tests (2 files)
+- `backend/tests/serializers/` - Serializer tests (3 files)
+- `backend/tests/services/` - Service layer tests (3 files)
+- `backend/tests/forms/` - Form validation tests (5 files)
+- `backend/tests/accessibility/` - WCAG compliance tests (1 file)
+- `backend/apps/*/tests/` - App-specific tests (7 files)
+
+#### Coverage Improvements
+- Increased test coverage for models, views, and services
+- Added tests for edge cases and error conditions
+- Improved FSM transition testing with permission checks
+- Added query optimization tests
+
+### Technical Details
+
+This phase focused on achieving comprehensive test coverage to ensure code quality and prevent regressions. Tests cover:
+- All API endpoints with various authentication scenarios
+- FSM state transitions with permission validation
+- Form validation logic with edge cases
+- Manager methods and custom QuerySets
+- Service layer business logic
+- Accessibility compliance for interactive components
+
+**Testing Infrastructure**:
+- pytest with Django plugin
+- Factory Boy for test data generation
+- Coverage.py for coverage tracking
+- Playwright for E2E tests
+
+### Files Modified
+- `backend/pyproject.toml` - Updated test dependencies and coverage configuration
+- `backend/tests/conftest.py` - Enhanced test fixtures and utilities
+
+---
+
+## [Phase 6] - 2025-12-24
+
+### Forms & Validation
+
+#### Enhanced
+- **Form Validation Coverage**
+  - Added custom `clean_*` methods for field-level validation
+  - Improved error messages for better user experience
+  - Enhanced form widgets (date pickers, rich text editors)
+  - Standardized ModelForm field definitions
+
+#### Forms Enhanced
+- `backend/apps/parks/forms/base.py` - Park creation/update forms
+- `backend/apps/parks/forms/review_forms.py` - Park review forms
+- `backend/apps/parks/forms/area_forms.py` - Park area forms
+- `backend/apps/rides/forms/base.py` - Ride creation/update forms
+- `backend/apps/rides/forms/review_forms.py` - Ride review forms
+- `backend/apps/rides/forms/company_forms.py` - Company forms
+- `backend/apps/rides/forms/search.py` - Ride search forms
+- `backend/apps/core/forms/search.py` - Core search forms
+- `backend/apps/core/forms/htmx_forms.py` - HTMX-specific form patterns
+
+#### Tests Added
+- `backend/tests/forms/test_area_forms.py` - Area form validation tests
+- `backend/tests/forms/test_park_forms.py` - Park form validation tests
+- `backend/tests/forms/test_ride_forms.py` - Ride form validation tests
+- `backend/tests/forms/test_review_forms.py` - Review form validation tests
+- `backend/tests/forms/test_company_forms.py` - Company form validation tests
+
+### Technical Details
+
+This phase improved form validation coverage across the application:
+1. **Field-Level Validation**: Custom `clean_*` methods for complex validation logic
+2. **User-Friendly Errors**: Clear, actionable error messages
+3. **Widget Improvements**: Better UX with appropriate input widgets
+4. **HTMX Integration**: Forms work seamlessly with HTMX partial updates
+5. **Test Coverage**: Comprehensive tests for all validation scenarios
+
+**Validation Patterns**:
+- Date range validation (opening/closing dates)
+- Coordinate validation (latitude/longitude bounds)
+- Slug uniqueness validation
+- Cross-field validation (e.g., closing date must be after opening date)
+- File upload validation (size, type, dimensions)
+
+---
+
+## [Phase 5] - 2025-12-24
+
+### Admin Interface
+
+#### Enhanced
+- **Django Admin Completeness**
+  - Added comprehensive `list_display` with key fields
+  - Implemented `search_fields` for text search
+  - Added `list_filter` for status, category, and date filtering
+  - Organized detail views with `fieldsets`
+  - Added `readonly_fields` for computed properties and timestamps
+  - Implemented custom admin actions (bulk approve, bulk reject, etc.)
+
+#### Admin Files Enhanced
+- `backend/apps/parks/admin.py` - Park, Area, Company, Review admin
+- `backend/apps/rides/admin.py` - Ride, Manufacturer, Review admin
+- `backend/apps/accounts/admin.py` - User, Profile admin
+- `backend/apps/moderation/admin.py` - Submission, Report admin
+- `backend/apps/core/admin.py` - Base admin classes and mixins
+
+#### Custom Admin Actions
+- Bulk approve/reject for moderation workflows
+- Bulk status changes for parks and rides
+- Export to CSV for reporting
+- Cache invalidation for modified entities
+
+### Technical Details
+
+This phase completed the Django admin interface to provide a powerful content management system:
+1. **List Views**: Optimized with select_related/prefetch_related
+2. **Search**: Full-text search on name, description, and location fields
+3. **Filters**: Status, category, date range, and custom filters
+4. **Detail Views**: Organized with logical fieldsets
+5. **Actions**: Bulk operations for efficient moderation
+
+**Admin Patterns**:
+- Inherited from `BaseModelAdmin` for consistency
+- Used `readonly_fields` for computed properties
+- Implemented `get_queryset()` optimization
+- Added inline admin for related objects
+
+---
+
+## [Phase 4] - 2025-12-24
+
+### Models & Database
+
+#### Enhanced
+- **Model Completeness & Consistency**
+  - Added/improved `__str__` methods for human-readable representations
+  - Standardized `Meta` classes with `ordering`, `verbose_name`, `verbose_name_plural`
+  - Added comprehensive `help_text` on all fields
+  - Verified database indexes on foreign keys and frequently queried fields
+  - Added model constraints (CheckConstraint, UniqueConstraint)
+
+#### Model Files Enhanced
+- `backend/apps/parks/models/parks.py` - Park model
+- `backend/apps/parks/models/companies.py` - Company, Operator models
+- `backend/apps/parks/models/areas.py` - ParkArea model
+- `backend/apps/parks/models/media.py` - ParkPhoto model
+- `backend/apps/parks/models/reviews.py` - ParkReview model
+- `backend/apps/parks/models/location.py` - ParkLocation model
+- `backend/apps/rides/models/rides.py` - Ride model
+- `backend/apps/rides/models/company.py` - Manufacturer, Designer models
+- `backend/apps/rides/models/rankings.py` - RideRanking model
+- `backend/apps/rides/models/media.py` - RidePhoto model
+- `backend/apps/rides/models/reviews.py` - RideReview model
+- `backend/apps/rides/models/location.py` - RideLocation model
+- `backend/apps/accounts/models.py` - User, Profile models
+- `backend/apps/moderation/models.py` - Submission, Report models
+- `backend/apps/core/models.py` - Base models and mixins
+
+#### Database Improvements
+- Added indexes for performance optimization
+- Implemented constraints for data integrity
+- Standardized field naming conventions
+- Improved model documentation
+
+### Technical Details
+
+This phase improved model quality and consistency:
+1. **String Representations**: All models have meaningful `__str__` methods
+2. **Metadata**: Complete Meta classes with ordering and verbose names
+3. **Field Documentation**: Every field has descriptive help_text
+4. **Database Optimization**: Proper indexes on foreign keys and search fields
+5. **Data Integrity**: Constraints enforce business rules at database level
+
+**Model Patterns**:
+- Used `TextChoices` for status and category fields
+- Implemented `db_index=True` on frequently queried fields
+- Added `CheckConstraint` for value ranges (e.g., ratings 1-5)
+- Used `UniqueConstraint` for compound uniqueness
+
+---
+
+## [Phase 3] - 2025-12-24
+
+### Logging & Observability
+
+#### Standardized
+- **Logging Pattern Consistency**
+  - Added `logger = logging.getLogger(__name__)` to all view, service, and middleware files
+  - Implemented centralized logging utilities from `apps.core.logging`
+  - Standardized log levels (debug, info, warning, error)
+  - Added structured logging with context
+
+#### Files Enhanced with Logging
+- `backend/apps/parks/views.py` - Park views
+- `backend/apps/rides/views.py` - Ride views
+- `backend/apps/accounts/views.py` - Account views
+- `backend/apps/moderation/views.py` - Moderation views
+- `backend/apps/accounts/services.py` - Account services
+- `backend/apps/parks/signals.py` - Park signals
+- `backend/apps/rides/signals.py` - Ride signals
+- `backend/apps/moderation/signals.py` - Moderation signals
+- `backend/apps/rides/tasks.py` - Celery tasks
+- `backend/apps/parks/apps.py` - App configuration
+- `backend/apps/rides/apps.py` - App configuration
+- `backend/apps/moderation/apps.py` - App configuration
+
+#### Logging Utilities
+- `log_exception()` - Exception logging with full context
+- `log_business_event()` - Business operation logging (FSM transitions, user actions)
+- `log_security_event()` - Security event logging (authentication, authorization)
+
+### Technical Details
+
+This phase standardized logging across the application for better observability:
+1. **Consistent Logger Initialization**: Every module uses `logging.getLogger(__name__)`
+2. **Centralized Utilities**: Structured logging functions in `apps.core.logging`
+3. **Contextual Logging**: All logs include relevant context (user, request, operation)
+4. **Security Logging**: Dedicated logging for security events
+5. **Performance Logging**: Query performance and cache hit/miss tracking
+
+**Logging Patterns**:
+- Exception handlers use `log_exception()` with context
+- FSM transitions use `log_business_event()`
+- Authentication events use `log_security_event()`
+- Never log sensitive data (passwords, tokens, PII)
+
+**Benefits**:
+- Easier debugging with consistent log format
+- Better production monitoring with structured logs
+- Security audit trail for compliance
+- Performance insights from cache and query logs
+
+---
+
 ## [Phase 15] - 2025-12-23

 ### Documentation
--- a/backend/README.md
+++ b/backend/README.md
@@ -288,27 +288,222 @@ uv run manage.py test backend.tests.accessibility

 ## Management Commands

+ThrillWiki provides numerous management commands for development, deployment, and maintenance.
+
+### Configuration & Validation
+
 ```bash
-# Database operations
+# Validate all settings and environment variables
+uv run manage.py validate_settings
+uv run manage.py validate_settings --strict  # Treat warnings as errors
+uv run manage.py validate_settings --json    # JSON output
+uv run manage.py validate_settings --secrets-only  # Only validate secrets
+
+# Validate state machine configurations
+uv run manage.py validate_state_machines
+
+# List all FSM transition callbacks
+uv run manage.py list_transition_callbacks
+```
+
+### Database Operations
+
+```bash
+# Standard Django commands
 uv run manage.py migrate
 uv run manage.py makemigrations
-uv run manage.py createsuperuser
 uv run manage.py showmigrations
+uv run manage.py createsuperuser

-# Static files
-uv run manage.py collectstatic
+# Fix migration history issues
+uv run manage.py fix_migrations
+uv run manage.py fix_migration_history

-# Configuration validation
-uv run manage.py validate_settings
-
-# Cache management
-uv run manage.py warm_cache
-
-# Data management
-uv run manage.py import_parks data/parks.json
-uv run manage.py generate_test_data
+# Reset database (DESTRUCTIVE - development only)
+uv run manage.py reset_db
 ```

+### Cache Management
+
+```bash
+# Warm cache with frequently accessed data
+uv run manage.py warm_cache
+uv run manage.py warm_cache --parks-only
+uv run manage.py warm_cache --rides-only
+uv run manage.py warm_cache --metadata-only
+uv run manage.py warm_cache --dry-run  # Preview without caching
+
+# Clear all caches
+uv run manage.py clear_cache
+```
+
+### Data Management
+
+```bash
+# Seed initial data (operators, manufacturers, etc.)
+uv run manage.py seed_initial_data
+
+# Create sample data for development
+uv run manage.py create_sample_data
+uv run manage.py create_sample_data --minimal  # Quick setup
+uv run manage.py create_sample_data --clear    # Clear existing first
+
+# Seed sample parks and rides
+uv run manage.py seed_sample_data
+
+# Seed test submissions for moderation
+uv run manage.py seed_submissions
+
+# Seed API test data
+uv run manage.py seed_data
+
+# Update park statistics (ride counts, ratings)
+uv run manage.py update_park_counts
+
+# Update ride rankings
+uv run manage.py update_ride_rankings
+```
+
+### User & Authentication
+
+```bash
+# Create test users
+uv run manage.py create_test_users
+
+# Delete user and all related data
+uv run manage.py delete_user <username>
+
+# Setup user groups and permissions
+uv run manage.py setup_groups
+
+# Setup Django sites framework
+uv run manage.py setup_site
+
+# Social authentication setup
+uv run manage.py setup_social_auth
+uv run manage.py setup_social_providers
+uv run manage.py create_social_apps
+uv run manage.py check_social_apps
+uv run manage.py fix_social_apps
+uv run manage.py reset_social_apps
+uv run manage.py reset_social_auth
+uv run manage.py cleanup_social_auth
+uv run manage.py update_social_apps_sites
+uv run manage.py verify_discord_settings
+uv run manage.py test_discord_auth
+uv run manage.py check_all_social_tables
+uv run manage.py setup_social_auth_admin
+
+# Avatar management
+uv run manage.py generate_letter_avatars
+uv run manage.py regenerate_avatars
+```
+
+### Content & Media
+
+```bash
+# Static file management
+uv run manage.py collectstatic
+uv run manage.py optimize_static  # Minify and compress
+
+# Media file management (in shared/media/)
+uv run manage.py download_photos
+uv run manage.py move_photos
+uv run manage.py fix_photo_paths
+```
+
+### Trending & Discovery
+
+```bash
+# Calculate trending content
+uv run manage.py calculate_trending
+uv run manage.py update_trending
+uv run manage.py test_trending
+
+# Calculate new content for discovery
+uv run manage.py calculate_new_content
+```
+
+### Testing & Development
+
+```bash
+# Run development server with auto-reload
+uv run manage.py rundev
+
+# Setup development environment
+uv run manage.py setup_dev
+
+# Test location services
+uv run manage.py test_location
+
+# Test FSM transition callbacks
+uv run manage.py test_transition_callbacks
+
+# Analyze FSM transitions
+uv run manage.py analyze_transitions
+
+# Cleanup test data
+uv run manage.py cleanup_test_data
+```
+
+### Security & Auditing
+
+```bash
+# Run security audit
+uv run manage.py security_audit
+```
+
+### Command Categories
+
+| Category | Commands |
+|----------|----------|
+| **Configuration** | validate_settings, validate_state_machines, list_transition_callbacks |
+| **Database** | migrate, makemigrations, reset_db, fix_migrations |
+| **Cache** | warm_cache, clear_cache |
+| **Data** | seed_initial_data, create_sample_data, update_park_counts, update_ride_rankings |
+| **Users** | create_test_users, delete_user, setup_groups, setup_social_auth |
+| **Media** | collectstatic, optimize_static, download_photos, move_photos |
+| **Trending** | calculate_trending, update_trending, calculate_new_content |
+| **Development** | rundev, setup_dev, test_location, cleanup_test_data |
+| **Security** | security_audit |
+
+### Common Workflows
+
+#### Initial Setup
+```bash
+uv run manage.py migrate
+uv run manage.py createsuperuser
+uv run manage.py setup_groups
+uv run manage.py seed_initial_data
+uv run manage.py create_sample_data --minimal
+uv run manage.py warm_cache
+```
+
+#### Development Reset
+```bash
+uv run manage.py reset_db
+uv run manage.py migrate
+uv run manage.py create_sample_data
+uv run manage.py warm_cache
+```
+
+#### Production Deployment
+```bash
+uv run manage.py migrate
+uv run manage.py collectstatic --noinput
+uv run manage.py validate_settings --strict
+uv run manage.py warm_cache
+```
+
+#### Cache Refresh
+```bash
+uv run manage.py clear_cache
+uv run manage.py warm_cache
+uv run manage.py calculate_trending
+```
+
+See [Management Commands Reference](../docs/MANAGEMENT_COMMANDS.md) for complete documentation.
+
 ## Database

 ### Entity Relationships
--- a/backend/docs/code_standards.md
+++ b/backend/docs/code_standards.md
@@ -238,6 +238,10 @@ pytest backend/tests/ --cov=backend/apps --cov-report=html

 ## Logging Standards

+### Architecture Decision
+
+The logging standardization pattern is documented in [ADR-007: Logging Standardization Pattern](../../docs/architecture/adr-007-logging-standardization.md).
+
 ### Logger Initialization

 Every view and middleware file should initialize a logger:
--- a/docs/DOCUMENTATION_REVIEW.md
+++ b/docs/DOCUMENTATION_REVIEW.md
@@ -0,0 +1,166 @@
+# Documentation Review Checklist
+
+Use this checklist to verify documentation completeness after major changes.
+
+## Core Documentation
+
+- [ ] `README.md` - Project overview and quick start
+- [ ] `docs/README.md` - Main documentation index
+- [ ] `backend/README.md` - Backend-specific documentation
+- [ ] `CHANGELOG.md` - All changes documented
+- [ ] `.env.example` - All environment variables documented
+
+## Architecture
+
+- [ ] All ADRs are up-to-date
+- [ ] `docs/architecture/README.md` - ADR index is complete
+- [ ] State machine diagrams match implementation
+- [ ] Architecture diagrams reflect current structure
+
+## Configuration
+
+- [ ] `docs/configuration/environment-variables.md` - Complete variable reference
+- [ ] `docs/PRODUCTION_CHECKLIST.md` - All deployment steps covered
+- [ ] `backend/docs/code_standards.md` - Standards reflect current patterns
+
+## API & Endpoints
+
+- [ ] `docs/THRILLWIKI_API_DOCUMENTATION.md` - All endpoints documented
+- [ ] `docs/htmx-patterns.md` - HTMX patterns are current
+- [ ] OpenAPI schema is up-to-date (`/api/schema/`)
+
+## Features & Workflows
+
+- [ ] `docs/FUTURE_WORK.md` - Deferred features documented
+- [ ] `docs/MANAGEMENT_COMMANDS.md` - All commands documented
+- [ ] FSM workflows documented
+- [ ] User workflows documented
+
+## Testing & Quality
+
+- [ ] Test coverage documentation
+- [ ] Accessibility testing guide
+- [ ] Performance testing guide
+- [ ] Security testing guide
+
+## Deployment
+
+- [ ] Deployment guide is accurate
+- [ ] Docker configuration documented
+- [ ] CI/CD pipeline documented
+- [ ] Rollback procedures documented
+
+## Maintenance
+
+- [ ] Backup procedures documented
+- [ ] Monitoring setup documented
+- [ ] Troubleshooting guide exists
+- [ ] Runbook for common operations
+
+## Review Process
+
+1. **After Major Changes**: Review all affected documentation
+2. **Before Release**: Complete full documentation review
+3. **Quarterly**: Review all documentation for accuracy
+4. **After Incidents**: Update troubleshooting and runbooks
+
+## Documentation Quality Standards
+
+- [ ] All code examples are tested and working
+- [ ] All links are valid (no 404s)
+- [ ] All commands include expected output
+- [ ] All configuration examples are complete
+- [ ] All diagrams are up-to-date
+- [ ] All ADRs follow the template
+- [ ] All changelog entries follow the format
+
+## ADR Completeness
+
+| ADR | Title | Status | Verified |
+|-----|-------|--------|----------|
+| ADR-001 | Django + HTMX Architecture | Accepted | [ ] |
+| ADR-002 | Hybrid API Design Pattern | Accepted | [ ] |
+| ADR-003 | State Machine Pattern | Accepted | [ ] |
+| ADR-004 | Caching Strategy | Accepted | [ ] |
+| ADR-005 | Authentication Approach | Accepted | [ ] |
+| ADR-006 | Media Handling with Cloudflare | Accepted | [ ] |
+| ADR-007 | Logging Standardization Pattern | Accepted | [ ] |
+
+## Changelog Phases
+
+| Phase | Title | Documented |
+|-------|-------|------------|
+| Phase 3 | Logging & Observability | [x] |
+| Phase 4 | Models & Database | [x] |
+| Phase 5 | Admin Interface | [x] |
+| Phase 6 | Forms & Validation | [x] |
+| Phase 7 | Testing | [x] |
+| Phase 14 | Documentation | [x] |
+| Phase 15 | Documentation | [x] |
+
+## Documentation File Index
+
+### Root Level
+- `README.md` - Project overview
+- `CHANGELOG.md` - Version history
+- `.env.example` - Environment variables
+
+### /docs
+- `README.md` - Documentation index
+- `SETUP_GUIDE.md` - Development setup
+- `HEALTH_CHECKS.md` - Health monitoring
+- `PRODUCTION_CHECKLIST.md` - Deployment checklist
+- `THRILLWIKI_API_DOCUMENTATION.md` - API reference
+- `MANAGEMENT_COMMANDS.md` - Command reference
+- `FUTURE_WORK.md` - Deferred features
+- `DOCUMENTATION_REVIEW.md` - This checklist
+- `htmx-patterns.md` - HTMX conventions
+
+### /docs/architecture
+- `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`
+- `adr-007-logging-standardization.md`
+
+### /docs/configuration
+- `environment-variables.md` - Environment reference
+- `secret-management.md` - Secret handling
+
+### /docs/accessibility
+- `keyboard-navigation.md` - Keyboard shortcuts
+- `screen-reader-testing.md` - Testing checklist
+- `component-patterns.md` - Accessible patterns
+
+### /backend
+- `README.md` - Backend documentation
+
+### /backend/docs
+- `code_standards.md` - Coding standards
+- `forms_guide.md` - Form patterns
+
+## Verification Commands
+
+```bash
+# Check for broken internal links
+find docs -name "*.md" -exec grep -l "\[.*\](\./" {} \;
+
+# List all markdown files
+find . -name "*.md" -not -path "./node_modules/*" | sort
+
+# Check ADR numbering
+ls -la docs/architecture/adr-*.md
+
+# Verify changelog has all phases
+grep -E "^## \[Phase" CHANGELOG.md
+```
+
+## Sign-off
+
+| Reviewer | Date | Notes |
+|----------|------|-------|
+| | | |
+| | | |
--- a/docs/MANAGEMENT_COMMANDS.md
+++ b/docs/MANAGEMENT_COMMANDS.md
@@ -0,0 +1,756 @@
+# ThrillWiki Management Commands Reference
+
+Complete reference for all Django management commands in ThrillWiki.
+
+## Quick Index
+
+- [Configuration & Validation](#configuration--validation)
+- [Database Operations](#database-operations)
+- [Cache Management](#cache-management)
+- [Data Management](#data-management)
+- [User & Authentication](#user--authentication)
+- [Content & Media](#content--media)
+- [Trending & Discovery](#trending--discovery)
+- [Testing & Development](#testing--development)
+- [Security & Auditing](#security--auditing)
+
+## Configuration & Validation
+
+### validate_settings
+
+Validate all environment variables and configuration settings.
+
+**Usage:**
+```bash
+uv run manage.py validate_settings [options]
+```
+
+**Options:**
+- `--strict` - Treat warnings as errors
+- `--json` - Output results as JSON
+- `--secrets-only` - Only validate secrets
+
+**Example:**
+```bash
+# Validate all settings
+uv run manage.py validate_settings
+
+# Strict mode for CI/CD
+uv run manage.py validate_settings --strict
+
+# JSON output for automation
+uv run manage.py validate_settings --json
+```
+
+**Exit Codes:**
+- `0` - All validations passed
+- `1` - Validation failed
+
+**Related:**
+- [Environment Variables Reference](./configuration/environment-variables.md)
+- [Production Checklist](./PRODUCTION_CHECKLIST.md)
+
+---
+
+### validate_state_machines
+
+Validate all FSM state machine configurations.
+
+**Usage:**
+```bash
+uv run manage.py validate_state_machines
+```
+
+**Validates:**
+- State transition definitions
+- Transition callbacks
+- State field configurations
+- Permission requirements
+
+**Related:**
+- [ADR-003: State Machine Pattern](./architecture/adr-003-state-machine-pattern.md)
+
+---
+
+### list_transition_callbacks
+
+List all registered FSM transition callbacks.
+
+**Usage:**
+```bash
+uv run manage.py list_transition_callbacks
+```
+
+**Output:**
+- Model name
+- Transition name
+- Callback function
+- Source states
+- Target state
+
+---
+
+## Database Operations
+
+### migrate
+
+Apply database migrations.
+
+**Usage:**
+```bash
+uv run manage.py migrate [app_label] [migration_name]
+```
+
+**Example:**
+```bash
+# Apply all migrations
+uv run manage.py migrate
+
+# Apply specific app migrations
+uv run manage.py migrate parks
+
+# Migrate to specific migration
+uv run manage.py migrate parks 0005
+```
+
+---
+
+### makemigrations
+
+Create new migrations based on model changes.
+
+**Usage:**
+```bash
+uv run manage.py makemigrations [app_label]
+```
+
+**Example:**
+```bash
+# Create migrations for all apps
+uv run manage.py makemigrations
+
+# Create migrations for specific app
+uv run manage.py makemigrations parks
+```
+
+---
+
+### showmigrations
+
+Show all migrations and their status.
+
+**Usage:**
+```bash
+uv run manage.py showmigrations [app_label]
+```
+
+---
+
+### fix_migrations / fix_migration_history
+
+Fix migration history issues.
+
+**Usage:**
+```bash
+uv run manage.py fix_migrations
+uv run manage.py fix_migration_history
+```
+
+**Use Cases:**
+- Resolve migration conflicts
+- Fix corrupted migration history
+- Synchronize migration state
+
+---
+
+### reset_db
+
+Reset the database (DESTRUCTIVE - development only).
+
+**Usage:**
+```bash
+uv run manage.py reset_db
+```
+
+**Warning:** This command destroys all data. Only use in development.
+
+---
+
+## Cache Management
+
+### warm_cache
+
+Pre-populate cache with frequently accessed data.
+
+**Usage:**
+```bash
+uv run manage.py warm_cache [options]
+```
+
+**Options:**
+- `--dry-run` - Show what would be cached without caching
+- `--parks-only` - Only warm park-related caches
+- `--rides-only` - Only warm ride-related caches
+- `--metadata-only` - Only warm filter metadata caches
+- `--verbose` - Show detailed output
+
+**Example:**
+```bash
+# Warm all caches
+uv run manage.py warm_cache
+
+# Preview without caching
+uv run manage.py warm_cache --dry-run
+
+# Only warm park caches
+uv run manage.py warm_cache --parks-only --verbose
+```
+
+**Caches Warmed:**
+- Park list (top 500)
+- Ride list (top 1000)
+- Popular parks (top 20 by ride count)
+- Top-rated rides (top 20 by rating)
+- Park/ride status counts
+- Filter metadata
+
+**Performance:**
+- Typical execution time: 5-10 seconds
+- Reduces initial page load time by 50-70%
+
+**Related:**
+- [ADR-004: Caching Strategy](./architecture/adr-004-caching-strategy.md)
+
+---
+
+### clear_cache
+
+Clear all application caches.
+
+**Usage:**
+```bash
+uv run manage.py clear_cache
+```
+
+**Clears:**
+- Default cache
+- Session cache
+- API cache
+- Template cache
+
+**Use Cases:**
+- After data imports
+- After configuration changes
+- Troubleshooting cache issues
+
+---
+
+## Data Management
+
+### seed_initial_data
+
+Seed initial reference data (operators, manufacturers, etc.).
+
+**Usage:**
+```bash
+uv run manage.py seed_initial_data
+```
+
+**Creates:**
+- Major park operators (Disney, Universal, Six Flags, Cedar Fair)
+- Ride manufacturers (Intamin, B&M, RMC, Vekoma)
+- Ride designers
+- Initial categories and types
+
+**Idempotent:** Safe to run multiple times (uses get_or_create)
+
+---
+
+### create_sample_data
+
+Create comprehensive sample data for development.
+
+**Usage:**
+```bash
+uv run manage.py create_sample_data [options]
+```
+
+**Options:**
+- `--minimal` - Create minimal data for quick testing
+- `--clear` - Delete existing data before creating
+
+**Creates:**
+- 10-15 parks (major theme parks, regional parks, water parks)
+- 50-100 rides (coasters, flat rides, water rides)
+- 20-30 companies (operators, manufacturers)
+- 10 test users
+- 100-200 reviews
+- 50 photos
+
+**Example:**
+```bash
+# Full sample data
+uv run manage.py create_sample_data
+
+# Minimal for quick testing
+uv run manage.py create_sample_data --minimal
+
+# Clear and recreate
+uv run manage.py create_sample_data --clear
+```
+
+**Related:**
+- [FUTURE_WORK.md - THRILLWIKI-111](./FUTURE_WORK.md)
+
+---
+
+### seed_sample_data
+
+Seed sample parks and rides.
+
+**Usage:**
+```bash
+uv run manage.py seed_sample_data
+```
+
+---
+
+### seed_submissions
+
+Seed test submissions for moderation testing.
+
+**Usage:**
+```bash
+uv run manage.py seed_submissions
+```
+
+---
+
+### seed_data
+
+Seed API test data.
+
+**Usage:**
+```bash
+uv run manage.py seed_data
+```
+
+---
+
+### update_park_counts
+
+Update park statistics (ride counts, ratings).
+
+**Usage:**
+```bash
+uv run manage.py update_park_counts
+```
+
+**Updates:**
+- Total ride count per park
+- Roller coaster count per park
+- Average rating per park
+- Review count per park
+
+---
+
+### update_ride_rankings
+
+Update ride rankings.
+
+**Usage:**
+```bash
+uv run manage.py update_ride_rankings
+```
+
+**Updates:**
+- Global ride rankings
+- Category-specific rankings
+- Winning percentages
+- Head-to-head comparisons
+
+---
+
+## User & Authentication
+
+### create_test_users
+
+Create test users for development.
+
+**Usage:**
+```bash
+uv run manage.py create_test_users
+```
+
+**Creates:**
+- Admin user
+- Moderator user
+- Regular test users
+
+---
+
+### delete_user
+
+Delete a user and all related data.
+
+**Usage:**
+```bash
+uv run manage.py delete_user <username>
+```
+
+**Example:**
+```bash
+uv run manage.py delete_user testuser
+```
+
+---
+
+### setup_groups
+
+Setup user groups and permissions.
+
+**Usage:**
+```bash
+uv run manage.py setup_groups
+```
+
+**Creates:**
+- Moderators group
+- Editors group
+- Contributors group
+- Appropriate permissions for each group
+
+---
+
+### setup_site
+
+Setup Django sites framework.
+
+**Usage:**
+```bash
+uv run manage.py setup_site
+```
+
+---
+
+### Social Authentication Commands
+
+```bash
+# Full social auth setup
+uv run manage.py setup_social_auth
+
+# Setup social providers
+uv run manage.py setup_social_providers
+
+# Create social apps
+uv run manage.py create_social_apps
+
+# Check social apps configuration
+uv run manage.py check_social_apps
+
+# Fix social apps issues
+uv run manage.py fix_social_apps
+
+# Reset social apps
+uv run manage.py reset_social_apps
+
+# Reset all social auth
+uv run manage.py reset_social_auth
+
+# Cleanup social auth
+uv run manage.py cleanup_social_auth
+
+# Update social apps sites
+uv run manage.py update_social_apps_sites
+
+# Discord-specific
+uv run manage.py verify_discord_settings
+uv run manage.py test_discord_auth
+
+# Check all social tables
+uv run manage.py check_all_social_tables
+
+# Setup social auth admin
+uv run manage.py setup_social_auth_admin
+```
+
+---
+
+### Avatar Management
+
+```bash
+# Generate letter avatars
+uv run manage.py generate_letter_avatars
+
+# Regenerate all avatars
+uv run manage.py regenerate_avatars
+```
+
+---
+
+## Content & Media
+
+### collectstatic
+
+Collect static files for deployment.
+
+**Usage:**
+```bash
+uv run manage.py collectstatic [--noinput]
+```
+
+**Example:**
+```bash
+# Interactive
+uv run manage.py collectstatic
+
+# Non-interactive (for CI/CD)
+uv run manage.py collectstatic --noinput
+```
+
+---
+
+### optimize_static
+
+Minify and compress static files.
+
+**Usage:**
+```bash
+uv run manage.py optimize_static
+```
+
+---
+
+### Media File Commands
+
+```bash
+# Download photos
+uv run manage.py download_photos
+
+# Move photos to correct locations
+uv run manage.py move_photos
+
+# Fix photo path issues
+uv run manage.py fix_photo_paths
+```
+
+---
+
+## Trending & Discovery
+
+### calculate_trending
+
+Calculate trending content.
+
+**Usage:**
+```bash
+uv run manage.py calculate_trending
+```
+
+**Calculates:**
+- Trending parks (based on views, reviews, activity)
+- Trending rides (based on views, reviews, activity)
+- Trending users (based on contributions)
+
+---
+
+### update_trending
+
+Update trending content.
+
+**Usage:**
+```bash
+uv run manage.py update_trending
+```
+
+---
+
+### test_trending
+
+Test trending calculation.
+
+**Usage:**
+```bash
+uv run manage.py test_trending
+```
+
+---
+
+### calculate_new_content
+
+Calculate new content for discovery.
+
+**Usage:**
+```bash
+uv run manage.py calculate_new_content
+```
+
+---
+
+## Testing & Development
+
+### rundev
+
+Run development server with auto-reload.
+
+**Usage:**
+```bash
+uv run manage.py rundev
+```
+
+**Features:**
+- Auto-reload on file changes
+- Debug mode enabled
+- Development settings
+
+---
+
+### setup_dev
+
+Setup development environment.
+
+**Usage:**
+```bash
+uv run manage.py setup_dev
+```
+
+**Performs:**
+- Creates required directories
+- Generates development config files
+- Sets up development database
+
+---
+
+### test_location
+
+Test location services.
+
+**Usage:**
+```bash
+uv run manage.py test_location
+```
+
+---
+
+### test_transition_callbacks
+
+Test FSM transition callbacks.
+
+**Usage:**
+```bash
+uv run manage.py test_transition_callbacks
+```
+
+---
+
+### analyze_transitions
+
+Analyze FSM transitions.
+
+**Usage:**
+```bash
+uv run manage.py analyze_transitions
+```
+
+---
+
+### cleanup_test_data
+
+Cleanup test data.
+
+**Usage:**
+```bash
+uv run manage.py cleanup_test_data
+```
+
+---
+
+## Security & Auditing
+
+### security_audit
+
+Run security audit.
+
+**Usage:**
+```bash
+uv run manage.py security_audit
+```
+
+**Checks:**
+- Security header configuration
+- HTTPS settings
+- Cookie security
+- CSRF protection
+- Rate limiting configuration
+
+---
+
+## Command Cheat Sheet
+
+| Task | Command |
+|------|---------|
+| Validate configuration | `uv run manage.py validate_settings --strict` |
+| Warm cache | `uv run manage.py warm_cache` |
+| Clear cache | `uv run manage.py clear_cache` |
+| Seed initial data | `uv run manage.py seed_initial_data` |
+| Create sample data | `uv run manage.py create_sample_data --minimal` |
+| Run development server | `uv run manage.py rundev` |
+| Setup development | `uv run manage.py setup_dev` |
+| Create test users | `uv run manage.py create_test_users` |
+| Update trending | `uv run manage.py calculate_trending` |
+| Security audit | `uv run manage.py security_audit` |
+
+## Common Workflows
+
+### Initial Development Setup
+```bash
+uv run manage.py migrate
+uv run manage.py createsuperuser
+uv run manage.py setup_groups
+uv run manage.py seed_initial_data
+uv run manage.py create_sample_data --minimal
+uv run manage.py warm_cache
+uv run manage.py rundev
+```
+
+### Production Deployment
+```bash
+uv run manage.py validate_settings --strict
+uv run manage.py migrate
+uv run manage.py collectstatic --noinput
+uv run manage.py warm_cache
+```
+
+### Cache Refresh After Data Import
+```bash
+uv run manage.py clear_cache
+uv run manage.py update_park_counts
+uv run manage.py update_ride_rankings
+uv run manage.py calculate_trending
+uv run manage.py warm_cache
+```
+
+### Development Reset
+```bash
+uv run manage.py reset_db
+uv run manage.py migrate
+uv run manage.py create_sample_data
+uv run manage.py warm_cache
+```
+
+### Social Auth Setup
+```bash
+uv run manage.py setup_site
+uv run manage.py setup_social_auth
+uv run manage.py check_social_apps
+```
+
+### Full Test Environment
+```bash
+uv run manage.py migrate
+uv run manage.py seed_initial_data
+uv run manage.py create_sample_data
+uv run manage.py create_test_users
+uv run manage.py seed_submissions
+uv run manage.py warm_cache
+```
--- a/docs/PRODUCTION_CHECKLIST.md
+++ b/docs/PRODUCTION_CHECKLIST.md
@@ -8,6 +8,13 @@ Use this checklist to verify your ThrillWiki deployment is production-ready.

 ## Pre-Deployment

+### Configuration Validation
+
+- [ ] Run `uv run manage.py validate_settings --strict` with no errors
+- [ ] Run `uv run manage.py validate_state_machines` with no errors
+- [ ] Run `uv run manage.py check --deploy` with no warnings
+- [ ] All management commands execute without errors
+
 ### Environment Configuration

 > **Important:** These variables are **required** for production. See [Environment Variables Reference](./configuration/environment-variables.md#production-required-variables) for detailed documentation.
@@ -123,6 +130,12 @@ Use this checklist to verify your ThrillWiki deployment is production-ready.
 - [ ] API endpoints respond correctly
 - [ ] Image uploads work

+### Cache Verification
+
+- [ ] Run `uv run manage.py warm_cache` successfully
+- [ ] Verify cache hit rate > 80% after warm-up
+- [ ] Check Redis memory usage is within limits
+
 ### Performance Tests

 - [ ] Page load time < 3 seconds
--- a/docs/README.md
+++ b/docs/README.md
@@ -277,6 +277,31 @@ See [API Documentation](./THRILLWIKI_API_DOCUMENTATION.md) for complete endpoint
 - [Screen Reader Testing](./accessibility/screen-reader-testing.md) - Testing checklist
 - [Component Patterns](./accessibility/component-patterns.md) - Accessible patterns

+## Management Commands
+
+ThrillWiki provides 50+ management commands for various operations. See [Backend README - Management Commands](../backend/README.md#management-commands) for complete documentation.
+
+### Quick Reference
+
+```bash
+# Configuration
+uv run manage.py validate_settings
+
+# Cache management
+uv run manage.py warm_cache
+uv run manage.py clear_cache
+
+# Data seeding
+uv run manage.py seed_initial_data
+uv run manage.py create_sample_data
+
+# Development
+uv run manage.py rundev
+uv run manage.py setup_dev
+```
+
+See [Management Commands Reference](./MANAGEMENT_COMMANDS.md) for complete command documentation.
+
 ## Testing

 ### Running Tests
--- a/docs/THRILLWIKI_API_DOCUMENTATION.md
+++ b/docs/THRILLWIKI_API_DOCUMENTATION.md
@@ -1243,6 +1243,18 @@ headers: {

 All error responses follow a consistent format with appropriate HTTP status codes.

+### Error Logging
+
+All API errors are logged with full context for debugging:
+- Request details (method, path, user)
+- Error type and message
+- Stack trace (for 500 errors)
+- Request payload (sanitized)
+
+Logs are sent to Sentry in production for monitoring.
+
+See [ADR-007: Logging Standardization](./architecture/adr-007-logging-standardization.md) for details.
+
 ### Error Response Structure
 ```json
 {
--- a/docs/architecture/README.md
+++ b/docs/architecture/README.md
@@ -20,6 +20,7 @@ An Architecture Decision Record is a document that captures an important archite
 | [ADR-004](./adr-004-caching-strategy.md) | Caching Strategy | Accepted | 2025-01 |
 | [ADR-005](./adr-005-authentication-approach.md) | Authentication Approach | Accepted | 2025-01 |
 | [ADR-006](./adr-006-media-handling-cloudflare.md) | Media Handling with Cloudflare | Accepted | 2025-01 |
+| [ADR-007](./adr-007-logging-standardization.md) | Logging Standardization Pattern | Accepted | 2025-01 |

 ## ADR Template

--- a/docs/architecture/adr-007-logging-standardization.md
+++ b/docs/architecture/adr-007-logging-standardization.md
@@ -0,0 +1,216 @@
+# ADR-007: Logging Standardization Pattern
+
+## Status
+
+Accepted
+
+## Context
+
+As the ThrillWiki application grew, logging patterns became inconsistent across different modules. Some files had no logging, others used print statements, and logging levels were applied inconsistently. This made debugging production issues difficult and prevented effective monitoring.
+
+The team needed:
+- Consistent logging patterns across all modules
+- Structured logging with contextual information
+- Security event tracking for compliance
+- Performance monitoring capabilities
+- Integration with centralized logging systems (Sentry, CloudWatch)
+
+## Decision
+
+We implemented a **standardized logging pattern** with centralized utilities for structured logging.
+
+### Core Pattern
+
+Every module initializes a logger using Python's standard logging:
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+```
+
+### Centralized Logging Utilities
+
+Created `apps.core.logging` module with specialized logging functions:
+
+1. **`log_exception(logger, exception, context, request)`**
+   - Logs exceptions with full stack trace
+   - Includes request context (user, IP, path)
+   - Automatically sends to Sentry in production
+
+2. **`log_business_event(logger, event_type, message, context, request)`**
+   - Logs significant business operations
+   - Used for FSM transitions, user actions, data changes
+   - Structured format for analytics
+
+3. **`log_security_event(logger, event_type, message, severity, context, request)`**
+   - Logs authentication and authorization events
+   - Tracks security-relevant actions
+   - Supports compliance auditing
+
+### Log Levels
+
+Standardized log level usage:
+
+| Level | Usage |
+|-------|-------|
+| `DEBUG` | Detailed diagnostic information (disabled in production) |
+| `INFO` | General operational events (user actions, searches) |
+| `WARNING` | Unexpected conditions that don't prevent operation |
+| `ERROR` | Error conditions requiring attention |
+| `CRITICAL` | System failures requiring immediate action |
+
+### Logging Configuration
+
+Modular logging configuration in `config/settings/logging.py`:
+
+```python
+LOGGING = {
+    'version': 1,
+    'disable_existing_loggers': False,
+    'formatters': {
+        'json': {
+            '()': 'pythonjsonlogger.jsonlogger.JsonFormatter',
+            'format': '%(asctime)s %(name)s %(levelname)s %(message)s',
+        },
+        'verbose': {
+            'format': '{levelname} {asctime} {name} {message}',
+            'style': '{',
+        },
+    },
+    'handlers': {
+        'console': {
+            'class': 'logging.StreamHandler',
+            'formatter': 'verbose',
+        },
+        'file': {
+            'class': 'logging.handlers.RotatingFileHandler',
+            'filename': 'logs/django.log',
+            'maxBytes': 10485760,  # 10MB
+            'backupCount': 5,
+            'formatter': 'json',
+        },
+        'sentry': {
+            'class': 'sentry_sdk.integrations.logging.EventHandler',
+            'level': 'ERROR',
+        },
+    },
+    'loggers': {
+        'django': {
+            'handlers': ['console', 'file'],
+            'level': 'INFO',
+        },
+        'apps': {
+            'handlers': ['console', 'file', 'sentry'],
+            'level': 'INFO',
+            'propagate': False,
+        },
+    },
+}
+```
+
+## Consequences
+
+### Benefits
+
+1. **Consistent Debugging**: All modules log in the same format
+2. **Structured Logs**: JSON format enables log aggregation and analysis
+3. **Security Auditing**: Dedicated security event logging for compliance
+4. **Performance Monitoring**: Cache and query performance tracking
+5. **Production Monitoring**: Integration with Sentry for error tracking
+6. **Contextual Information**: All logs include user, request, and operation context
+
+### Trade-offs
+
+1. **Verbosity**: More logging code in each module
+2. **Performance**: Logging has minimal overhead (~1-2ms per log)
+3. **Storage**: JSON logs consume more disk space than plain text
+4. **Learning Curve**: Developers must learn when to use each logging function
+
+### Implementation Guidelines
+
+1. **Logger Initialization**: Every view, service, and middleware file must initialize a logger
+2. **Exception Handling**: Always use `log_exception()` in exception handlers
+3. **Business Events**: Use `log_business_event()` for FSM transitions and significant actions
+4. **Security Events**: Use `log_security_event()` for authentication and authorization
+5. **Sensitive Data**: Never log passwords, tokens, session IDs, or PII
+
+### Example Usage
+
+```python
+import logging
+from apps.core.logging import log_exception, log_business_event, log_security_event
+
+logger = logging.getLogger(__name__)
+
+class ParkDetailView(DetailView):
+    def get_object(self):
+        try:
+            park = super().get_object()
+            logger.info(f"Park viewed: {park.name}", extra={
+                'park_id': park.id,
+                'user_id': self.request.user.id if self.request.user.is_authenticated else None,
+            })
+            return park
+        except Park.DoesNotExist as e:
+            log_exception(
+                logger,
+                e,
+                context={'slug': self.kwargs.get('slug')},
+                request=self.request,
+            )
+            raise
+
+    def post(self, request, *args, **kwargs):
+        park = self.get_object()
+        old_status = park.status
+        park.approve()
+        park.save()
+
+        log_business_event(
+            logger,
+            event_type='fsm_transition',
+            message=f'Park approved: {park.name}',
+            context={
+                'model': 'Park',
+                'object_id': park.id,
+                'old_state': old_status,
+                'new_state': park.status,
+            },
+            request=request,
+        )
+
+        return redirect('park_detail', slug=park.slug)
+```
+
+## Alternatives Considered
+
+### Django Debug Toolbar Only
+
+**Rejected because:**
+- Only works in development
+- No production monitoring
+- No structured logging
+- No security event tracking
+
+### Third-Party Logging Service (Datadog, New Relic)
+
+**Rejected because:**
+- High cost for small team
+- Vendor lock-in
+- Sentry + CloudWatch sufficient for current needs
+
+### Print Statements
+
+**Rejected because:**
+- Not configurable
+- No log levels
+- No structured format
+- Not production-ready
+
+## References
+
+- [Python Logging Documentation](https://docs.python.org/3/library/logging.html)
+- [Django Logging Documentation](https://docs.djangoproject.com/en/5.0/topics/logging/)
+- [Sentry Integration](https://docs.sentry.io/platforms/python/guides/django/)
+- [Code Standards - Logging](../../backend/docs/code_standards.md#logging-standards)