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

Install dependencies
```
cd frontend
pnpm install
```

Environment configuration

cp .env.development .env.local
# Edit .env.local with your settings

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

Available Scripts

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

# 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

# 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

Vue 3 Composition API with <script setup> syntax
TypeScript for all new components and utilities
Component naming following Vue.js conventions
CSS classes using Tailwind utility classes

Development Process

Create feature branch from main
Follow component structure guidelines
Add tests for new functionality
Update documentation as needed
Submit pull request with description

Component Creation

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

README.md

ThrillWiki Frontend

🏗️ Architecture Overview