mirror of
https://github.com/pacnpal/thrillwiki_django_no_react.git
synced 2025-12-20 17:31:09 -05:00
e62646bcf9
- Centralize API endpoints in dedicated api app with v1 versioning - Remove individual API modules from parks and rides apps - Add event tracking system with analytics functionality - Integrate Vue.js frontend with Tailwind CSS v4 and TypeScript - Add comprehensive database migrations for event tracking - Implement user authentication and social provider setup - Add API schema documentation and serializers - Configure development environment with shared scripts - Update project structure for monorepo with frontend/backend separation
345 lines
11 KiB
Markdown
345 lines
11 KiB
Markdown
# 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**
|