thrillwiki_django_no_react/docs/project_documentation.md

# ThrillWiki Project Documentation

## Overview
ThrillWiki is a comprehensive Django-based web application for managing and sharing information about amusement parks, rides, and attractions. The platform allows users to explore parks, review rides, share photos, and track various statistics about amusement parks and rides worldwide.

## System Architecture

### Core Applications

1. **Parks App**
   - Manages amusement park information
   - Handles park areas and locations
   - Tracks park statistics and operating status

2. **Rides App**
   - Manages ride information and categories
   - Tracks detailed roller coaster statistics
   - Links rides to parks, manufacturers, and designers

3. **Companies App**
   - Handles park ownership information
   - Manages ride manufacturers
   - Tracks company statistics and history

4. **Designers App**
   - Manages ride designer/engineering firm information
   - Tracks designer contributions and history

5. **Media App**
   - Handles photo uploads and management
   - Supports generic relationships for photos
   - Manages media storage and organization

6. **Reviews App**
   - Manages user reviews and ratings
   - Handles review moderation
   - Supports review images and likes

7. **Analytics App**
   - Tracks page views and user interactions
   - Identifies trending content
   - Provides analytics data for the platform

### Authentication & User Management
- Custom user model through accounts app
- Social authentication support (Google, Discord)
- User profiles and settings management

## Data Models

### Park Models
```python
class Park:
    - name, slug, description
    - status (Operating, Closed, etc.)
    - location (latitude, longitude, address)
    - operating details (season, dates)
    - statistics (total rides, coasters)
    - ownership information
```

### Ride Models
```python
class Ride:
    - name, slug, description
    - category (Roller Coaster, Dark Ride, etc.)
    - status and operating dates
    - manufacturer and designer links
    - park and area location
    - accessibility and capacity info

class RollerCoasterStats:
    - height, length, speed metrics
    - track type and materials
    - launch system details
    - train configuration
```

### Company Models
```python
class Company:
    - name, slug, description
    - headquarters and contact info
    - park ownership tracking
    - historical records

class Manufacturer:
    - name, slug, description
    - ride production statistics
    - historical records
```

### Media Management
```python
class Photo:
    - Generic relationship to content
    - Image storage and organization
    - Caption and metadata
    - Upload tracking
```

### Review System
```python
class Review:
    - Generic relationship to content
    - Rating and content
    - Moderation support
    - Image attachments
    - Like/report functionality
```

### Analytics
```python
class PageView:
    - Content tracking
    - Timestamp and user info
    - Trending content calculation
```

## Key Features

### Content Management
- Comprehensive park and ride information
- Historical tracking of all content changes
- Rich media support with photo management
- Detailed statistics and specifications

### User Interaction
- User reviews and ratings
- Photo uploads and sharing
- Content moderation system
- Social features (likes, reports)

### Analytics and Trending
- Page view tracking
- Trending content identification
- Usage statistics and metrics

### Location Features
- Geographic coordinates
- Address management
- Park area organization

## Technical Implementation

### Database Design
- PostgreSQL database
- Generic relations for flexible content relationships
- Comprehensive indexing for performance
- Historical record tracking

### Authentication
- Django allauth integration
- Multiple social auth providers
- Custom user model and authentication flow

### Media Handling
- Custom storage backend
- Organized file structure
- Automatic file naming and organization

### Performance Features
- Caching configuration
- Database query optimization
- Efficient media handling

### Security Features
- CSRF protection
- Secure authentication
- Content moderation
- User input validation

## Management Commands

### Analytics
- `update_trending.py`: Updates trending content calculations

### Parks
- `update_park_counts.py`: Updates park statistics and ride counts

## Frontend Integration

### Templates
- Organized template structure
- Partial templates for reusability
- Photo gallery integration

### Static Files
- CSS with Tailwind integration
- JavaScript for interactive features
- Photo gallery functionality

## Development Guidelines

### Code Organization
- Modular app structure
- Clear separation of concerns
- Consistent naming conventions

### Best Practices
- Generic relations for flexibility
- Historical tracking for all major models
- Comprehensive validation
- Efficient query patterns

### Security Considerations
- Secure content storage
- User permission management
- Input validation and sanitization
- Protected user data

## Deployment Considerations

### Environment Configuration
- Environment-specific settings
- Secure key management
- Database configuration

### Media Storage
- Organized upload structure
- Efficient file handling
- Backup considerations

### Performance Optimization
- Caching strategy
- Database indexing
- Query optimization

## Future Considerations

### Scalability
- Database optimization opportunities
- Caching improvements
- Media handling optimization

### Feature Expansion
- Additional social features
- Enhanced analytics
- Mobile app integration possibilities

### Integration Opportunities
- API development
- Third-party service integration
- Mobile app support