thrillwiki_django_no_react/memory-bank/documentation/Architecture.md

System Architecture Documentation

Overview

ThrillWiki is a Django-based web platform built with a modular architecture focusing on theme park information management, user reviews, and content moderation.

Technology Stack

Backend

• Framework: Django 5.1.6
• API: Django REST Framework 3.15.2
• WebSocket Support: Channels 4.2.0 with Redis
• Authentication: django-allauth, OAuth Toolkit
• Database: PostgreSQL with django-pghistory

Frontend

• Templating: Django Templates
• CSS Framework: Tailwind CSS
• Enhancement: HTMX, JavaScript
• Asset Management: django-webpack-loader

Infrastructure

• Static Files: WhiteNoise 6.9.0
• Media Storage: Local filesystem with custom storage backends
• Caching: Redis (shared with WebSocket layer)

System Components

Core Applications

1. Parks Module

   • Park information management
   • Geographic data handling
   • Operating hours tracking
   • Integration with location services

2. Rides Module

   • Ride specifications
   • Manufacturer/Designer attribution
   • Historical data tracking
   • Technical details management

3. Reviews System

   • User-generated content
   • Media attachments
   • Rating framework
   • Integration with moderation

4. Moderation System

   • Content review workflow
   • Quality control mechanisms
   • User management
   • Verification processes

5. Companies Module

   • Company profiles
   • Verification system
   • Official update management
   • Park operator features

Service Layer

1. Authentication Service

   # Key authentication flows
   User Authentication → JWT Token → Protected Resources
   Social Auth → Profile Creation → Platform Access
   

2. Media Service

   # Media handling workflow
   Upload → Processing → Storage → Delivery
   

3. Analytics Service

   # Analytics pipeline
   User Action → Event Tracking → Processing → Insights
   

Data Flow Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Client    │ ──→ │   Django     │ ──→ │  Database   │
│   Browser   │ ←── │   Server     │ ←── │  (Postgres) │
└─────────────┘     └──────────────┘     └─────────────┘
                          ↑ ↓
                    ┌──────────────┐
                    │   Services   │
                    │  (Redis/S3)  │
                    └──────────────┘

Security Architecture

1. Authentication Flow

   • JWT-based authentication
   • Social authentication integration
   • Session management
   • Permission-based access control

2. Data Protection

   • Input validation
   • XSS prevention
   • CSRF protection
   • SQL injection prevention

Deployment Model

Production Environment

├── Application Server (Daphne/ASGI)
├── Database (PostgreSQL)
├── Cache/Message Broker (Redis)
├── Static Files (WhiteNoise)
└── Media Storage (Filesystem/S3)

Development Environment

├── Local Django Server
├── Local PostgreSQL
├── Local Redis
└── Local File Storage

Monitoring and Scaling

1. Performance Monitoring

   • Page load metrics
   • Database query analysis
   • Cache hit rates
   • API response times

2. Scaling Strategy

   • Horizontal scaling of web servers
   • Database read replicas
   • Cache layer expansion
   • Media CDN integration

Search Architecture

Search Infrastructure

• Base Pattern: BaseAutocomplete provides authentication-first autocomplete foundation
• Park Search: ParkAutocomplete + ParkSearchForm with HTMX integration
• Ride Search: Planned extension following same pattern with park relationship context

Search Components

1. Autocomplete Layer

   • Authentication requirement enforced at base level
   • Query limiting (10 results) for performance
   • HTMX-driven real-time suggestions

2. Form Layer

   • Django forms with autocomplete widgets
   • Filter integration for advanced search
   • Clean validation and error handling

3. Frontend Integration

   • HTMX for dynamic updates (hx-get, hx-trigger)
   • AlpineJS for local state management
   • Tailwind CSS for consistent styling

Database Optimization

• Indexes on searchable fields (name, foreign keys)
• select_related() for relationship queries
• Query result limiting for performance

Integration Points

1. External Services

   • Email service (ForwardEmail.net)
   • Social authentication providers
   • Geographic data services
   • Media processing services

2. Internal Services

   • WebSocket notifications
   • Background tasks
   • Media processing
   • Analytics processing

System Requirements

Minimum Requirements

• Python 3.11+
• PostgreSQL 13+
• Redis 6+
• Node.js 18+ (for frontend builds)

Development Tools

• black (code formatting)
• flake8 (linting)
• pytest (testing)
• tailwind CLI (CSS processing)