mirror of
https://github.com/pacnpal/thrillwiki_django_no_react.git
synced 2025-12-20 16:51:07 -05:00
Add comprehensive test scripts for various models and services
- Implement tests for RideLocation and CompanyHeadquarters models to verify functionality and data integrity. - Create a manual trigger test script for trending content calculation endpoint, including authentication and unauthorized access tests. - Develop a manufacturer sync test to ensure ride manufacturers are correctly associated with ride models. - Add tests for ParkLocation model, including coordinate setting and distance calculations between parks. - Implement a RoadTripService test suite covering geocoding, route calculation, park discovery, and error handling. - Create a unified map service test script to validate map functionality, API endpoints, and performance metrics.
This commit is contained in:
pacnpal
600
docs/nuxt/planning/architecture-decisions.md
Normal file
600
docs/nuxt/planning/architecture-decisions.md
Normal file
@@ -0,0 +1,600 @@
|
||||
# 🏗️ ThrillWiki Nuxt Frontend - Architecture Decisions
|
||||
|
||||
**Status:** ✅ COMPLETE
|
||||
**Last Updated:** 2025-01-27 19:58 UTC
|
||||
**Dependencies:** requirements.md
|
||||
**Blocks:** All implementation phases
|
||||
|
||||
## 🎯 Architecture Overview
|
||||
|
||||
### System Architecture
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ ThrillWiki System │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Frontend (Nuxt 3) │ Backend (Django) │
|
||||
│ ┌─────────────────────┐ │ ┌─────────────────────┐ │
|
||||
│ │ Pages & Components │ │ │ REST API (/api/v1/) │ │
|
||||
│ │ ├─ Parks │ │ │ ├─ Authentication │ │
|
||||
│ │ ├─ Rides │ │ │ ├─ Parks CRUD │ │
|
||||
│ │ ├─ Auth │ │ │ ├─ Rides CRUD │ │
|
||||
│ │ └─ Admin │ │ │ ├─ Photos │ │
|
||||
│ └─────────────────────┘ │ │ └─ Moderation │ │
|
||||
│ ┌─────────────────────┐ │ └─────────────────────┘ │
|
||||
│ │ Composables │ │ ┌─────────────────────┐ │
|
||||
│ │ ├─ useAuth │◄───┼──┤ JWT Authentication │ │
|
||||
│ │ ├─ useApi │◄───┼──┤ Token Management │ │
|
||||
│ │ ├─ useParks │◄───┼──┤ CORS Configuration │ │
|
||||
│ │ └─ useRides │ │ └─────────────────────┘ │
|
||||
│ └─────────────────────┘ │ │
|
||||
│ ┌─────────────────────┐ │ ┌─────────────────────┐ │
|
||||
│ │ Component Library │ │ │ Database (PostgreSQL)│ │
|
||||
│ │ ├─ UI Components │ │ │ ├─ Parks │ │
|
||||
│ │ ├─ Forms │ │ │ ├─ Rides │ │
|
||||
│ │ ├─ Navigation │ │ │ ├─ Users │ │
|
||||
│ │ └─ Modals │ │ │ └─ Photos │ │
|
||||
│ └─────────────────────┘ │ └─────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Technology Stack Decisions
|
||||
|
||||
#### Frontend Framework: Nuxt 3
|
||||
**Decision:** Use Nuxt 3 with Vue 3 Composition API
|
||||
**Rationale:**
|
||||
- **Server-Side Rendering:** Better SEO and initial load performance
|
||||
- **File-based Routing:** Intuitive page organization
|
||||
- **Auto-imports:** Reduced boilerplate code
|
||||
- **Built-in Optimization:** Image optimization, code splitting, etc.
|
||||
- **TypeScript Support:** First-class TypeScript integration
|
||||
- **Ecosystem:** Rich ecosystem with modules and plugins
|
||||
|
||||
**Alternatives Considered:**
|
||||
- **Next.js:** Rejected due to React requirement
|
||||
- **SvelteKit:** Rejected due to smaller ecosystem
|
||||
- **Vite + Vue:** Rejected due to lack of SSR out-of-the-box
|
||||
|
||||
#### State Management: Pinia
|
||||
**Decision:** Use Pinia for global state management
|
||||
**Rationale:**
|
||||
- **Vue 3 Native:** Built specifically for Vue 3
|
||||
- **TypeScript Support:** Excellent TypeScript integration
|
||||
- **DevTools:** Great debugging experience
|
||||
- **Modular:** Easy to organize stores by feature
|
||||
- **Performance:** Optimized for Vue 3 reactivity
|
||||
|
||||
**Alternatives Considered:**
|
||||
- **Vuex:** Rejected due to Vue 3 compatibility issues
|
||||
- **Composables Only:** Rejected for complex state management needs
|
||||
|
||||
#### Component Library: TBD (User Choice Required)
|
||||
**Status:** ⏳ PENDING USER DECISION
|
||||
**Options Analyzed:**
|
||||
|
||||
##### Option 1: Nuxt UI (Recommended)
|
||||
```typescript
|
||||
// Installation
|
||||
npm install @nuxt/ui
|
||||
|
||||
// Configuration
|
||||
export default defineNuxtConfig({
|
||||
modules: ['@nuxt/ui'],
|
||||
ui: {
|
||||
global: true,
|
||||
icons: ['heroicons']
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
- Built specifically for Nuxt 3
|
||||
- Tailwind CSS integration
|
||||
- Headless UI foundation (accessibility)
|
||||
- TypeScript support
|
||||
- Modern design system
|
||||
- Tree-shakable
|
||||
|
||||
**Cons:**
|
||||
- Newer library (less mature)
|
||||
- Smaller component set
|
||||
- Limited complex components
|
||||
|
||||
##### Option 2: Vuetify
|
||||
```typescript
|
||||
// Installation
|
||||
npm install vuetify @mdi/font
|
||||
|
||||
// Configuration
|
||||
import { createVuetify } from 'vuetify'
|
||||
export default defineNuxtPlugin(() => {
|
||||
const vuetify = createVuetify({
|
||||
theme: { defaultTheme: 'light' }
|
||||
})
|
||||
return { provide: { vuetify } }
|
||||
})
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
- Mature, battle-tested
|
||||
- Comprehensive component set
|
||||
- Material Design system
|
||||
- Strong community
|
||||
- Good documentation
|
||||
|
||||
**Cons:**
|
||||
- Large bundle size
|
||||
- Material Design constraints
|
||||
- Vue 3 support still evolving
|
||||
- Less customizable
|
||||
|
||||
##### Option 3: PrimeVue
|
||||
```typescript
|
||||
// Installation
|
||||
npm install primevue primeicons
|
||||
|
||||
// Configuration
|
||||
import PrimeVue from 'primevue/config'
|
||||
export default defineNuxtPlugin((nuxtApp) => {
|
||||
nuxtApp.vueApp.use(PrimeVue)
|
||||
})
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
- Enterprise-focused
|
||||
- Comprehensive components
|
||||
- Good TypeScript support
|
||||
- Professional themes
|
||||
- Accessibility features
|
||||
|
||||
**Cons:**
|
||||
- Commercial themes cost
|
||||
- Learning curve
|
||||
- Less modern design
|
||||
- Larger bundle size
|
||||
|
||||
#### Authentication: JWT with Refresh Tokens
|
||||
**Decision:** Implement JWT authentication with refresh token mechanism
|
||||
**Rationale:**
|
||||
- **Stateless:** No server-side session storage required
|
||||
- **Scalable:** Works well with multiple frontend instances
|
||||
- **Secure:** Short-lived access tokens with refresh mechanism
|
||||
- **Standard:** Industry standard for API authentication
|
||||
|
||||
**Implementation Strategy:**
|
||||
```typescript
|
||||
// composables/useAuth.ts
|
||||
export const useAuth = () => {
|
||||
const accessToken = useCookie('access_token', {
|
||||
httpOnly: true,
|
||||
secure: true,
|
||||
sameSite: 'strict',
|
||||
maxAge: 15 * 60 // 15 minutes
|
||||
})
|
||||
|
||||
const refreshToken = useCookie('refresh_token', {
|
||||
httpOnly: true,
|
||||
secure: true,
|
||||
sameSite: 'strict',
|
||||
maxAge: 7 * 24 * 60 * 60 // 7 days
|
||||
})
|
||||
|
||||
const refreshAccessToken = async () => {
|
||||
// Auto-refresh logic
|
||||
}
|
||||
|
||||
return {
|
||||
login, logout, refreshAccessToken,
|
||||
isAuthenticated: computed(() => !!accessToken.value)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### API Integration: Custom Composables with $fetch
|
||||
**Decision:** Use Nuxt's built-in $fetch with custom composables
|
||||
**Rationale:**
|
||||
- **Built-in:** No additional HTTP client needed
|
||||
- **SSR Compatible:** Works seamlessly with server-side rendering
|
||||
- **Type Safe:** Full TypeScript support
|
||||
- **Caching:** Built-in request caching
|
||||
- **Error Handling:** Consistent error handling patterns
|
||||
|
||||
**Implementation Pattern:**
|
||||
```typescript
|
||||
// composables/useApi.ts
|
||||
export const useApi = () => {
|
||||
const { $fetch } = useNuxtApp()
|
||||
const { accessToken } = useAuth()
|
||||
|
||||
const apiCall = async (endpoint: string, options: any = {}) => {
|
||||
return await $fetch(`/api/v1${endpoint}`, {
|
||||
...options,
|
||||
headers: {
|
||||
'Authorization': `Bearer ${accessToken.value}`,
|
||||
...options.headers
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
return { apiCall }
|
||||
}
|
||||
```
|
||||
|
||||
### Project Structure Decisions
|
||||
|
||||
#### Directory Structure
|
||||
```
|
||||
frontend/
|
||||
├── assets/ # Static assets (images, fonts, etc.)
|
||||
├── components/ # Vue components
|
||||
│ ├── ui/ # UI library components
|
||||
│ ├── layout/ # Layout components
|
||||
│ ├── forms/ # Form components
|
||||
│ └── features/ # Feature-specific components
|
||||
│ ├── parks/ # Park-related components
|
||||
│ ├── rides/ # Ride-related components
|
||||
│ ├── auth/ # Authentication components
|
||||
│ └── admin/ # Admin/moderation components
|
||||
├── composables/ # Vue composables
|
||||
│ ├── useAuth.ts # Authentication logic
|
||||
│ ├── useApi.ts # API integration
|
||||
│ ├── useParks.ts # Parks data management
|
||||
│ ├── useRides.ts # Rides data management
|
||||
│ └── useModeration.ts # Moderation logic
|
||||
├── layouts/ # Nuxt layouts
|
||||
│ ├── default.vue # Default layout
|
||||
│ ├── auth.vue # Authentication layout
|
||||
│ └── admin.vue # Admin layout
|
||||
├── middleware/ # Route middleware
|
||||
│ ├── auth.ts # Authentication middleware
|
||||
│ └── admin.ts # Admin access middleware
|
||||
├── pages/ # File-based routing
|
||||
│ ├── index.vue # Homepage
|
||||
│ ├── parks/ # Parks pages
|
||||
│ ├── rides/ # Rides pages
|
||||
│ ├── auth/ # Authentication pages
|
||||
│ └── admin/ # Admin pages
|
||||
├── plugins/ # Nuxt plugins
|
||||
│ ├── api.client.ts # API configuration
|
||||
│ └── context7.client.ts # Context7 integration
|
||||
├── stores/ # Pinia stores
|
||||
│ ├── auth.ts # Authentication store
|
||||
│ ├── parks.ts # Parks store
|
||||
│ └── ui.ts # UI state store
|
||||
├── types/ # TypeScript type definitions
|
||||
│ ├── api.ts # API response types
|
||||
│ ├── auth.ts # Authentication types
|
||||
│ └── components.ts # Component prop types
|
||||
├── utils/ # Utility functions
|
||||
│ ├── validation.ts # Form validation
|
||||
│ ├── formatting.ts # Data formatting
|
||||
│ └── constants.ts # Application constants
|
||||
├── nuxt.config.ts # Nuxt configuration
|
||||
├── package.json # Dependencies
|
||||
└── tsconfig.json # TypeScript configuration
|
||||
```
|
||||
|
||||
### Development Environment Decisions
|
||||
|
||||
#### Package Manager: npm
|
||||
**Decision:** Use npm for package management
|
||||
**Rationale:**
|
||||
- **Consistency:** Matches existing project setup
|
||||
- **Reliability:** Stable and well-supported
|
||||
- **Lock File:** package-lock.json for reproducible builds
|
||||
- **CI/CD:** Easy integration with deployment pipelines
|
||||
|
||||
#### Development Server Configuration
|
||||
```typescript
|
||||
// nuxt.config.ts
|
||||
export default defineNuxtConfig({
|
||||
devtools: { enabled: true },
|
||||
|
||||
// Development server configuration
|
||||
devServer: {
|
||||
port: 3000,
|
||||
host: '0.0.0.0'
|
||||
},
|
||||
|
||||
// Proxy API calls to Django backend
|
||||
nitro: {
|
||||
devProxy: {
|
||||
'/api': {
|
||||
target: 'http://localhost:8000',
|
||||
changeOrigin: true
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// Runtime configuration
|
||||
runtimeConfig: {
|
||||
public: {
|
||||
apiBase: process.env.NUXT_PUBLIC_API_BASE || 'http://localhost:8000/api/v1'
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
#### Environment Variables
|
||||
```bash
|
||||
# .env
|
||||
NUXT_PUBLIC_API_BASE=http://localhost:8000/api/v1
|
||||
NUXT_SECRET_JWT_SECRET=your-jwt-secret
|
||||
NUXT_PUBLIC_APP_NAME=ThrillWiki
|
||||
NUXT_PUBLIC_APP_VERSION=1.0.0
|
||||
```
|
||||
|
||||
### Performance Optimization Decisions
|
||||
|
||||
#### Code Splitting Strategy
|
||||
**Decision:** Implement route-based and component-based code splitting
|
||||
**Implementation:**
|
||||
```typescript
|
||||
// Lazy load heavy components
|
||||
const PhotoGallery = defineAsyncComponent(() => import('~/components/PhotoGallery.vue'))
|
||||
|
||||
// Route-based splitting (automatic with Nuxt)
|
||||
// pages/admin/ - Admin bundle
|
||||
// pages/parks/ - Parks bundle
|
||||
// pages/rides/ - Rides bundle
|
||||
```
|
||||
|
||||
#### Image Optimization
|
||||
**Decision:** Use Nuxt Image module for automatic optimization
|
||||
**Configuration:**
|
||||
```typescript
|
||||
// nuxt.config.ts
|
||||
export default defineNuxtConfig({
|
||||
modules: ['@nuxt/image'],
|
||||
image: {
|
||||
provider: 'ipx',
|
||||
quality: 80,
|
||||
format: ['webp', 'avif', 'jpg'],
|
||||
screens: {
|
||||
xs: 320,
|
||||
sm: 640,
|
||||
md: 768,
|
||||
lg: 1024,
|
||||
xl: 1280
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
#### Caching Strategy
|
||||
**Decision:** Multi-layer caching approach
|
||||
**Layers:**
|
||||
1. **Browser Cache:** Static assets with long cache times
|
||||
2. **API Cache:** Response caching with TTL
|
||||
3. **Component Cache:** Expensive component computations
|
||||
4. **Route Cache:** Static route pre-generation
|
||||
|
||||
```typescript
|
||||
// API caching example
|
||||
export const useParks = () => {
|
||||
const { data: parks } = useLazyFetch('/api/v1/parks/', {
|
||||
key: 'parks-list',
|
||||
server: true,
|
||||
default: () => [],
|
||||
transform: (data: any) => data.results || data
|
||||
})
|
||||
|
||||
return { parks }
|
||||
}
|
||||
```
|
||||
|
||||
### Security Decisions
|
||||
|
||||
#### Token Storage
|
||||
**Decision:** Use HTTP-only cookies for token storage
|
||||
**Rationale:**
|
||||
- **XSS Protection:** Tokens not accessible via JavaScript
|
||||
- **CSRF Protection:** SameSite cookie attribute
|
||||
- **Automatic Handling:** Browser handles cookie management
|
||||
|
||||
#### Input Validation
|
||||
**Decision:** Client-side validation with server-side verification
|
||||
**Implementation:**
|
||||
```typescript
|
||||
// utils/validation.ts
|
||||
import { z } from 'zod'
|
||||
|
||||
export const parkSchema = z.object({
|
||||
name: z.string().min(1).max(100),
|
||||
location: z.string().min(1),
|
||||
operator: z.string().optional(),
|
||||
status: z.enum(['OPERATING', 'CLOSED', 'UNDER_CONSTRUCTION'])
|
||||
})
|
||||
|
||||
export type ParkInput = z.infer<typeof parkSchema>
|
||||
```
|
||||
|
||||
#### CORS Configuration
|
||||
**Decision:** Strict CORS policy for production
|
||||
**Django Configuration:**
|
||||
```python
|
||||
# backend/config/settings/production.py
|
||||
CORS_ALLOWED_ORIGINS = [
|
||||
"https://thrillwiki.com",
|
||||
"https://www.thrillwiki.com"
|
||||
]
|
||||
|
||||
CORS_ALLOW_CREDENTIALS = True
|
||||
CORS_ALLOW_ALL_ORIGINS = False # Never true in production
|
||||
```
|
||||
|
||||
### Testing Strategy Decisions
|
||||
|
||||
#### Testing Framework: Vitest
|
||||
**Decision:** Use Vitest for unit and component testing
|
||||
**Rationale:**
|
||||
- **Vite Integration:** Fast test execution
|
||||
- **Vue Support:** Excellent Vue component testing
|
||||
- **TypeScript:** Native TypeScript support
|
||||
- **Jest Compatible:** Familiar API for developers
|
||||
|
||||
#### E2E Testing: Playwright
|
||||
**Decision:** Use Playwright for end-to-end testing
|
||||
**Rationale:**
|
||||
- **Cross-browser:** Chrome, Firefox, Safari support
|
||||
- **Mobile Testing:** Mobile browser simulation
|
||||
- **Reliable:** Stable test execution
|
||||
- **Modern:** Built for modern web applications
|
||||
|
||||
#### Testing Configuration
|
||||
```typescript
|
||||
// vitest.config.ts
|
||||
import { defineConfig } from 'vitest/config'
|
||||
import vue from '@vitejs/plugin-vue'
|
||||
|
||||
export default defineConfig({
|
||||
plugins: [vue()],
|
||||
test: {
|
||||
environment: 'happy-dom',
|
||||
coverage: {
|
||||
reporter: ['text', 'json', 'html'],
|
||||
threshold: {
|
||||
global: {
|
||||
branches: 80,
|
||||
functions: 80,
|
||||
lines: 80,
|
||||
statements: 80
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### Deployment Decisions
|
||||
|
||||
#### Build Strategy
|
||||
**Decision:** Hybrid rendering with static generation for public pages
|
||||
**Configuration:**
|
||||
```typescript
|
||||
// nuxt.config.ts
|
||||
export default defineNuxtConfig({
|
||||
nitro: {
|
||||
prerender: {
|
||||
routes: [
|
||||
'/',
|
||||
'/parks',
|
||||
'/rides',
|
||||
'/about',
|
||||
'/privacy',
|
||||
'/terms'
|
||||
]
|
||||
}
|
||||
},
|
||||
|
||||
// Route rules for different rendering strategies
|
||||
routeRules: {
|
||||
'/': { prerender: true },
|
||||
'/parks': { prerender: true },
|
||||
'/rides': { prerender: true },
|
||||
'/admin/**': { ssr: false }, // SPA mode for admin
|
||||
'/auth/**': { ssr: false } // SPA mode for auth
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
#### Docker Configuration
|
||||
**Decision:** Multi-stage Docker build for production
|
||||
**Dockerfile:**
|
||||
```dockerfile
|
||||
# Build stage
|
||||
FROM node:18-alpine AS builder
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm ci --only=production
|
||||
COPY . .
|
||||
RUN npm run build
|
||||
|
||||
# Production stage
|
||||
FROM node:18-alpine AS production
|
||||
WORKDIR /app
|
||||
COPY --from=builder /app/.output ./
|
||||
EXPOSE 3000
|
||||
CMD ["node", "server/index.mjs"]
|
||||
```
|
||||
|
||||
### Context7 Integration Decisions
|
||||
|
||||
#### Documentation Strategy
|
||||
**Decision:** Integrate Context7 for automatic documentation generation
|
||||
**Implementation:**
|
||||
```typescript
|
||||
// plugins/context7.client.ts
|
||||
export default defineNuxtPlugin(() => {
|
||||
if (process.dev) {
|
||||
// Initialize Context7 connection
|
||||
const context7 = new Context7Client({
|
||||
endpoint: 'http://localhost:8080',
|
||||
project: 'thrillwiki-frontend'
|
||||
})
|
||||
|
||||
// Auto-document API calls
|
||||
context7.trackApiCalls()
|
||||
|
||||
// Document component usage
|
||||
context7.trackComponentUsage()
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
#### Knowledge Preservation
|
||||
**Decision:** Structured documentation with progress tracking
|
||||
**Features:**
|
||||
- Automatic API endpoint documentation
|
||||
- Component usage tracking
|
||||
- Implementation decision logging
|
||||
- Progress milestone tracking
|
||||
- LLM handoff preparation
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Implementation Priorities
|
||||
|
||||
### Phase 1: Foundation (Week 1)
|
||||
1. **Project Setup:** Initialize Nuxt 3 with TypeScript
|
||||
2. **Component Library:** Integrate chosen UI library
|
||||
3. **Authentication:** Implement JWT auth system
|
||||
4. **API Integration:** Set up Django backend communication
|
||||
5. **Basic Layout:** Create header, footer, navigation
|
||||
|
||||
### Phase 2: Core Features (Week 2)
|
||||
1. **Parks System:** Listing, detail, search functionality
|
||||
2. **Rides System:** Listing, detail, filtering
|
||||
3. **User Profiles:** Profile management and settings
|
||||
4. **Photo System:** Upload, display, basic moderation
|
||||
|
||||
### Phase 3: Advanced Features (Week 3)
|
||||
1. **Submission System:** Content submission workflow
|
||||
2. **Moderation Interface:** Admin tools and queues
|
||||
3. **Advanced Search:** Filters, autocomplete, suggestions
|
||||
4. **Maps Integration:** Location visualization
|
||||
|
||||
### Phase 4: Polish & Deployment (Week 4)
|
||||
1. **Performance Optimization:** Bundle size, loading times
|
||||
2. **Testing:** Comprehensive test suite
|
||||
3. **Documentation:** Complete user and developer docs
|
||||
4. **Deployment:** Production setup and monitoring
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Critical Dependencies
|
||||
|
||||
### Immediate Blockers
|
||||
1. **Component Library Choice:** Must be decided before implementation
|
||||
2. **Django JWT Setup:** Backend enhancement required
|
||||
3. **Development Environment:** CORS and proxy configuration
|
||||
|
||||
### Technical Dependencies
|
||||
1. **Node.js 18+:** Required for Nuxt 3
|
||||
2. **Django Backend:** Must be running for development
|
||||
3. **PostgreSQL:** Database must be accessible
|
||||
4. **Context7:** Integration approach needs clarification
|
||||
|
||||
---
|
||||
|
||||
**Next Document:** `component-library-analysis.md` - Detailed analysis of chosen library
|
||||
**Status:** Ready for component library decision and implementation start
|
||||
445
docs/nuxt/planning/requirements.md
Normal file
445
docs/nuxt/planning/requirements.md
Normal file
@@ -0,0 +1,445 @@
|
||||
# 📋 ThrillWiki Nuxt Frontend - Detailed Requirements
|
||||
|
||||
**Status:** ✅ COMPLETE
|
||||
**Last Updated:** 2025-01-27 19:55 UTC
|
||||
**Dependencies:** None
|
||||
**Blocks:** All implementation phases
|
||||
|
||||
## 🎯 Project Overview
|
||||
|
||||
### Primary Goal
|
||||
Create a modern, responsive Nuxt 3 frontend for ThrillWiki that seamlessly integrates with the existing Django REST API backend, providing users with an intuitive interface for discovering, submitting, and moderating theme park and ride content.
|
||||
|
||||
### Success Criteria
|
||||
1. **Functionality Parity:** All Django backend features accessible through frontend
|
||||
2. **Performance:** Sub-3s initial load, sub-1s navigation between pages
|
||||
3. **User Experience:** Intuitive, mobile-first design with smooth interactions
|
||||
4. **Maintainability:** Clean, documented, testable codebase
|
||||
5. **Scalability:** Architecture supports future feature additions
|
||||
|
||||
## 🏗️ Technical Requirements
|
||||
|
||||
### Framework & Architecture
|
||||
- **Frontend Framework:** Nuxt 3 with Vue 3 Composition API
|
||||
- **Language:** TypeScript for type safety and better developer experience
|
||||
- **State Management:** Pinia for global state management
|
||||
- **Component Library:** TBD - Existing reusable component library (user choice)
|
||||
- **Styling:** Tailwind CSS (or library's preferred styling system)
|
||||
- **Build Tool:** Vite (included with Nuxt 3)
|
||||
|
||||
### Authentication & Security
|
||||
- **Authentication Method:** JWT with refresh tokens
|
||||
- **Token Storage:** HTTP-only cookies for security
|
||||
- **Session Management:** Automatic token refresh
|
||||
- **Route Protection:** Middleware for protected routes
|
||||
- **CSRF Protection:** Integration with Django CSRF tokens
|
||||
- **Input Validation:** Client-side validation with server-side verification
|
||||
|
||||
### API Integration
|
||||
- **Backend API:** Django REST API at `/api/v1/`
|
||||
- **HTTP Client:** Nuxt's built-in $fetch with custom composables
|
||||
- **Error Handling:** Comprehensive error handling and user feedback
|
||||
- **Caching:** Smart caching strategy for API responses
|
||||
- **Real-time Updates:** WebSocket integration for live updates (future)
|
||||
|
||||
### Performance Requirements
|
||||
- **Initial Load:** < 3 seconds on 3G connection
|
||||
- **Navigation:** < 1 second between pages
|
||||
- **Bundle Size:** < 500KB initial JavaScript bundle
|
||||
- **Image Optimization:** Lazy loading and responsive images
|
||||
- **SEO:** Server-side rendering for public pages
|
||||
|
||||
## 🎨 User Interface Requirements
|
||||
|
||||
### Design System
|
||||
- **Design Philosophy:** Modern, clean, user-centric interface
|
||||
- **Responsive Design:** Mobile-first approach with breakpoints:
|
||||
- Mobile: 320px - 767px
|
||||
- Tablet: 768px - 1023px
|
||||
- Desktop: 1024px+
|
||||
- **Accessibility:** WCAG 2.1 AA compliance
|
||||
- **Theme Support:** Light/dark mode with system preference detection
|
||||
- **Typography:** Clear hierarchy with readable fonts
|
||||
- **Color Palette:** Modern, accessible color scheme
|
||||
|
||||
### Component Requirements
|
||||
- **Reusable Components:** Consistent design system components
|
||||
- **Form Components:** Validation, error handling, accessibility
|
||||
- **Navigation Components:** Header, sidebar, breadcrumbs, pagination
|
||||
- **Data Display:** Cards, tables, lists, galleries
|
||||
- **Interactive Components:** Modals, dropdowns, tooltips, tabs
|
||||
- **Feedback Components:** Alerts, notifications, loading states
|
||||
|
||||
## 🚀 Functional Requirements
|
||||
|
||||
### Core Features
|
||||
|
||||
#### 1. Authentication System
|
||||
**Priority:** High
|
||||
**Description:** Complete user authentication and account management
|
||||
|
||||
**Features:**
|
||||
- User registration with email verification
|
||||
- Login/logout with "remember me" option
|
||||
- Password reset via email
|
||||
- Profile management (avatar, bio, preferences)
|
||||
- Account settings and privacy controls
|
||||
- Social authentication (future enhancement)
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Users can register with email and password
|
||||
- [ ] Email verification required for new accounts
|
||||
- [ ] Secure login/logout with JWT tokens
|
||||
- [ ] Password reset functionality works
|
||||
- [ ] Profile information can be updated
|
||||
- [ ] Account deletion option available
|
||||
|
||||
#### 2. Parks Management
|
||||
**Priority:** High
|
||||
**Description:** Browse, search, and manage theme park information
|
||||
|
||||
**Features:**
|
||||
- Parks listing with search and filtering
|
||||
- Detailed park pages with photos and information
|
||||
- Park submission form for new parks
|
||||
- Photo upload and gallery management
|
||||
- Reviews and ratings system
|
||||
- Location-based search with maps
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Parks can be browsed with pagination
|
||||
- [ ] Search works by name, location, operator
|
||||
- [ ] Filtering by status, country, operator
|
||||
- [ ] Park detail pages show complete information
|
||||
- [ ] Users can submit new parks for approval
|
||||
- [ ] Photo upload works with moderation queue
|
||||
- [ ] Map integration shows park locations
|
||||
|
||||
#### 3. Rides Management
|
||||
**Priority:** High
|
||||
**Description:** Browse, search, and manage ride information
|
||||
|
||||
**Features:**
|
||||
- Rides listing with advanced filtering
|
||||
- Detailed ride pages with specifications
|
||||
- Ride submission form with validation
|
||||
- Photo galleries and media management
|
||||
- Manufacturer and model information
|
||||
- Ride rankings and statistics
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Rides can be browsed and filtered by category
|
||||
- [ ] Search works by name, park, manufacturer
|
||||
- [ ] Ride specifications displayed clearly
|
||||
- [ ] Users can submit new rides
|
||||
- [ ] Photo management with approval workflow
|
||||
- [ ] Rankings and statistics visible
|
||||
|
||||
#### 4. Content Submission System
|
||||
**Priority:** High
|
||||
**Description:** User-generated content with moderation workflow
|
||||
|
||||
**Features:**
|
||||
- Submission forms for parks, rides, photos
|
||||
- Draft saving and auto-save functionality
|
||||
- Submission status tracking
|
||||
- User submission history
|
||||
- Collaborative editing (future)
|
||||
- Bulk submission tools (admin)
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Users can submit parks and rides
|
||||
- [ ] Forms validate input and show errors
|
||||
- [ ] Drafts are saved automatically
|
||||
- [ ] Users can track submission status
|
||||
- [ ] Submission history is accessible
|
||||
- [ ] Admins can bulk approve/reject
|
||||
|
||||
#### 5. Moderation Interface
|
||||
**Priority:** High
|
||||
**Description:** Admin tools for content approval and management
|
||||
|
||||
**Features:**
|
||||
- Moderation queue with filtering
|
||||
- Bulk approval/rejection actions
|
||||
- Moderation notes and feedback
|
||||
- User reputation system
|
||||
- Content flagging and reporting
|
||||
- Moderation analytics dashboard
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Moderators can view pending submissions
|
||||
- [ ] Bulk actions work for multiple items
|
||||
- [ ] Moderation notes can be added
|
||||
- [ ] User reputation affects submission priority
|
||||
- [ ] Flagged content appears in queue
|
||||
- [ ] Analytics show moderation metrics
|
||||
|
||||
#### 6. Search & Discovery
|
||||
**Priority:** Medium
|
||||
**Description:** Advanced search and content discovery features
|
||||
|
||||
**Features:**
|
||||
- Global search across parks and rides
|
||||
- Autocomplete suggestions
|
||||
- Advanced filtering options
|
||||
- Trending content section
|
||||
- Recently added content
|
||||
- Personalized recommendations (future)
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Global search returns relevant results
|
||||
- [ ] Autocomplete works as user types
|
||||
- [ ] Filters can be combined effectively
|
||||
- [ ] Trending content updates regularly
|
||||
- [ ] New content is highlighted
|
||||
- [ ] Search performance is fast
|
||||
|
||||
#### 7. User Profiles & Social Features
|
||||
**Priority:** Medium
|
||||
**Description:** User profiles and social interaction features
|
||||
|
||||
**Features:**
|
||||
- Public user profiles
|
||||
- Top lists and favorites
|
||||
- User statistics and achievements
|
||||
- Following/followers system (future)
|
||||
- Activity feeds (future)
|
||||
- User-generated content showcase
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] User profiles are publicly viewable
|
||||
- [ ] Users can create and share top lists
|
||||
- [ ] Statistics show user activity
|
||||
- [ ] Achievements unlock based on activity
|
||||
- [ ] User content is showcased on profile
|
||||
- [ ] Privacy settings control visibility
|
||||
|
||||
### Advanced Features
|
||||
|
||||
#### 8. Photo Management
|
||||
**Priority:** Medium
|
||||
**Description:** Comprehensive photo upload and management system
|
||||
|
||||
**Features:**
|
||||
- Drag-and-drop photo upload
|
||||
- Image cropping and editing tools
|
||||
- Photo galleries with lightbox
|
||||
- Bulk photo operations
|
||||
- Photo metadata and tagging
|
||||
- Image optimization and CDN
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Photos can be uploaded via drag-and-drop
|
||||
- [ ] Basic editing tools available
|
||||
- [ ] Galleries display photos attractively
|
||||
- [ ] Bulk operations work efficiently
|
||||
- [ ] Photos are optimized automatically
|
||||
- [ ] CDN integration improves performance
|
||||
|
||||
#### 9. Maps Integration
|
||||
**Priority:** Medium
|
||||
**Description:** Interactive maps for park and ride locations
|
||||
|
||||
**Features:**
|
||||
- Interactive park location maps
|
||||
- Clustering for dense areas
|
||||
- Custom markers and popups
|
||||
- Directions integration
|
||||
- Mobile-friendly map controls
|
||||
- Offline map support (future)
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Maps show accurate park locations
|
||||
- [ ] Clustering works for nearby parks
|
||||
- [ ] Markers show park information
|
||||
- [ ] Directions can be requested
|
||||
- [ ] Maps work well on mobile
|
||||
- [ ] Performance is acceptable
|
||||
|
||||
#### 10. Rankings & Statistics
|
||||
**Priority:** Low
|
||||
**Description:** Display and interact with ride ranking system
|
||||
|
||||
**Features:**
|
||||
- Ride rankings display
|
||||
- Ranking history and trends
|
||||
- User voting interface (future)
|
||||
- Statistical analysis
|
||||
- Comparison tools
|
||||
- Export functionality
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Rankings display correctly
|
||||
- [ ] Historical data is accessible
|
||||
- [ ] Statistics are accurate
|
||||
- [ ] Comparisons are meaningful
|
||||
- [ ] Data can be exported
|
||||
- [ ] Performance is good with large datasets
|
||||
|
||||
## 🔧 Technical Specifications
|
||||
|
||||
### Component Library Options
|
||||
**Status:** ⏳ PENDING USER CHOICE
|
||||
|
||||
#### Option 1: Nuxt UI (Recommended)
|
||||
**Pros:**
|
||||
- Built specifically for Nuxt 3
|
||||
- Tailwind CSS integration
|
||||
- TypeScript support
|
||||
- Modern design system
|
||||
- Active development
|
||||
|
||||
**Cons:**
|
||||
- Newer library, smaller ecosystem
|
||||
- Limited complex components
|
||||
|
||||
#### Option 2: Vuetify
|
||||
**Pros:**
|
||||
- Mature, comprehensive library
|
||||
- Material Design system
|
||||
- Extensive component set
|
||||
- Strong community support
|
||||
|
||||
**Cons:**
|
||||
- Larger bundle size
|
||||
- Material Design may not fit brand
|
||||
- Vue 3 support still maturing
|
||||
|
||||
#### Option 3: PrimeVue
|
||||
**Pros:**
|
||||
- Enterprise-focused
|
||||
- Comprehensive component set
|
||||
- Good TypeScript support
|
||||
- Professional themes
|
||||
|
||||
**Cons:**
|
||||
- Commercial themes cost money
|
||||
- Larger learning curve
|
||||
- Less modern design
|
||||
|
||||
### Development Environment
|
||||
- **Node.js:** Version 18+ required
|
||||
- **Package Manager:** npm (consistent with project)
|
||||
- **Development Server:** Nuxt dev server with HMR
|
||||
- **Proxy Configuration:** API calls proxied to Django backend
|
||||
- **Environment Variables:** Separate configs for dev/staging/production
|
||||
|
||||
### Build & Deployment
|
||||
- **Build Tool:** Nuxt build with Vite
|
||||
- **Output:** Static generation for public pages, SSR for dynamic content
|
||||
- **Docker:** Multi-stage build for production
|
||||
- **CI/CD:** GitHub Actions for automated testing and deployment
|
||||
- **Monitoring:** Error tracking and performance monitoring
|
||||
|
||||
## 📊 Non-Functional Requirements
|
||||
|
||||
### Performance
|
||||
- **Page Load Time:** < 3 seconds initial load
|
||||
- **Navigation:** < 1 second between pages
|
||||
- **API Response Time:** < 500ms for most endpoints
|
||||
- **Bundle Size:** < 500KB initial JavaScript
|
||||
- **Image Loading:** Progressive loading with placeholders
|
||||
|
||||
### Scalability
|
||||
- **Concurrent Users:** Support 1000+ concurrent users
|
||||
- **Data Volume:** Handle 10,000+ parks and 50,000+ rides
|
||||
- **API Calls:** Efficient caching to minimize backend load
|
||||
- **Database:** Optimized queries and indexing
|
||||
|
||||
### Security
|
||||
- **Authentication:** Secure JWT implementation
|
||||
- **Data Validation:** Client and server-side validation
|
||||
- **XSS Protection:** Sanitized user input
|
||||
- **CSRF Protection:** Token-based protection
|
||||
- **HTTPS:** All production traffic encrypted
|
||||
|
||||
### Accessibility
|
||||
- **WCAG Compliance:** Level AA compliance
|
||||
- **Keyboard Navigation:** Full keyboard accessibility
|
||||
- **Screen Readers:** Proper ARIA labels and roles
|
||||
- **Color Contrast:** Minimum 4.5:1 contrast ratio
|
||||
- **Focus Management:** Clear focus indicators
|
||||
|
||||
### Browser Support
|
||||
- **Modern Browsers:** Chrome, Firefox, Safari, Edge (latest 2 versions)
|
||||
- **Mobile Browsers:** iOS Safari, Chrome Mobile
|
||||
- **Progressive Enhancement:** Basic functionality without JavaScript
|
||||
- **Polyfills:** Minimal polyfills for essential features
|
||||
|
||||
## 🧪 Testing Requirements
|
||||
|
||||
### Testing Strategy
|
||||
- **Unit Tests:** 80%+ code coverage for utilities and composables
|
||||
- **Component Tests:** All UI components tested
|
||||
- **Integration Tests:** API integration and user flows
|
||||
- **E2E Tests:** Critical user journeys automated
|
||||
- **Performance Tests:** Load testing and optimization
|
||||
|
||||
### Testing Tools
|
||||
- **Unit Testing:** Vitest for fast unit tests
|
||||
- **Component Testing:** Vue Test Utils with Vitest
|
||||
- **E2E Testing:** Playwright for cross-browser testing
|
||||
- **Visual Testing:** Chromatic for visual regression
|
||||
- **Performance Testing:** Lighthouse CI for performance monitoring
|
||||
|
||||
## 📚 Documentation Requirements
|
||||
|
||||
### Code Documentation
|
||||
- **Component Documentation:** Props, events, slots documented
|
||||
- **API Documentation:** All composables and utilities documented
|
||||
- **Type Definitions:** Comprehensive TypeScript types
|
||||
- **Examples:** Usage examples for all components
|
||||
- **Storybook:** Interactive component documentation
|
||||
|
||||
### User Documentation
|
||||
- **User Guide:** How to use the application
|
||||
- **Admin Guide:** Moderation and administration
|
||||
- **API Guide:** For developers integrating with the system
|
||||
- **Deployment Guide:** Self-hosting instructions
|
||||
- **Troubleshooting:** Common issues and solutions
|
||||
|
||||
### Context7 Integration
|
||||
- **Auto-Documentation:** Automatic API and component docs
|
||||
- **Implementation Tracking:** Progress and decision documentation
|
||||
- **Knowledge Preservation:** Context for future development
|
||||
- **LLM Handoffs:** Structured information for continuation
|
||||
|
||||
---
|
||||
|
||||
## ✅ Acceptance Criteria Summary
|
||||
|
||||
### Phase 1: Foundation (Week 1)
|
||||
- [ ] Nuxt 3 project set up with TypeScript
|
||||
- [ ] Component library integrated and configured
|
||||
- [ ] Authentication system implemented with JWT
|
||||
- [ ] Basic layout and navigation components
|
||||
- [ ] API integration with Django backend
|
||||
- [ ] Development environment fully configured
|
||||
|
||||
### Phase 2: Core Features (Week 2)
|
||||
- [ ] Parks listing and detail pages functional
|
||||
- [ ] Rides listing and detail pages functional
|
||||
- [ ] Search functionality working across content
|
||||
- [ ] Photo upload and display system
|
||||
- [ ] User profile management
|
||||
- [ ] Basic submission forms
|
||||
|
||||
### Phase 3: Advanced Features (Week 3)
|
||||
- [ ] Complete submission system with moderation
|
||||
- [ ] Admin moderation interface
|
||||
- [ ] Advanced search and filtering
|
||||
- [ ] Maps integration for locations
|
||||
- [ ] Rankings and statistics display
|
||||
- [ ] Performance optimization complete
|
||||
|
||||
### Phase 4: Polish & Deployment (Week 4)
|
||||
- [ ] Comprehensive testing suite
|
||||
- [ ] Documentation complete
|
||||
- [ ] Production deployment configured
|
||||
- [ ] Performance monitoring set up
|
||||
- [ ] User acceptance testing passed
|
||||
|
||||
---
|
||||
|
||||
**Next Document:** `architecture-decisions.md` - Technical architecture details
|
||||
Reference in New Issue
Block a user