# 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](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)

### Development Setup

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd thrillwiki-monorepo
   ```

2. **Install dependencies**
   ```bash
   # Install frontend dependencies
   pnpm install

   # Install backend dependencies
   cd backend && uv sync && cd ..
   ```

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
   ```

4. **Database setup**
   ```bash
   cd backend
   uv run manage.py migrate
   uv run manage.py createsuperuser
   cd ..
   ```

5. **Start development servers**
   ```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
   ```

## 📁 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

```bash
# 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

```bash
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

```bash
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`
```bash
# 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`
```bash
# 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`
```bash
# 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](./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

### Architecture & Deployment
- **[Architecture Overview](./architecture/)** - System design and decisions
- **[Deployment Guide](./shared/docs/deployment/)** - Production deployment instructions
- **[Development Scripts](./shared/scripts/)** - Automation and tooling

### 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

## 🚀 Deployment

### Development Environment
```bash
# Quick start with all services
./shared/scripts/dev/start-all.sh

# 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](./shared/docs/deployment/) 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](./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

### Quick Contribution Start
```bash
# 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](./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](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)

---

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