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**
   ```python
   # Key authentication flows
   User Authentication → JWT Token → Protected Resources
   Social Auth → Profile Creation → Platform Access
   ```

2. **Media Service**
   ```python
   # Media handling workflow
   Upload → Processing → Storage → Delivery
   ```

3. **Analytics Service**
   ```python
   # 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`](core/forms.py:1) provides authentication-first autocomplete foundation
- **Park Search**: [`ParkAutocomplete`](search/mixins.py:1) + [`ParkSearchForm`](search/forms.py:1) 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)