thrillwiki_django_no_react/frontend/README.md

# ThrillWiki Frontend

Modern Vue.js 3 SPA frontend for the ThrillWiki theme park and roller coaster information system.

## 🏗️ Architecture Overview

This frontend is built with Vue 3 and follows modern development practices:

```
frontend/
├── src/
│   ├── 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

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

### 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 20+** (see `engines` in package.json)
- **pnpm** package manager
- **Backend API** running on `http://localhost:8000`

### Setup

1. **Install dependencies**
   ```bash
   cd frontend
   pnpm install
   ```

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

3. **Start development server**
   ```bash
   pnpm dev
   ```
   The application will be available at `http://localhost:5174`

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

# Application Settings
VITE_APP_TITLE=ThrillWiki (Development)
VITE_APP_VERSION=1.0.0

# Feature Flags
VITE_ENABLE_DEBUG=true
VITE_ENABLE_ANALYTICS=false

# Theme
VITE_DEFAULT_THEME=system
```

### Vite Configuration

The build system is configured in `vite.config.ts` with:

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

Custom design system configured in `tailwind.config.js`:

- **Custom color palette** with CSS variables
- **Dark mode support** with `class` strategy
- **Component classes** for consistent styling
- **Material Design** inspired design tokens

## 📁 Project Structure Details

### Components Architecture

#### UI Components (`src/components/ui/`)
Base component library following shadcn-vue patterns:

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

#### Layout Components (`src/components/layout/`)
Application layout and navigation:

- **Navbar** - Main navigation with responsive design
- **ThemeController** - Dark/light mode toggle
- **Footer** - Site footer with links

#### Specialized Components
- **State Layer** - Material Design ripple effects
- **Icon** - Lucide React icon wrapper
- **Button variants** - Different button styles

### Views Structure

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

### State Management

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

### API Integration

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

### Type Definitions

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

## 🎨 Design System

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

### Typography
- **Inter font family** for modern appearance
- **Responsive text scales** for all screen sizes
- **Consistent line heights** for readability

### Component Variants
- **Button variants** - Primary, secondary, outline, ghost
- **Card variants** - Default, elevated, outlined
- **Input variants** - Default, error, success

### Dark Mode
- **Automatic detection** of system preference
- **Manual toggle** in theme controller
- **Smooth transitions** between themes
- **CSS custom properties** for dynamic theming

## 🧪 Testing Strategy

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

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

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

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

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