thrillwiki_django_no_react/README.md

ThrillWiki Django + Vue.js Monorepo

A comprehensive theme park and roller coaster information system built with a modern monorepo architecture combining Django REST API backend with Vue.js frontend.

🏗️ Architecture Overview

This project uses a monorepo structure that cleanly separates backend and frontend concerns while maintaining shared resources and documentation:

thrillwiki-monorepo/
├── backend/                 # Django REST API (Port 8000)
│   ├── apps/               # Modular Django applications
│   ├── 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
│   ├── scripts/            # Development and deployment scripts
│   ├── config/             # Shared configuration
│   └── media/              # Shared media files
├── architecture/            # Architecture documentation
└── profiles/                # Development profiles

🚀 Quick Start

Prerequisites

• Python 3.11+ with uv for backend dependencies
• Node.js 18+ with pnpm for frontend dependencies
• PostgreSQL 14+ (optional, defaults to SQLite for development)
• Redis 6+ (optional, for caching and sessions)

Development Setup

1. Clone the repository

   git clone <repository-url>
   cd thrillwiki-monorepo
   

2. Install dependencies

   # Install frontend dependencies
   pnpm install
   
   # Install backend dependencies
   cd backend && uv sync && cd ..
   

3. Environment configuration

   # 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
   

4. Database setup

   cd backend
   uv run manage.py migrate
   uv run manage.py createsuperuser
   cd ..
   

5. Start development servers

   # 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
   

📁 Project Structure Details

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

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

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

🛠️ Development Workflow

Available Scripts

# Development
pnpm run dev              # Start both servers concurrently
pnpm run dev:frontend     # Frontend only (:5174)
pnpm run dev:backend      # Backend only (:8000)

# Building
pnpm run build            # Build frontend for production
pnpm run build:staging    # Build for staging environment
pnpm run build:production # Build for production environment

# 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

# Code Quality
pnpm run lint             # Lint all code
pnpm run type-check       # TypeScript type checking

# 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

Backend Development

cd backend

# Django management commands
uv run manage.py migrate
uv run manage.py makemigrations
uv run manage.py createsuperuser
uv run manage.py collectstatic

# Testing and quality
uv run manage.py test
uv run black .           # Format code
uv run flake8 .          # Lint code
uv run isort .           # Sort imports

Frontend Development

cd frontend

# 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

🔧 Configuration

Environment Variables

Root .env

# Database
DATABASE_URL=postgresql://user:pass@localhost/thrillwiki
REDIS_URL=redis://localhost:6379

# Security
SECRET_KEY=your-secret-key
DEBUG=True

# API Configuration
API_BASE_URL=http://localhost:8000/api

Backend .env

# Django Settings
DJANGO_SETTINGS_MODULE=config.django.local
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1

# Database
DATABASE_URL=postgresql://user:pass@localhost/thrillwiki

# Redis
REDIS_URL=redis://localhost:6379

# Email (optional)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USE_TLS=True

Frontend .env.local

# API Configuration
VITE_API_BASE_URL=http://localhost:8000/api

# Development
VITE_APP_TITLE=ThrillWiki (Development)

# Feature Flags
VITE_ENABLE_DEBUG=true

📊 Key Features

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

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

📖 Documentation

Core Documentation

• Backend Documentation - Django setup and API details
• Frontend Documentation - Vue.js setup and development
• API Documentation - Complete API reference
• Development Workflow - Daily development processes

Architecture & Deployment

• Architecture Overview - System design and decisions
• Deployment Guide - Production deployment instructions
• Development Scripts - Automation and tooling

Additional Resources

• Contributing Guide - How to contribute to the project
• Code of Conduct - Community guidelines
• Security Policy - Security reporting and policies

🚀 Deployment

Development Environment

# Quick start with all services
./shared/scripts/dev/start-all.sh

# Full development setup
./shared/scripts/dev/setup-dev.sh

Production Deployment

# Build all components
./shared/scripts/build/build-all.sh

# Deploy to production
./shared/scripts/deploy/deploy.sh

See Deployment Guide for detailed production setup instructions.

🧪 Testing Strategy

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

Frontend Testing

• Unit Tests - Component and utility function testing with Vitest
• Integration Tests - Component interaction testing
• E2E Tests - User journey testing with Playwright

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

🤝 Contributing

We welcome contributions! Please see our Contributing Guide 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

Quick Contribution Start

# Fork and clone the repository
git clone https://github.com/your-username/thrillwiki-monorepo.git
cd thrillwiki-monorepo

# Set up development environment
./shared/scripts/dev/setup-dev.sh

# Create a feature branch
git checkout -b feature/your-feature-name

# Make your changes and test
pnpm run test

# Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• 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
• Discussions - GitHub Discussions
• Documentation - Project Wiki

---

Built with ❤️ for the theme park and roller coaster community