pacnpal/thrillwiki_django_no_react
1
1
Fork 0
mirror of https://github.com/pacnpal/thrillwiki_django_no_react.git synced 2025-12-24 17:11:09 -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

458
docs/README.md
View File

@@ -1,344 +1,370 @@
# ThrillWiki Django + Vue.js Monorepo
# ThrillWiki - Django + HTMX Application
A comprehensive theme park and roller coaster information system built with a modern monorepo architecture combining Django REST API backend with Vue.js frontend.
A comprehensive theme park and roller coaster information system built with Django and HTMX, providing a progressive enhancement approach to modern web development.
## 🏗️ Architecture Overview
## Architecture Overview
This project uses a monorepo structure that cleanly separates backend and frontend concerns while maintaining shared resources and documentation:
ThrillWiki is a **Django monolith with HTMX-driven interactivity**, not a traditional SPA. This architecture provides:
- **Server-side rendering** for SEO and initial page load performance
- **Progressive enhancement** with HTMX for dynamic updates without full page reloads
- **REST API** for programmatic access and potential mobile app integration
- **Alpine.js** for minimal client-side state (limited to form validation and UI toggles)
```
thrillwiki-monorepo/
├── backend/ # Django REST API (Port 8000)
thrillwiki/
├── backend/ # Django application (main codebase)
│ ├── apps/ # Modular Django applications
│ │ ├── accounts/ # User management and authentication
│ │ ├── api/v1/ # REST API endpoints
│ │ ├── core/ # Shared utilities and base classes
│ │ ├── location/ # Geographic data and services
│ │ ├── media/ # File management (Cloudflare Images)
│ │ ├── moderation/ # Content moderation workflows
│ │ ├── parks/ # Theme park data and operations
│ │ └── rides/ # Ride information and relationships
│ ├── config/ # Django settings and configuration
│ ├── templates/ # Django templates
│ └── static/ # Static assets
├── frontend/ # Vue.js SPA (Port 5174)
│ ├── src/ # Vue.js source code
│ ├── public/ # Static assets
│ └── dist/ # Build output
├── shared/ # Shared resources and documentation
│ ├── docs/ # Comprehensive documentation
│ │ ├── django/ # Environment-specific settings
│ │ └── settings/ # Modular settings modules
│ ├── templates/ # Django templates with HTMX
│ │ ├── components/ # Reusable UI components
│ │ ├── htmx/ # HTMX partial templates
│ │ └── layouts/ # Base layout templates
│ └── static/ # Static assets (CSS, JS, images)
├── shared/ # Shared resources
│ ├── scripts/ # Development and deployment scripts
│ ├── config/ # Shared configuration
│ └── media/ # Shared media files
├── architecture/ # Architecture documentation
└── profiles/ # Development profiles
├── docs/ # Project documentation
└── tests/ # Test files
```
## 🚀 Quick Start
## Technology Stack
| Technology | Version | Purpose |
|------------|---------|---------|
| **Django** | 5.2.8+ | Web framework |
| **Django REST Framework** | 3.15.2+ | API framework |
| **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
### Prerequisites
- **Python 3.11+** with [uv](https://docs.astral.sh/uv/) for backend dependencies
- **Node.js 18+** with [pnpm](https://pnpm.io/) for frontend dependencies
- **PostgreSQL 14+** (optional, defaults to SQLite for development)
- **Redis 6+** (optional, for caching and sessions)
- **Python 3.13+** with [uv](https://docs.astral.sh/uv/) for package management
- **PostgreSQL 14+** with PostGIS extension
- **Redis 6+** for caching and sessions
### Development Setup
1. **Clone the repository**
```bash
git clone <repository-url>
cd thrillwiki-monorepo
cd thrillwiki
```
2. **Install dependencies**
```bash
# Install frontend dependencies
pnpm install
# Install backend dependencies
cd backend && uv sync && cd ..
cd backend
uv sync --frozen # Use locked versions for reproducibility
```
3. **Environment configuration**
```bash
# Copy environment files
cp .env.example .env
cp backend/.env.example backend/.env
cp frontend/.env.development frontend/.env.local
# Edit .env files with your settings
# Edit .env with your settings
```
4. **Database setup**
```bash
cd backend
uv run manage.py migrate
uv run manage.py createsuperuser
cd ..
```
5. **Start development servers**
5. **Start development server**
```bash
# Start both servers concurrently
pnpm run dev
# Or start individually
pnpm run dev:frontend # Vue.js on :5174
pnpm run dev:backend # Django on :8000
uv run manage.py runserver
```
## 📁 Project Structure Details
The application will be available at `http://localhost:8000`.
### Backend (`/backend`)
- **Django 5.0+** with REST Framework for API development
- **Modular app architecture** with separate apps for parks, rides, accounts, etc.
- **UV package management** for fast, reliable Python dependency management
- **PostgreSQL/SQLite** database with comprehensive entity relationships
- **Redis** for caching, sessions, and background tasks
- **Comprehensive API** with frontend serializers for camelCase conversion
## Project Structure Details
### Frontend (`/frontend`)
- **Vue 3** with Composition API and `<script setup>` syntax
- **TypeScript** for type safety and better developer experience
- **Vite** for lightning-fast development and optimized production builds
- **Tailwind CSS** with custom design system and dark mode support
- **Pinia** for state management with modular stores
- **Vue Router** for client-side routing
- **Comprehensive UI component library** with shadcn-vue components
### Django Applications
### Shared Resources (`/shared`)
- **Documentation** - Comprehensive guides and API documentation
- **Development scripts** - Automated setup, build, and deployment scripts
- **Configuration** - Shared Docker, CI/CD, and infrastructure configs
- **Media management** - Centralized media file handling and optimization
| App | Description |
|-----|-------------|
| **accounts** | User authentication, profiles, preferences, and social auth |
| **api/v1** | RESTful API endpoints with OpenAPI documentation |
| **core** | Shared utilities, managers, middleware, and services |
| **location** | Geographic models, geocoding, and map services |
| **media** | Cloudflare Images integration and file management |
| **moderation** | Content review workflows and moderation queue |
| **parks** | Theme park models, views, and related operations |
| **rides** | Ride models, coaster statistics, and ride history |
## 🛠️ Development Workflow
### HTMX Patterns
### Available Scripts
ThrillWiki uses HTMX for server-driven interactivity:
```bash
# Development
pnpm run dev # Start both servers concurrently
pnpm run dev:frontend # Frontend only (:5174)
pnpm run dev:backend # Backend only (:8000)
- **Partial templates** (`*_partial.html`) for dynamic content updates
- **HX-Trigger** for cross-component communication
- **hx-indicator** with skeleton loaders for loading states
- **Field-level validation** via HTMX for form feedback
# Building
pnpm run build # Build frontend for production
pnpm run build:staging # Build for staging environment
pnpm run build:production # Build for production environment
See [HTMX Patterns](./htmx-patterns.md) for detailed conventions.
# Testing
pnpm run test # Run all tests
pnpm run test:frontend # Frontend unit and E2E tests
pnpm run test:backend # Backend unit and integration tests
### Hybrid API/HTML Endpoints
# Code Quality
pnpm run lint # Lint all code
pnpm run type-check # TypeScript type checking
Many views serve dual purposes:
# Setup and Maintenance
pnpm run install:all # Install all dependencies
./shared/scripts/dev/setup-dev.sh # Full development setup
./shared/scripts/dev/start-all.sh # Start all services
```
- **HTML response** for browser requests (template rendering)
- **JSON response** for API requests (DRF serialization)
### Backend Development
This is achieved through content negotiation and hybrid view mixins.
## Development Workflow
### Running the Development Server
```bash
cd backend
uv run manage.py runserver
```
# Django management commands
### Django Management Commands
```bash
# Database operations
uv run manage.py migrate
uv run manage.py makemigrations
uv run manage.py createsuperuser
# Static files
uv run manage.py collectstatic
# Testing and quality
# Validate configuration
uv run manage.py validate_settings
# Testing
uv run manage.py test
uv run black . # Format code
uv run flake8 . # Lint code
uv run isort . # Sort imports
```
### Frontend Development
### Code Quality
```bash
cd frontend
# Format code
uv run black .
uv run isort .
# Vue.js development
pnpm run dev # Start dev server
pnpm run build # Production build
pnpm run preview # Preview production build
pnpm run test:unit # Vitest unit tests
pnpm run test:e2e # Playwright E2E tests
pnpm run lint # ESLint
pnpm run type-check # TypeScript checking
# Lint code
uv run ruff check .
uv run flake8 .
# Type checking
uv run pyright
```
## 🔧 Configuration
## Configuration
### Environment Variables
#### Root `.env`
```bash
# Database
DATABASE_URL=postgresql://user:pass@localhost/thrillwiki
REDIS_URL=redis://localhost:6379
ThrillWiki uses environment variables for configuration. Key variables:
# Security
SECRET_KEY=your-secret-key
DEBUG=True
| Variable | Description |
|----------|-------------|
| `SECRET_KEY` | Django secret key (required) |
| `DEBUG` | Debug mode (True/False) |
| `DATABASE_URL` | PostgreSQL connection URL |
| `REDIS_URL` | Redis connection URL |
| `DJANGO_SETTINGS_MODULE` | Settings module to use |
# API Configuration
API_BASE_URL=http://localhost:8000/api
See [Environment Variables](./configuration/environment-variables.md) for complete reference.
### Settings Architecture
ThrillWiki uses a modular settings architecture:
```
config/
├── django/ # Environment-specific settings
│ ├── base.py # Core settings
│ ├── local.py # Development overrides
│ ├── production.py # Production overrides
│ └── test.py # Test overrides
└── settings/ # Modular settings
├── cache.py # Redis caching
├── database.py # Database configuration
├── email.py # Email settings
├── logging.py # Logging configuration
├── rest_framework.py # DRF and CORS
├── security.py # Security headers
└── storage.py # Static/media files
```
#### Backend `.env`
```bash
# Django Settings
DJANGO_SETTINGS_MODULE=config.django.local
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1
## API Documentation
# Database
DATABASE_URL=postgresql://user:pass@localhost/thrillwiki
### Interactive Documentation
# Redis
REDIS_URL=redis://localhost:6379
- **Swagger UI**: `/api/docs/`
- **ReDoc**: `/api/redoc/`
- **OpenAPI Schema**: `/api/schema/`
# Email (optional)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USE_TLS=True
```
### API Overview
#### Frontend `.env.local`
```bash
# API Configuration
VITE_API_BASE_URL=http://localhost:8000/api
- **Base URL**: `/api/v1/`
- **Authentication**: JWT Bearer tokens or session-based
- **Content-Type**: `application/json`
# Development
VITE_APP_TITLE=ThrillWiki (Development)
See [API Documentation](./THRILLWIKI_API_DOCUMENTATION.md) for complete endpoint reference.
# Feature Flags
VITE_ENABLE_DEBUG=true
```
## Key Features
## 📊 Key Features
### Park Database
- Comprehensive theme park information worldwide
- Operator and property owner relationships
- Geographic data with PostGIS support
- Operating status and seasonal information
### Backend Features
- **Comprehensive Park Database** - Detailed information about theme parks worldwide
- **Extensive Ride Database** - Complete roller coaster and ride information
- **User Management** - Authentication, profiles, and permissions
- **Content Moderation** - Review and approval workflows
- **API Documentation** - Auto-generated OpenAPI/Swagger docs
- **Background Tasks** - Celery integration for long-running processes
- **Caching Strategy** - Redis-based caching for performance
- **Search Functionality** - Full-text search across all content
### Ride Database
- Complete ride specifications and statistics
- Roller coaster technical data (height, speed, inversions)
- Manufacturer and designer tracking
- Historical status and name changes
### Frontend Features
- **Responsive Design** - Mobile-first approach with Tailwind CSS
- **Dark Mode Support** - Complete dark/light theme system
- **Real-time Search** - Instant search with debouncing and highlighting
- **Interactive Maps** - Park and ride location visualization
- **Photo Galleries** - High-quality image management
- **User Dashboard** - Personalized content and contributions
- **Progressive Web App** - PWA capabilities for mobile experience
- **Accessibility** - WCAG 2.1 AA compliance
### User Features
- User authentication with social login (Google, Discord)
- Profile management and preferences
- Review and rating system
- Personalized content and contributions
## 📖 Documentation
### Content Moderation
- Review and approval workflows
- Moderation queue management
- User moderation actions
- Bulk operations support
### API Capabilities
- Full CRUD for all entities
- Advanced filtering and search
- Pagination and sorting
- Rate limiting and caching
## Documentation
### Core Documentation
- **[Backend Documentation](./backend/README.md)** - Django setup and API details
- **[Frontend Documentation](./frontend/README.md)** - Vue.js setup and development
- **[API Documentation](./shared/docs/api/README.md)** - Complete API reference
- **[Development Workflow](./shared/docs/development/workflow.md)** - Daily development processes
- [Backend Documentation](../backend/README.md) - Setup and development details
- [API Documentation](./THRILLWIKI_API_DOCUMENTATION.md) - Complete API reference
- [Setup Guide](./SETUP_GUIDE.md) - Comprehensive setup instructions
### Architecture & Deployment
- **[Architecture Overview](./architecture/)** - System design and decisions
- **[Deployment Guide](./shared/docs/deployment/)** - Production deployment instructions
- **[Development Scripts](./shared/scripts/)** - Automation and tooling
### Configuration
- [Environment Variables](./configuration/environment-variables.md) - Complete reference
- [Secret Management](./configuration/secret-management.md) - Secret handling
### Additional Resources
- **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute to the project
- **[Code of Conduct](./CODE_OF_CONDUCT.md)** - Community guidelines
- **[Security Policy](./SECURITY.md)** - Security reporting and policies
### Architecture
- [Architecture Decisions](./architecture/) - ADRs for key decisions
- [Deployment Guide](../architecture/deployment-guide.md) - Production deployment
- [Health Checks](./HEALTH_CHECKS.md) - Monitoring endpoints
## 🚀 Deployment
### Accessibility
- [Keyboard Navigation](./accessibility/keyboard-navigation.md) - Keyboard shortcuts
- [Screen Reader Testing](./accessibility/screen-reader-testing.md) - Testing checklist
- [Component Patterns](./accessibility/component-patterns.md) - Accessible patterns
## Testing
### Running Tests
```bash
# Run all tests
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
```
### Accessibility Testing
```bash
# Run accessibility tests
uv run manage.py test backend.tests.accessibility
```
## Deployment
### Development Environment
```bash
# Quick start with all services
./shared/scripts/dev/start-all.sh
# Start development server
uv run manage.py runserver
# Full development setup
./shared/scripts/dev/setup-dev.sh
```
### Production Deployment
```bash
# Build all components
./shared/scripts/build/build-all.sh
# Deploy to production
./shared/scripts/deploy/deploy.sh
```
See [Deployment Guide](../architecture/deployment-guide.md) for detailed production setup instructions.
See [Deployment Guide](./shared/docs/deployment/) for detailed production setup instructions.
Key production requirements:
- `DEBUG=False`
- SSL/HTTPS enforcement
- Redis for caching and sessions
- PostgreSQL with connection pooling
- Proper secret management
## 🧪 Testing Strategy
### Production Checklist
### Backend Testing
- **Unit Tests** - Individual function and method testing
- **Integration Tests** - API endpoint and database interaction testing
- **E2E Tests** - Full user journey testing with Selenium
See [Production Checklist](./PRODUCTION_CHECKLIST.md) for deployment verification.
### Frontend Testing
- **Unit Tests** - Component and utility function testing with Vitest
- **Integration Tests** - Component interaction testing
- **E2E Tests** - User journey testing with Playwright
## Contributing
### Code Quality
- **Linting** - ESLint for JavaScript/TypeScript, Flake8 for Python
- **Type Checking** - TypeScript for frontend, mypy for Python
- **Code Formatting** - Prettier for frontend, Black for Python
We welcome contributions! Please follow these guidelines:
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details on:
1. **Development Setup** - Getting your development environment ready
2. **Code Standards** - Coding conventions and best practices
3. **Pull Request Process** - How to submit your changes
4. **Issue Reporting** - How to report bugs and request features
1. **Development Setup** - Follow the setup instructions above
2. **Code Standards** - Follow Django coding standards and use provided linters
3. **Testing** - Write tests for new features
4. **Documentation** - Update documentation as needed
### Quick Contribution Start
```bash
# Fork and clone the repository
git clone https://github.com/your-username/thrillwiki-monorepo.git
cd thrillwiki-monorepo
git clone https://github.com/your-username/thrillwiki.git
cd thrillwiki
# Set up development environment
./shared/scripts/dev/setup-dev.sh
cd backend && uv sync
# Create a feature branch
git checkout -b feature/your-feature-name
# Make your changes and test
pnpm run test
uv run manage.py test
# Submit a pull request
```
## 📄 License
## License
This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
This project is licensed under the MIT License - see the [LICENSE](../LICENSE) file for details.
## 🙏 Acknowledgments
## Support
- **Theme Park Community** - For providing data and inspiration
- **Open Source Contributors** - For the amazing tools and libraries
- **Vue.js and Django Communities** - For excellent documentation and support
## 📞 Support
- **Issues** - [GitHub Issues](https://github.com/your-repo/thrillwiki-monorepo/issues)
- **Discussions** - [GitHub Discussions](https://github.com/your-repo/thrillwiki-monorepo/discussions)
- **Documentation** - [Project Wiki](https://github.com/your-repo/thrillwiki-monorepo/wiki)
- **Issues**: [GitHub Issues](https://github.com/your-repo/thrillwiki/issues)
- **Discussions**: [GitHub Discussions](https://github.com/your-repo/thrillwiki/discussions)
---
**Built with ❤️ for the theme park and roller coaster community**
**Built with Django + HTMX for the theme park and roller coaster community**