thrillwiki_django_no_react/memory-bank/projects/django-to-symfony-conversion/01-source-analysis-overview.md

Django ThrillWiki Source Analysis - Symfony Conversion Foundation

Date: January 7, 2025
Analyst: Roo (Architect Mode)
Purpose: Complete analysis of Django ThrillWiki for Symfony conversion planning
Status: Source Analysis Phase - Complete Foundation Documentation

Executive Summary

This document provides a comprehensive analysis of the current Django ThrillWiki implementation to serve as the definitive source for planning and executing a Symfony conversion. The analysis covers all architectural layers, entity relationships, features, and implementation patterns that must be replicated or adapted in Symfony.

Project Overview

ThrillWiki is a sophisticated Django-based theme park and ride database application featuring:

• 18 Django Apps with distinct responsibilities
• PostgreSQL + PostGIS for geographic data
• HTMX + Tailwind CSS for modern frontend interactions
• Comprehensive history tracking via django-pghistory
• User-generated content with moderation workflows
• Social authentication and role-based access control
• Advanced search and autocomplete functionality
• Media management with approval workflows

Source Architecture Analysis

Core Framework Stack

Django 5.0+ (Python 3.11+)
├── Database: PostgreSQL + PostGIS
├── Frontend: HTMX + Tailwind CSS + Alpine.js
├── Authentication: django-allauth (Google, Discord)
├── History: django-pghistory + pgtrigger
├── Media: Pillow + django-cleanup
├── Testing: Playwright + pytest
└── Package Management: UV

Django Apps Architecture

Core Entity Apps (Business Logic)

1. parks - Theme park management with geographic location
2. rides - Ride database with detailed specifications
3. operators - Companies that operate parks
4. property_owners - Companies that own park property
5. manufacturers - Companies that manufacture rides
6. designers - Companies/individuals that design rides

User Management Apps

7. accounts - Extended User model with profiles and top lists
8. reviews - User review system with ratings and photos

Content Management Apps

9. media - Photo management with approval workflow
10. moderation - Content moderation and submission system

Supporting Service Apps

11. location - Geographic services with PostGIS
12. analytics - Page view tracking and trending content
13. search - Global search across all content types
14. history_tracking - Change tracking and audit trails
15. email_service - Email management and notifications

Infrastructure Apps

16. core - Shared utilities and base classes
17. avatars - User avatar management
18. history - History visualization and timeline

Entity Relationship Model

Primary Entities & Relationships

erDiagram
    Park ||--|| Operator : "operated_by (required)"
    Park ||--o| PropertyOwner : "owned_by (optional)"
    Park ||--o{ ParkArea : "contains"
    Park ||--o{ Ride : "hosts"
    Park ||--o{ Location : "located_at"
    Park ||--o{ Photo : "has_photos"
    Park ||--o{ Review : "has_reviews"
    
    Ride ||--|| Park : "belongs_to (required)"
    Ride ||--o| ParkArea : "located_in"
    Ride ||--o| Manufacturer : "manufactured_by"
    Ride ||--o| Designer : "designed_by"
    Ride ||--o| RideModel : "instance_of"
    Ride ||--o| RollerCoasterStats : "has_stats"
    
    User ||--|| UserProfile : "has_profile"
    User ||--o{ Review : "writes"
    User ||--o{ TopList : "creates"
    User ||--o{ EditSubmission : "submits"
    User ||--o{ PhotoSubmission : "uploads"
    
    RideModel ||--o| Manufacturer : "manufactured_by"
    RideModel ||--o{ Ride : "installed_as"

Key Entity Definitions (Per .clinerules)

• Parks MUST have an Operator (required relationship)
• Parks MAY have a PropertyOwner (optional, usually same as Operator)
• Rides MUST belong to a Park (required relationship)
• Rides MAY have Manufacturer/Designer (optional relationships)
• Operators/PropertyOwners/Manufacturers/Designers are distinct entity types
• No direct Company entity references (replaced by specific entity types)

Django-Specific Implementation Patterns

1. Model Architecture Patterns

TrackedModel Base Class

@pghistory.track()
class Park(TrackedModel):
    # Automatic history tracking for all changes
    # Slug management with historical preservation
    # Generic relations for photos/reviews/locations

Generic Foreign Keys

# Photos can be attached to any model
photos = GenericRelation(Photo, related_query_name='park')

# Reviews can be for parks, rides, etc.
content_type = models.ForeignKey(ContentType)
object_id = models.PositiveIntegerField()
content_object = GenericForeignKey('content_type', 'object_id')

PostGIS Geographic Fields

# Location model with geographic data
location = models.PointField(geography=True, null=True, blank=True)
coordinates = models.JSONField(default=dict, blank=True)  # Legacy support

2. Authentication & Authorization

Extended User Model

class User(AbstractUser):
    ROLE_CHOICES = [
        ('USER', 'User'),
        ('MODERATOR', 'Moderator'), 
        ('ADMIN', 'Admin'),
        ('SUPERUSER', 'Superuser'),
    ]
    role = models.CharField(max_length=20, choices=ROLE_CHOICES, default='USER')
    user_id = models.CharField(max_length=20, unique=True)  # Public ID

Social Authentication

• Google OAuth2 integration
• Discord OAuth2 integration
• Turnstile CAPTCHA protection
• Email verification workflows

3. Frontend Architecture

HTMX Integration

# HTMX-aware views
def search_suggestions(request):
    if request.htmx:
        return render(request, 'search/partials/suggestions.html', context)
    return render(request, 'search/full_page.html', context)

Template Organization

templates/
├── base/ - Base layouts and components
├── [app]/ - App-specific templates
│   └── partials/ - HTMX partial templates
├── account/ - Authentication templates
└── pages/ - Static pages

4. Content Moderation System

Submission Workflow

class EditSubmission(models.Model):
    STATUS_CHOICES = [
        ('PENDING', 'Pending Review'),
        ('APPROVED', 'Approved'),
        ('REJECTED', 'Rejected'),
        ('ESCALATED', 'Escalated'),
    ]
    # Auto-approval for moderators
    # Duplicate detection
    # Change tracking

5. Media Management

Photo Model with Approval

class Photo(models.Model):
    # Generic foreign key for any model association
    # EXIF data extraction
    # Approval workflow
    # Custom storage backend
    # Automatic file organization

Database Schema Analysis

Key Tables Structure

Core Content Tables

• parks_park - Main park entity
• parks_parkarea - Park themed areas
• rides_ride - Individual ride installations
• rides_ridemodel - Manufacturer ride types
• rides_rollercoasterstats - Detailed coaster specs

Entity Relationship Tables

• operators_operator - Park operating companies
• property_owners_propertyowner - Property ownership
• manufacturers_manufacturer - Ride manufacturers
• designers_designer - Ride designers

User & Content Tables

• accounts_user - Extended Django user
• accounts_userprofile - User profiles and stats
• media_photo - Generic photo storage
• reviews_review - User reviews with ratings
• moderation_editsubmission - Content submissions

Supporting Tables

• location_location - Geographic data with PostGIS
• analytics_pageview - Usage tracking
• history_tracking_* - Change audit trails

History Tables (pghistory)

• *_*event - Automatic history tracking for all models
• Complete audit trail of all changes
• Trigger-based implementation

URL Structure Analysis

Main URL Patterns

/ - Home with trending content
/admin/ - Django admin interface
/parks/{slug}/ - Park detail pages
/rides/{slug}/ - Ride detail pages
/operators/{slug}/ - Operator profiles
/manufacturers/{slug}/ - Manufacturer profiles
/designers/{slug}/ - Designer profiles
/search/ - Global search interface
/ac/ - Autocomplete endpoints (HTMX)
/accounts/ - User authentication
/moderation/ - Content moderation
/history/ - Change history timeline

SEO & Routing Features

• SEO-friendly slugs for all content
• Historical slug support with automatic redirects
• HTMX-compatible partial endpoints
• RESTful resource organization

Form System Analysis

Key Form Types

1. Authentication Forms - Login/signup with Turnstile CAPTCHA
2. Content Forms - Park/ride creation and editing
3. Upload Forms - Photo uploads with validation
4. Review Forms - User rating and review submission
5. Moderation Forms - Edit approval workflows

Form Features

• HTMX integration for dynamic interactions
• Comprehensive server-side validation
• File upload handling with security
• CSRF protection throughout

Search & Autocomplete System

Search Implementation

# Global search across multiple models
def global_search(query):
    parks = Park.objects.filter(name__icontains=query)
    rides = Ride.objects.filter(name__icontains=query)
    operators = Operator.objects.filter(name__icontains=query)
    # Combine and rank results

Autocomplete Features

• HTMX-powered suggestions
• Real-time search as you type
• Multiple entity type support
• Configurable result limits

Dependencies & Packages

Core Django Packages

Django = "^5.0"
psycopg2-binary = ">=2.9.9"  # PostgreSQL adapter
django-allauth = ">=0.60.1"  # Social auth
django-pghistory = ">=3.5.2"  # History tracking
django-htmx = ">=1.17.2"  # HTMX integration
django-cleanup = ">=8.0.0"  # File cleanup
django-filter = ">=23.5"  # Advanced filtering
whitenoise = ">=6.6.0"  # Static file serving

Geographic & Media

# PostGIS support requires system libraries:
# GDAL_LIBRARY_PATH, GEOS_LIBRARY_PATH
Pillow = ">=10.2.0"  # Image processing

Development & Testing

playwright = ">=1.41.0"  # E2E testing
pytest-django = ">=4.9.0"  # Unit testing
django-tailwind-cli = ">=2.21.1"  # CSS framework

Key Django Features Utilized

1. Admin Interface

• Heavily customized admin for all models
• Bulk operations and advanced filtering
• Moderation workflow integration
• History tracking display

2. Middleware Stack

MIDDLEWARE = [
    'django.middleware.cache.UpdateCacheMiddleware',
    'whitenoise.middleware.WhiteNoiseMiddleware',
    'core.middleware.PgHistoryContextMiddleware',
    'analytics.middleware.PageViewMiddleware',
    'django_htmx.middleware.HtmxMiddleware',
    # ... standard Django middleware
]

3. Context Processors

TEMPLATES = [{
    'OPTIONS': {
        'context_processors': [
            'moderation.context_processors.moderation_access',
            # ... standard processors
        ]
    }
}]

4. Custom Management Commands

• Data import/export utilities
• Maintenance and cleanup scripts
• Analytics processing
• Content moderation helpers

Static Assets & Frontend

CSS Architecture

• Tailwind CSS utility-first approach
• Custom CSS in static/css/src/
• Component-specific styles
• Dark mode support

JavaScript Strategy

• Minimal custom JavaScript
• HTMX for dynamic interactions
• Alpine.js for UI components
• Progressive enhancement approach

Media Organization

media/
├── avatars/ - User profile pictures
├── park/[slug]/ - Park-specific photos
├── ride/[slug]/ - Ride-specific photos
└── submissions/ - User-uploaded content

Performance & Optimization

Database Optimization

• Proper indexing on frequently queried fields
• select_related() and prefetch_related() usage
• Generic foreign key indexing
• PostGIS spatial indexing

Caching Strategy

• Basic Django cache framework
• Trending content caching
• Static file optimization via WhiteNoise
• HTMX partial caching

Geographic Performance

• PostGIS Point fields for efficient spatial queries
• Distance calculations and nearby location queries
• Legacy coordinate support during migration

Security Implementation

Authentication Security

• Role-based access control (USER, MODERATOR, ADMIN, SUPERUSER)
• Social login with OAuth2
• Turnstile CAPTCHA protection
• Email verification workflows

Data Security

• Django ORM prevents SQL injection
• CSRF protection on all forms
• File upload validation and security
• User input sanitization

Authorization Patterns

# Role-based access in views
@user_passes_test(lambda u: u.role in ['MODERATOR', 'ADMIN'])
def moderation_view(request):
    # Moderator-only functionality

Testing Strategy

Test Structure

tests/
├── e2e/ - Playwright browser tests
├── fixtures/ - Test data fixtures
└── [app]/tests/ - Django unit tests

Testing Approach

• Playwright for end-to-end browser testing
• pytest-django for unit tests
• Fixture-based test data management
• Coverage reporting for quality assurance

Conversion Implications

This Django implementation presents several key considerations for Symfony conversion:

1. Entity Framework Mapping

• Django's ORM patterns → Doctrine ORM
• Generic foreign keys → Polymorphic associations
• PostGIS fields → Geographic types
• History tracking → Event sourcing or audit bundles

2. Authentication System

• django-allauth → Symfony Security + OAuth bundles
• Role-based access → Voter system
• Social login → KnpUOAuth2ClientBundle

3. Frontend Architecture

• HTMX integration → Symfony UX + Stimulus
• Template system → Twig templates
• Static assets → Webpack Encore

4. Content Management

• Django admin → EasyAdmin or Sonata
• Moderation workflow → Custom service layer
• File uploads → VichUploaderBundle

5. Geographic Features

• PostGIS → Doctrine DBAL geographic types
• Spatial queries → Custom repository methods

Next Steps for Conversion Planning

1. Entity Mapping - Map Django models to Doctrine entities
2. Bundle Selection - Choose appropriate Symfony bundles for each feature
3. Database Migration - Plan PostgreSQL schema adaptation
4. Authentication Migration - Design Symfony Security implementation
5. Frontend Strategy - Plan Twig + Stimulus architecture
6. Testing Migration - Adapt test suite to PHPUnit

References

• memory-bank/documentation/complete-project-review-2025-01-05.md - Complete Django analysis
• memory-bank/activeContext.md - Current project status
• .clinerules - Project entity relationship rules

---

Status: ✅ COMPLETED - Source analysis foundation established
Next: Entity mapping and Symfony bundle selection planning