mirror of
https://github.com/pacnpal/thrillwiki_django_no_react.git
synced 2025-12-20 09:51:09 -05:00
feat: complete monorepo structure with frontend and shared resources
- Add complete backend/ directory with full Django application - Add frontend/ directory with Vite + TypeScript setup ready for Next.js - Add comprehensive shared/ directory with: - Complete documentation and memory-bank archives - Media files and avatars (letters, park/ride images) - Deployment scripts and automation tools - Shared types and utilities - Add architecture/ directory with migration guides - Configure pnpm workspace for monorepo development - Update .gitignore to exclude .django_tailwind_cli/ build artifacts - Preserve all historical documentation in shared/docs/memory-bank/ - Set up proper structure for full-stack development with shared resources
This commit is contained in:
pacnpal
346
frontend/README.md
Normal file
346
frontend/README.md
Normal file
@@ -0,0 +1,346 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user