pacnpal/thrillwiki_django_no_react
1
1
Fork 0
mirror of https://github.com/pacnpal/thrillwiki_django_no_react.git synced 2025-12-24 11:31:08 -05:00
Code Issues Packages Projects Releases Wiki Activity

Add secret management guide, client-side performance monitoring, and search accessibility enhancements

Browse Source 
- Introduced a comprehensive Secret Management Guide detailing best practices, secret classification, development setup, production management, rotation procedures, and emergency protocols.
- Implemented a client-side performance monitoring script to track various metrics including page load performance, paint metrics, layout shifts, and memory usage.
- Enhanced search accessibility with keyboard navigation support for search results, ensuring compliance with WCAG standards and improving user experience.
This commit is contained in:
pacnpal
2025-12-23 16:41:42 -05:00
parent ae31e889d7
commit edcd8f2076
155 changed files with 22046 additions and 4645 deletions
Download Patch File Download Diff File Expand all files Collapse all files

374
backend/README.md
View File

@@ -1,46 +1,70 @@
# ThrillWiki Backend
Django REST API backend for the ThrillWiki monorepo.
Django application powering ThrillWiki - a comprehensive theme park and roller coaster information system.
## 🏗️ Architecture
## Architecture
This backend follows Django best practices with a modular app structure:
ThrillWiki is a **Django monolith with HTMX-driven templates**, providing:
- **Server-side rendering** with Django templates
- **HTMX** for dynamic partial updates without full page reloads
- **REST API** for programmatic access (mobile apps, integrations)
- **Alpine.js** for minimal client-side state (form validation, UI toggles)
```
backend/
├── apps/ # Django applications
│ ├── accounts/ # User management
│ ├── parks/ # Theme park data
│ ├── rides/ # Ride information
│ ├── moderation/ # Content moderation
│ ├── location/ # Geographic data
│ ├── media/ # File management
│ ├── email_service/ # Email functionality
│ └── core/ # Core utilities
├── config/ # Django configuration
│ ├── django/ # Settings files
│ └── settings/ # Modular settings
├── templates/ # Django templates
├── static/ # Static files
└── tests/ # Test files
├── apps/ # Django applications
│ ├── accounts/ # User authentication and profiles
│ ├── api/v1/ # REST API endpoints
│ ├── core/ # Shared utilities, managers, services
│ ├── location/ # Geographic data and services
│ ├── media/ # Cloudflare Images integration
│ ├── moderation/ # Content moderation workflows
│ ├── parks/ # Theme park models and views
│ └── rides/ # Ride information and statistics
├── config/ # Django configuration
│ ├── django/ # Environment-specific settings
│ │ ├── base.py # Core settings
│ │ ├── local.py # Development overrides
│ │ ├── production.py # Production overrides
│ │ └── test.py # Test overrides
│ └── settings/ # Modular settings modules
│ ├── cache.py # Redis caching
│ ├── database.py # Database and GeoDjango
│ ├── email.py # Email configuration
│ ├── logging.py # Logging setup
│ ├── rest_framework.py # DRF, JWT, CORS
│ ├── security.py # Security headers
│ └── storage.py # Static/media files
├── templates/ # Django templates with HTMX
│ ├── components/ # Reusable UI components
│ ├── htmx/ # HTMX partial templates
│ └── layouts/ # Base layout templates
├── static/ # Static assets
└── tests/ # Test files
```
## 🛠️ Technology Stack
## Technology Stack
- **Django 5.0+** - Web framework
- **Django REST Framework** - API framework
- **PostgreSQL** - Primary database
- **Redis** - Caching and sessions
- **UV** - Python package management
- **Celery** - Background task processing
| Technology | Version | Purpose |
|------------|---------|---------|
| **Django** | 5.2.8+ | Web framework (security patched) |
| **Django REST Framework** | 3.15.2+ | API framework (security patched) |
| **HTMX** | 1.20.0+ | Dynamic UI updates |
| **Alpine.js** | 3.x | Minimal client-side state |
| **Tailwind CSS** | 3.x | Utility-first styling |
| **PostgreSQL/PostGIS** | 14+ | Database with geospatial support |
| **Redis** | 6+ | Caching and sessions |
| **Celery** | 5.5+ | Background task processing |
| **UV** | Latest | Python package management |
## 🚀 Quick Start
## Quick Start
### Prerequisites
- Python 3.11+
- Python 3.13+
- [uv](https://docs.astral.sh/uv/) package manager
- PostgreSQL 14+
- PostgreSQL 14+ with PostGIS extension
- Redis 6+
### Setup
@@ -48,7 +72,8 @@ backend/
1. **Install dependencies**
```bash
cd backend
uv sync
uv sync --frozen # Use locked versions for reproducibility
# Or: uv sync # Allow updates within version constraints
```
2. **Environment configuration**
@@ -68,75 +93,182 @@ backend/
uv run manage.py runserver
```
## 🔧 Configuration
The application will be available at `http://localhost:8000`.
## HTMX Patterns
ThrillWiki uses HTMX for server-driven interactivity. Key patterns:
### Partial Templates
Views render partial templates for HTMX requests:
```python
# In views.py
def park_list(request):
parks = Park.objects.optimized_for_list()
template = "parks/partials/park_list.html" if request.htmx else "parks/park_list.html"
return render(request, template, {"parks": parks})
```
### HX-Trigger Events
Cross-component communication via custom events:
```html
<!-- Trigger event after action -->
<button hx-post="/parks/1/favorite/"
hx-trigger="click"
hx-swap="none"
hx-headers='{"HX-Trigger-After-Settle": "parkFavorited"}'>
Favorite
</button>
<!-- Listen for event -->
<div hx-get="/parks/favorites/"
hx-trigger="parkFavorited from:body">
<!-- Updated on event -->
</div>
```
### Loading Indicators
Skeleton loaders for better UX:
```html
<div hx-get="/parks/" hx-trigger="load" hx-indicator="#loading">
<div id="loading" class="htmx-indicator">
{% include "components/skeleton_loader.html" %}
</div>
</div>
```
### Field-Level Validation
Real-time form validation:
```html
<input name="email"
hx-post="/validate/email/"
hx-trigger="blur changed delay:500ms"
hx-target="next .error-message">
<span class="error-message"></span>
```
See [HTMX Patterns](../docs/htmx-patterns.md) for complete documentation.
## Hybrid API/HTML Endpoints
Many views serve dual purposes through content negotiation:
```python
class ParkDetailView(HybridViewMixin, DetailView):
"""
Returns HTML for browser requests, JSON for API requests.
Browser: GET /parks/cedar-point/ -> HTML template
API: GET /api/v1/parks/cedar-point/ -> JSON response
"""
model = Park
template_name = "parks/park_detail.html"
serializer_class = ParkSerializer
```
This approach:
- Reduces code duplication
- Ensures API and web views stay in sync
- Supports both HTMX partials and JSON responses
## Configuration
### Settings Architecture
ThrillWiki uses modular settings for maintainability:
```
config/
├── django/ # Environment-specific settings
│ ├── base.py # Core settings (imports modular settings)
│ ├── local.py # Development overrides
│ ├── production.py # Production overrides
│ └── test.py # Test overrides
├── settings/ # Modular settings
│ ├── cache.py # Redis caching
│ ├── database.py # Database and GeoDjango
│ ├── email.py # Email configuration
│ ├── logging.py # Logging setup
│ ├── rest_framework.py # DRF, JWT, CORS
│ ├── secrets.py # Secret management
│ ├── security.py # Security headers
│ ├── storage.py # Static/media files
│ ├── third_party.py # Allauth, Celery, etc.
│ └── validation.py # Settings validation
└── celery.py # Celery configuration
```
Validate configuration with:
```bash
uv run manage.py validate_settings
```
### Environment Variables
Required environment variables:
Key environment variables:
```bash
# Database
DATABASE_URL=postgresql://user:pass@localhost/thrillwiki
| Variable | Description | Required |
|----------|-------------|----------|
| `SECRET_KEY` | Django secret key | Yes |
| `DEBUG` | Debug mode (True/False) | Yes |
| `DATABASE_URL` | PostgreSQL connection URL | Yes |
| `REDIS_URL` | Redis connection URL | Production |
| `DJANGO_SETTINGS_MODULE` | Settings module to use | Yes |
# Django
SECRET_KEY=your-secret-key
DEBUG=True
DJANGO_SETTINGS_MODULE=config.django.local
See [Environment Variables](../docs/configuration/environment-variables.md) for complete reference.
# Redis
REDIS_URL=redis://localhost:6379
# Email (optional)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USE_TLS=True
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-password
```
### Settings Structure
- `config/django/base.py` - Base settings
- `config/django/local.py` - Development settings
- `config/django/production.py` - Production settings
- `config/django/test.py` - Test settings
## 📁 Apps Overview
## Apps Overview
### Core Apps
- **accounts** - User authentication and profile management
- **parks** - Theme park models and operations
- **rides** - Ride information and relationships
- **core** - Shared utilities and base classes
| App | Description |
|-----|-------------|
| **accounts** | User authentication, profiles, social auth (Google, Discord) |
| **parks** | Theme park models, views, and operations |
| **rides** | Ride models, coaster statistics, ride history |
| **core** | Shared utilities, managers, services, middleware |
### Support Apps
- **moderation** - Content moderation workflows
- **location** - Geographic data and services
- **media** - File upload and management
- **email_service** - Email sending and templates
| App | Description |
|-----|-------------|
| **api/v1** | REST API endpoints with OpenAPI documentation |
| **moderation** | Content moderation workflows and queue |
| **location** | Geographic data, geocoding, map services |
| **media** | Cloudflare Images integration |
## 🔌 API Endpoints
## API Endpoints
Base URL: `http://localhost:8000/api/`
Base URL: `http://localhost:8000/api/v1/`
### Authentication
- `POST /auth/login/` - User login
- `POST /auth/logout/` - User logout
- `POST /auth/register/` - User registration
### Interactive Documentation
### Parks
- `GET /parks/` - List parks
- `GET /parks/{id}/` - Park details
- `POST /parks/` - Create park (admin)
- **Swagger UI**: `/api/docs/`
- **ReDoc**: `/api/redoc/`
- **OpenAPI Schema**: `/api/schema/`
### Rides
- `GET /rides/` - List rides
- `GET /rides/{id}/` - Ride details
- `GET /parks/{park_id}/rides/` - Rides by park
### Core Endpoints
## 🧪 Testing
| Endpoint | Description |
|----------|-------------|
| `/api/v1/auth/` | Authentication (login, signup, social auth) |
| `/api/v1/parks/` | Theme park CRUD and filtering |
| `/api/v1/rides/` | Ride CRUD and filtering |
| `/api/v1/accounts/` | User profile and settings |
| `/api/v1/maps/` | Map data and location services |
| `/api/v1/health/` | Health check endpoints |
See [API Documentation](../docs/THRILLWIKI_API_DOCUMENTATION.md) for complete reference.
## Testing
```bash
# Run all tests
@@ -144,34 +276,47 @@ uv run manage.py test
# Run specific app tests
uv run manage.py test apps.parks
uv run manage.py test apps.rides
# Run with coverage
uv run coverage run manage.py test
uv run coverage report
# Run accessibility tests
uv run manage.py test backend.tests.accessibility
```
## 🔧 Management Commands
Custom management commands:
## Management Commands
```bash
# Import park data
# Database operations
uv run manage.py migrate
uv run manage.py makemigrations
uv run manage.py createsuperuser
uv run manage.py showmigrations
# Static files
uv run manage.py collectstatic
# 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
# Generate test data
uv run manage.py generate_test_data
# Clean up expired sessions
uv run manage.py clearsessions
```
## 📊 Database
## Database
### Entity Relationships
- **Parks** have Operators (required) and PropertyOwners (optional)
- **Rides** belong to Parks and may have Manufacturers/Designers
- **Users** can create submissions and moderate content
- **Reviews** are linked to Parks or Rides with user attribution
### Migrations
@@ -186,44 +331,51 @@ uv run manage.py migrate
uv run manage.py showmigrations
```
## 🔐 Security
## Security
- CORS configured for frontend integration
- CSRF protection enabled
- JWT token authentication
- Rate limiting on API endpoints
- Input validation and sanitization
Security features implemented:
## 📈 Performance
- **CORS** configured for API access
- **CSRF** protection enabled
- **JWT** token authentication for API
- **Session** authentication for web
- **Rate limiting** on API endpoints
- **Input validation** and sanitization
- **Security headers** (HSTS, CSP, etc.)
- Database query optimization
- Redis caching for frequent queries
- Background task processing with Celery
- Database connection pooling
## Performance
## 🚀 Deployment
Performance optimizations:
See the [Deployment Guide](../shared/docs/deployment/) for production setup.
- **Database query optimization** with custom managers
- **Redis caching** for frequent queries
- **Background tasks** with Celery
- **Connection pooling** for database
- **HTMX partials** for minimal data transfer
## 🐛 Debugging
## Debugging
### Development Tools
- Django Debug Toolbar
- Django Extensions
- Silk profiler for performance analysis
- **Django Debug Toolbar** - Request/response inspection
- **Django Extensions** - Additional management commands
- **Silk profiler** - Performance analysis
### Logging
Logs are written to:
- Console (development)
- Files in `logs/` directory (production)
- External logging service (production)
- Sentry (production, if configured)
## 🤝 Contributing
## Contributing
1. Follow Django coding standards
2. Write tests for new features
3. Update documentation
4. Run linting: `uv run flake8 .`
5. Format code: `uv run black .`
4. Run linting: `uv run ruff check .`
5. Format code: `uv run black .`
---
See [Main Documentation](../docs/README.md) for complete project documentation.