thrillwiki_django_no_react/frontend/README.md

ThrillWiki Frontend

Vue.js SPA frontend for the ThrillWiki monorepo.

🏗️ Architecture

Modern Vue 3 application with TypeScript and composition API:

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

🛠️ 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

🚀 Quick Start

Prerequisites

• Node.js 18+
• pnpm 8+

Setup

1. Install dependencies

   cd frontend
   pnpm install
   

2. Environment configuration

   cp .env.example .env
   # Edit .env with your settings
   

3. Start development server

   pnpm run dev
   

   Frontend will be available at http://localhost:3000

🔧 Configuration

Environment Variables

# 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

# Feature Flags
VITE_ENABLE_PWA=true
VITE_ENABLE_ANALYTICS=false

Build Configuration

• Vite configuration in vite.config.ts
• TypeScript configuration in tsconfig.json
• Tailwind CSS configuration in tailwind.config.js

🧩 Components

Component Structure

// 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:

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

// router/index.ts
const routes = [
  {
    path: '/',
    name: 'Home',
    component: () => import('@/views/Home.vue')
  },
  {
    path: '/parks',
    name: 'Parks',
    component: () => import('@/views/parks/ParksIndex.vue')
  }
]

🎨 Styling

Tailwind CSS

• Dark mode support with class strategy
• Custom colors for brand consistency
• Responsive design utilities
• Component classes for reusable styles

Theme System

// composables/useTheme.ts
export const useTheme = () => {
  const isDark = ref(false)
  
  const toggleTheme = () => {
    isDark.value = !isDark.value
    document.documentElement.classList.toggle('dark')
  }
  
  return { isDark, toggleTheme }
}

🔌 API Integration

Service Layer

// 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 })
  }
}

Error Handling

• Global error interceptors
• User-friendly error messages
• Retry mechanisms for failed requests
• Offline support indicators

🧪 Testing

Test Structure

tests/
├── unit/           # Unit tests
├── e2e/            # End-to-end tests
└── __mocks__/      # Mock files

Running Tests

# Unit tests
pnpm run test

# E2E tests
pnpm run test:e2e

# Watch mode
pnpm run test:watch

Testing Tools

• Vitest - Unit testing framework
• Vue Test Utils - Vue component testing
• Playwright - End-to-end testing

📱 Progressive Web App

PWA features:

• Service Worker for offline functionality
• App Manifest for installation
• Push Notifications for updates
• Background Sync for data synchronization

🔧 Build & Deployment

Development Build

pnpm run dev

Production Build

pnpm run build

Preview Production Build

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

// utils/logger.ts
export const logger = {
  info: (message: string, data?: any) => {
    if (import.meta.env.DEV) {
      console.log(message, data)
    }
  }
}

🚀 Deployment

See the Deployment Guide for production setup.

🤝 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