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**
   ```bash
   cd frontend
   pnpm install
   ```

2. **Environment configuration**
   ```bash
   cp .env.example .env
   # Edit .env with your settings
   ```

3. **Start development server**
   ```bash
   pnpm run dev
   ```

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

## 🔧 Configuration

### Environment Variables

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

# 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

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

### Tailwind CSS

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

### Theme System

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

## 🔌 API Integration

### Service Layer

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

### Error Handling

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

## 🧪 Testing

### Test Structure

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

### Running Tests

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

```bash
pnpm run dev
```

### Production Build

```bash
pnpm run build
```

### 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)
    }
  }
}
```

## 🚀 Deployment

See the [Deployment Guide](../shared/docs/deployment/) 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