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

feat: major API restructure and Vue.js frontend integration

Browse Source 
- 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
This commit is contained in:
pacnpal
2025-08-24 16:42:20 -04:00
parent 92f4104d7a
commit e62646bcf9
127 changed files with 27734 additions and 1867 deletions
Download Patch File Download Diff File Expand all files Collapse all files

566
frontend/README.md
View File

@@ -1,49 +1,73 @@
# ThrillWiki Frontend
Vue.js SPA frontend for the ThrillWiki monorepo.
Modern Vue.js 3 SPA frontend for the ThrillWiki theme park and roller coaster information system.
## 🏗️ Architecture
## 🏗️ Architecture Overview
Modern Vue 3 application with TypeScript and composition API:
This frontend is built with Vue 3 and follows modern development practices:
```
frontend/
├── src/
│ ├── components/ # Vue components
│ │ ├── common/ # Shared components
│ │ ├── parks/ # Park-specific components
│ │ ├── rides/ # Ride-specific components
│ │ └── moderation/ # Moderation components
│ ├── views/ # Page components
│ ├── router/ # Vue Router setup
│ ├── stores/ # Pinia state management
│ ├── composables/ # Vue 3 composables
│ ├── services/ # API services
│ ├── utils/ # Utility functions
│ ├── types/ # TypeScript types
│ └── assets/ # Static assets
├── public/ # Public assets
└── tests/ # Frontend tests
│ ├── components/ # Reusable UI components
│ │ ├── ui/ # Base UI components (shadcn-vue style)
│ │ ├── layout/ # Layout components (Navbar, ThemeController)
│ │ ├── button/ # Button variants
│ │ ├── icon/ # Icon components
│ │ └── state-layer/ # Material Design state layers
│ ├── views/ # Page components
│ │ ├── Home.vue # Landing page
│ │ ├── SearchResults.vue # Search results page
│ │ ├── parks/ # Park-related pages
│ │ └── rides/ # Ride-related pages
│ ├── stores/ # Pinia state management
│ ├── router/ # Vue Router configuration
│ ├── services/ # API services and utilities
│ ├── types/ # TypeScript type definitions
│ ├── App.vue # Root component
│ └── main.ts # Application entry point
├── public/ # Static assets
├── dist/ # Production build output
└── e2e/ # End-to-end tests
```
## 🛠️ Technology Stack
## 🚀 Technology Stack
- **Vue 3** - Frontend framework with Composition API
- **TypeScript** - Type safety and better developer experience
- **Vite** - Fast build tool and dev server
- **Vue Router** - Client-side routing
- **Pinia** - State management
- **Tailwind CSS** - Utility-first CSS framework
- **Headless UI** - Unstyled, accessible UI components
- **Heroicons** - Beautiful SVG icons
- **Axios** - HTTP client for API requests
### Core Framework
- **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
## 🚀 Quick Start
### UI & Styling
- **Tailwind CSS v4** with custom design system
- **shadcn-vue** inspired component library
- **Material Design** state layers and interactions
- **Dark mode support** with automatic theme detection
### State Management & Routing
- **Pinia** for predictable state management
- **Vue Router 4** for client-side routing
### Development & Testing
- **Vitest** for fast unit testing
- **Playwright** for end-to-end testing
- **ESLint** with Vue and TypeScript rules
- **Prettier** for code formatting
- **Vue DevTools** integration
### Build & Performance
- **Vite** with optimized build pipeline
- **Vue 3's reactivity system** for optimal performance
- **Tree-shaking** and code splitting
- **PWA capabilities** for mobile experience
## 🛠️ Development Workflow
### Prerequisites
- Node.js 18+
- pnpm 8+
- **Node.js 20+** (see `engines` in package.json)
- **pnpm** package manager
- **Backend API** running on `http://localhost:8000`
### Setup
@@ -55,292 +79,306 @@ frontend/
2. **Environment configuration**
```bash
cp .env.example .env
# Edit .env with your settings
cp .env.development .env.local
# Edit .env.local with your settings
```
3. **Start development server**
```bash
pnpm run dev
pnpm dev
```
The application will be available at `http://localhost:5174`
Frontend will be available at http://localhost:3000
### Available Scripts
```bash
# Development
pnpm dev # Start dev server with hot reload
pnpm preview # Preview production build locally
# Building
pnpm build # Build for production
pnpm build-only # Build without type checking
pnpm type-check # TypeScript type checking only
# Testing
pnpm test:unit # Run unit tests with Vitest
pnpm test:e2e # Run E2E tests with Playwright
# Code Quality
pnpm lint # Run ESLint with auto-fix
pnpm lint:eslint # ESLint only
pnpm lint:oxlint # Oxlint (fast linter) only
pnpm format # Format code with Prettier
# Component Development
pnpm add # Add new components with Liftkit
```
## 🔧 Configuration
### Environment Variables
Create `.env.local` for local development:
```bash
# API Configuration
VITE_API_BASE_URL=http://localhost:8000/api
# App Configuration
VITE_APP_TITLE=ThrillWiki
VITE_APP_DESCRIPTION=Your ultimate guide to theme parks
# Application Settings
VITE_APP_TITLE=ThrillWiki (Development)
VITE_APP_VERSION=1.0.0
# Feature Flags
VITE_ENABLE_PWA=true
VITE_ENABLE_DEBUG=true
VITE_ENABLE_ANALYTICS=false
# Theme
VITE_DEFAULT_THEME=system
```
### Build Configuration
### Vite Configuration
- **Vite** configuration in `vite.config.ts`
- **TypeScript** configuration in `tsconfig.json`
- **Tailwind CSS** configuration in `tailwind.config.js`
The build system is configured in `vite.config.ts` with:
## 🧩 Components
### Component Structure
```typescript
// Example component structure
<template>
<div class="component-wrapper">
<!-- Template content -->
</div>
</template>
<script setup lang="ts">
import { ref, computed } from 'vue'
import type { ComponentProps } from '@/types'
// Component logic
</script>
<style scoped>
/* Component-specific styles */
</style>
```
### Shared Components
- **AppHeader** - Navigation and user menu
- **AppSidebar** - Main navigation sidebar
- **LoadingSpinner** - Loading indicator
- **ErrorMessage** - Error display component
- **SearchBox** - Global search functionality
## 🗂️ State Management
Using **Pinia** for state management:
```typescript
// stores/auth.ts
export const useAuthStore = defineStore('auth', () => {
const user = ref<User | null>(null)
const isAuthenticated = computed(() => !!user.value)
const login = async (credentials: LoginData) => {
// Login logic
}
return { user, isAuthenticated, login }
})
```
### Available Stores
- **authStore** - User authentication
- **parksStore** - Park data and operations
- **ridesStore** - Ride information
- **uiStore** - UI state (modals, notifications)
- **themeStore** - Dark/light mode toggle
## 🛣️ Routing
Vue Router setup with:
- **Route guards** for authentication
- **Lazy loading** for code splitting
- **Meta fields** for page titles and permissions
```typescript
// router/index.ts
const routes = [
{
path: '/',
name: 'Home',
component: () => import('@/views/Home.vue')
},
{
path: '/parks',
name: 'Parks',
component: () => import('@/views/parks/ParksIndex.vue')
}
]
```
## 🎨 Styling
- **Vue 3** plugin with JSX support
- **Path aliases** for clean imports
- **CSS preprocessing** with PostCSS and Tailwind
- **Development server** with proxy to backend API
- **Build optimizations** for production
### Tailwind CSS
- **Dark mode** support with class strategy
- **Custom colors** for brand consistency
- **Responsive design** utilities
- **Component classes** for reusable styles
Custom design system configured in `tailwind.config.js`:
### Theme System
- **Custom color palette** with CSS variables
- **Dark mode support** with `class` strategy
- **Component classes** for consistent styling
- **Material Design** inspired design tokens
```typescript
// composables/useTheme.ts
export const useTheme = () => {
const isDark = ref(false)
const toggleTheme = () => {
isDark.value = !isDark.value
document.documentElement.classList.toggle('dark')
}
return { isDark, toggleTheme }
}
```
## 📁 Project Structure Details
## 🔌 API Integration
### Components Architecture
### Service Layer
#### UI Components (`src/components/ui/`)
Base component library following shadcn-vue patterns:
```typescript
// services/api.ts
class ApiService {
private client = axios.create({
baseURL: import.meta.env.VITE_API_BASE_URL,
withCredentials: true,
})
// API methods
getParks(params?: ParkFilters) {
return this.client.get('/parks/', { params })
}
}
```
- **Button** - Multiple variants and sizes
- **Card** - Flexible content containers
- **Badge** - Status indicators and labels
- **SearchInput** - Search functionality with debouncing
- **Input, Textarea, Select** - Form components
- **Dialog, Sheet, Dropdown** - Overlay components
### Error Handling
#### Layout Components (`src/components/layout/`)
Application layout and navigation:
- Global error interceptors
- User-friendly error messages
- Retry mechanisms for failed requests
- Offline support indicators
- **Navbar** - Main navigation with responsive design
- **ThemeController** - Dark/light mode toggle
- **Footer** - Site footer with links
## 🧪 Testing
#### Specialized Components
- **State Layer** - Material Design ripple effects
- **Icon** - Lucide React icon wrapper
- **Button variants** - Different button styles
### Test Structure
### Views Structure
```bash
tests/
├── unit/ # Unit tests
├── e2e/ # End-to-end tests
└── __mocks__/ # Mock files
```
#### Page Components (`src/views/`)
- **Home.vue** - Landing page with featured content
- **SearchResults.vue** - Global search results display
- **parks/ParkList.vue** - List of all parks
- **parks/ParkDetail.vue** - Individual park information
- **rides/RideList.vue** - List of rides with filtering
- **rides/RideDetail.vue** - Detailed ride information
### Running Tests
### State Management
```bash
# Unit tests
pnpm run test
#### Pinia Stores (`src/stores/`)
- **Theme Store** - Dark/light mode state
- **Search Store** - Search functionality and results
- **Park Store** - Park data management
- **Ride Store** - Ride data management
- **UI Store** - General UI state
# E2E tests
pnpm run test:e2e
### API Integration
# Watch mode
pnpm run test:watch
```
#### Services (`src/services/`)
- **API client** with Axios configuration
- **Authentication** service
- **Park service** - CRUD operations for parks
- **Ride service** - CRUD operations for rides
- **Search service** - Global search functionality
### Testing Tools
### Type Definitions
- **Vitest** - Unit testing framework
- **Vue Test Utils** - Vue component testing
- **Playwright** - End-to-end testing
#### TypeScript Types (`src/types/`)
- **API response types** matching backend serializers
- **Component prop types** for better type safety
- **Store state types** for Pinia stores
- **Utility types** for common patterns
## 📱 Progressive Web App
## 🎨 Design System
PWA features:
### Color Palette
- **Primary colors** - Brand identity
- **Semantic colors** - Success, warning, error states
- **Neutral colors** - Grays for text and backgrounds
- **Dark mode variants** - Automatic color adjustments
- **Service Worker** for offline functionality
- **App Manifest** for installation
- **Push Notifications** for updates
- **Background Sync** for data synchronization
### Typography
- **Inter font family** for modern appearance
- **Responsive text scales** for all screen sizes
- **Consistent line heights** for readability
## 🔧 Build & Deployment
### Component Variants
- **Button variants** - Primary, secondary, outline, ghost
- **Card variants** - Default, elevated, outlined
- **Input variants** - Default, error, success
### Development Build
### Dark Mode
- **Automatic detection** of system preference
- **Manual toggle** in theme controller
- **Smooth transitions** between themes
- **CSS custom properties** for dynamic theming
```bash
pnpm run dev
```
## 🧪 Testing Strategy
### Production Build
### Unit Tests (Vitest)
- **Component testing** with Vue Test Utils
- **Composable testing** for custom hooks
- **Service testing** for API calls
- **Store testing** for Pinia state management
```bash
pnpm run build
```
### End-to-End Tests (Playwright)
- **User journey testing** - Complete user flows
- **Cross-browser testing** - Chrome, Firefox, Safari
- **Mobile testing** - Responsive behavior
- **Accessibility testing** - WCAG compliance
### Preview Production Build
```bash
pnpm run preview
```
### Build Output
- Static assets in `dist/`
- Optimized and minified code
- Source maps for debugging
- Chunk splitting for performance
## 🎯 Performance
### Optimization Strategies
- **Code splitting** with dynamic imports
- **Image optimization** with responsive loading
- **Bundle analysis** with rollup-plugin-visualizer
- **Lazy loading** for routes and components
### Core Web Vitals
- First Contentful Paint (FCP)
- Largest Contentful Paint (LCP)
- Cumulative Layout Shift (CLS)
## ♿ Accessibility
- **ARIA labels** and roles
- **Keyboard navigation** support
- **Screen reader** compatibility
- **Color contrast** compliance
- **Focus management**
## 🐛 Debugging
### Development Tools
- Vue DevTools browser extension
- Vite's built-in debugging features
- TypeScript error reporting
- Hot module replacement (HMR)
### Logging
```typescript
// utils/logger.ts
export const logger = {
info: (message: string, data?: any) => {
if (import.meta.env.DEV) {
console.log(message, data)
}
}
}
```
### Test Configuration
- **Vitest config** in `vitest.config.ts`
- **Playwright config** in `playwright.config.ts`
- **Test utilities** in `src/__tests__/`
- **Mock data** for consistent testing
## 🚀 Deployment
See the [Deployment Guide](../shared/docs/deployment/) for production setup.
### Build Process
```bash
# Production build
pnpm build
# Preview build locally
pnpm preview
# Type checking before build
pnpm type-check
```
### Build Output
- **Optimized bundles** with code splitting
- **Asset optimization** (images, fonts, CSS)
- **Source maps** for debugging (development only)
- **Service worker** for PWA features
### Environment Configurations
- **Development** - `.env.development`
- **Staging** - `.env.staging`
- **Production** - `.env.production`
## 🔧 Development Tools
### IDE Setup
- **VSCode** with Volar extension
- **Vue Language Features** for better Vue support
- **TypeScript Importer** for auto-imports
- **Tailwind CSS IntelliSense** for styling
### Browser Extensions
- **Vue DevTools** for debugging
- **Tailwind CSS DevTools** for styling
- **Playwright Inspector** for E2E testing
### Performance Monitoring
- **Vite's built-in analyzer** for bundle analysis
- **Vue DevTools performance tab**
- **Lighthouse** for performance metrics
## 📖 API Integration
### Backend Communication
- **RESTful API** integration with Django backend
- **Automatic field conversion** (snake_case ↔ camelCase)
- **Error handling** with user-friendly messages
- **Loading states** for better UX
### Authentication Flow
- **JWT token management**
- **Automatic token refresh**
- **Protected routes** with guards
- **User session management**
## 🤝 Contributing
1. Follow Vue.js style guide
2. Use TypeScript for type safety
3. Write tests for components
4. Follow Prettier formatting
5. Use conventional commits
### Code Standards
1. **Vue 3 Composition API** with `<script setup>` syntax
2. **TypeScript** for all new components and utilities
3. **Component naming** following Vue.js conventions
4. **CSS classes** using Tailwind utility classes
### Development Process
1. **Create feature branch** from `main`
2. **Follow component structure** guidelines
3. **Add tests** for new functionality
4. **Update documentation** as needed
5. **Submit pull request** with description
### Component Creation
```bash
# Add new component with Liftkit
pnpm add
# Follow the prompts to create component structure
```
## 🐛 Troubleshooting
### Common Issues
#### Build Errors
- **TypeScript errors** - Run `pnpm type-check` to identify issues
- **Missing dependencies** - Run `pnpm install` to sync packages
- **Vite configuration** - Check `vite.config.ts` for build settings
#### Runtime Errors
- **API connection** - Verify backend is running on port 8000
- **Environment variables** - Check `.env.local` configuration
- **CORS issues** - Configure backend CORS settings
#### Development Issues
- **Hot reload not working** - Restart dev server
- **Type errors** - Check TypeScript configuration
- **Styling issues** - Verify Tailwind classes
### Performance Tips
- **Use Composition API** for better performance
- **Lazy load components** for better initial load
- **Optimize images** and assets
- **Use `computed` properties** for derived state
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](../LICENSE) file for details.
## 🙏 Acknowledgments
- **Vue.js Team** for the excellent framework
- **Vite Team** for the blazing fast build tool
- **Tailwind CSS** for the utility-first approach
- **shadcn-vue** for component inspiration
- **ThrillWiki Community** for feedback and support
---
**Built with ❤️ for the theme park and roller coaster community**