diff --git a/.clinerules b/.clinerules
index f966e91a..939a5d5b 100644
--- a/.clinerules
+++ b/.clinerules
@@ -3,10 +3,13 @@
## Development Server
IMPORTANT: Always follow these instructions exactly when starting the development server:
-```bash
-lsof -ti :8000 | xargs kill -9; find . -type d -name "__pycache__" -exec rm -r {} +; ./scripts/dev_server.sh
+FIRST, assume the server is running. Always. Assume the changes have taken effect.
-Note: These steps must be executed in this exact order as a single command to ensure consistent behavior. If server does not start correctly, do not attempt to modify the dev_server.sh script.
+IF THERE IS AN ISSUE WITH THE SERVER, run the following command exactly:
+```bash
+lsof -ti :8000 | xargs kill -9; find . -type d -name "__pycache__" -exec rm -r {} +; cd backend && uv run manage.py runserver_plus && cd ../frontend && pnpm run dev
+
+Note: These steps must be executed in this exact order to ensure consistent behavior. If server does not start correctly, fix the error in accordance with the error details as best you can.
## Package Management
IMPORTANT: When a Python package is needed, only use UV to add it:
@@ -47,8 +50,30 @@ IMPORTANT: Follow these entity relationship patterns consistently:
- PropertyOwners: Companies that own park property (new concept, optional)
- Manufacturers: Companies that manufacture rides (replaces Company for rides)
- Designers: Companies/individuals that design rides (existing concept)
+- IMPORTANT: All entities can have locations.
# Relationship Constraints
- Operator and PropertyOwner are usually the same entity but CAN be different
- Manufacturers and Designers are distinct concepts and should not be conflated
-- All entity relationships should use proper foreign keys with appropriate null/blank settings
\ No newline at end of file
+- All entity relationships should use proper foreign keys with appropriate null/blank settings
+
+- You are to NEVER assume that blank output means your fixes were correct. That assumption can lead to further issues down the line.
+- ALWAYS verify your changes by testing the affected functionality thoroughly.
+- ALWAYS use context7 to check documentation when troubleshooting. It contains VITAL documentation for any and all frameworks, modules, and packages.
+- ALWAYS document your code changes with conport and the reasoning behind them.
+- ALWAYS include relevant context and information when making changes to the codebase.
+- ALWAYS ensure that your code changes are properly tested and validated before deployment.
+- ALWAYS communicate clearly and effectively with your team about any changes you make.
+- ALWAYS be open to feedback and willing to make adjustments as necessary.
+- ALWAYS strive for continuous improvement in your work and processes.
+- ALWAYS prioritize code readability and maintainability.
+- ALWAYS keep security best practices in mind when developing and reviewing code.
+- ALWAYS consider performance implications when making changes to the codebase.
+- ALWAYS be mindful of the impact of your changes on the overall system architecture.
+- ALWAYS keep scalability in mind when designing new features or modifying existing ones.
+- ALWAYS consider the potential for code reuse and modularity in your designs.
+- ALWAYS document your code with clear and concise comments.
+- ALWAYS keep your code DRY (Don't Repeat Yourself) by abstracting common functionality into reusable components.
+- ALWAYS use meaningful variable and function names to improve code readability.
+- ALWAYS handle errors and exceptions gracefully to improve the user experience.
+- ALWAYS log important events and errors for troubleshooting purposes.
\ No newline at end of file
diff --git a/README.md b/README.md
index 462c7ddd..de7679e3 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,29 @@
# ThrillWiki Django + Vue.js Monorepo
-A modern monorepo architecture for ThrillWiki, combining a Django REST API backend with a Vue.js frontend.
+A comprehensive theme park and roller coaster information system built with a modern monorepo architecture combining Django REST API backend with Vue.js frontend.
-## ๐๏ธ Architecture
+## ๐๏ธ Architecture Overview
-This project uses a monorepo structure that cleanly separates backend and frontend concerns:
+This project uses a monorepo structure that cleanly separates backend and frontend concerns while maintaining shared resources and documentation:
```
thrillwiki-monorepo/
-โโโ backend/ # Django REST API
-โโโ frontend/ # Vue.js SPA
-โโโ shared/ # Shared resources and documentation
+โโโ backend/ # Django REST API (Port 8000)
+โ โโโ apps/ # Modular Django applications
+โ โโโ config/ # Django settings and configuration
+โ โโโ templates/ # Django templates
+โ โโโ static/ # Static assets
+โโโ frontend/ # Vue.js SPA (Port 5174)
+โ โโโ src/ # Vue.js source code
+โ โโโ public/ # Static assets
+โ โโโ dist/ # Build output
+โโโ shared/ # Shared resources and documentation
+โ โโโ docs/ # Comprehensive documentation
+โ โโโ scripts/ # Development and deployment scripts
+โ โโโ config/ # Shared configuration
+โ โโโ media/ # Shared media files
+โโโ architecture/ # Architecture documentation
+โโโ profiles/ # Development profiles
```
## ๐ Quick Start
@@ -19,6 +32,8 @@ thrillwiki-monorepo/
- **Python 3.11+** with [uv](https://docs.astral.sh/uv/) for backend dependencies
- **Node.js 18+** with [pnpm](https://pnpm.io/) for frontend dependencies
+- **PostgreSQL 14+** (optional, defaults to SQLite for development)
+- **Redis 6+** (optional, for caching and sessions)
### Development Setup
@@ -32,41 +47,63 @@ thrillwiki-monorepo/
```bash
# Install frontend dependencies
pnpm install
-
+
# Install backend dependencies
- cd backend && uv sync
+ cd backend && uv sync && cd ..
```
-3. **Start development servers**
+3. **Environment configuration**
```bash
- # Start both frontend and backend
- pnpm run dev
-
- # Or start individually
- pnpm run dev:frontend # Vue.js on :3000
- pnpm run dev:backend # Django on :8000
+ # Copy environment files
+ cp .env.example .env
+ cp backend/.env.example backend/.env
+ cp frontend/.env.development frontend/.env.local
+
+ # Edit .env files with your settings
```
-## ๐ Project Structure
+4. **Database setup**
+ ```bash
+ cd backend
+ uv run manage.py migrate
+ uv run manage.py createsuperuser
+ cd ..
+ ```
+
+5. **Start development servers**
+ ```bash
+ # Start both servers concurrently
+ pnpm run dev
+
+ # Or start individually
+ pnpm run dev:frontend # Vue.js on :5174
+ pnpm run dev:backend # Django on :8000
+ ```
+
+## ๐ Project Structure Details
### Backend (`/backend`)
-- **Django REST API** with modular app architecture
-- **UV package management** for Python dependencies
-- **PostgreSQL** database (configurable)
-- **Redis** for caching and sessions
+- **Django 5.0+** with REST Framework for API development
+- **Modular app architecture** with separate apps for parks, rides, accounts, etc.
+- **UV package management** for fast, reliable Python dependency management
+- **PostgreSQL/SQLite** database with comprehensive entity relationships
+- **Redis** for caching, sessions, and background tasks
+- **Comprehensive API** with frontend serializers for camelCase conversion
### Frontend (`/frontend`)
-- **Vue 3** with Composition API
-- **TypeScript** for type safety
-- **Vite** for fast development and building
-- **Tailwind CSS** for styling
-- **Pinia** for state management
+- **Vue 3** with Composition API and `
-
-
-```
-
-### 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(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
+- **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
-- **Dark mode** support with class strategy
-- **Custom colors** for brand consistency
-- **Responsive design** utilities
-- **Component classes** for reusable styles
+Custom design system configured in `tailwind.config.js`:
-### Theme System
+- **Custom color palette** with CSS variables
+- **Dark mode support** with `class` strategy
+- **Component classes** for consistent styling
+- **Material Design** inspired design tokens
-```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 }
-}
-```
+## ๐ Project Structure Details
-## ๐ API Integration
+### Components Architecture
-### Service Layer
+#### UI Components (`src/components/ui/`)
+Base component library following shadcn-vue patterns:
-```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 })
- }
-}
-```
+- **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
-### Error Handling
+#### Layout Components (`src/components/layout/`)
+Application layout and navigation:
-- Global error interceptors
-- User-friendly error messages
-- Retry mechanisms for failed requests
-- Offline support indicators
+- **Navbar** - Main navigation with responsive design
+- **ThemeController** - Dark/light mode toggle
+- **Footer** - Site footer with links
-## ๐งช Testing
+#### Specialized Components
+- **State Layer** - Material Design ripple effects
+- **Icon** - Lucide React icon wrapper
+- **Button variants** - Different button styles
-### Test Structure
+### Views Structure
-```bash
-tests/
-โโโ unit/ # Unit tests
-โโโ e2e/ # End-to-end tests
-โโโ __mocks__/ # Mock files
-```
+#### 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
-### Running Tests
+### State Management
-```bash
-# Unit tests
-pnpm run test
+#### 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
-# E2E tests
-pnpm run test:e2e
+### API Integration
-# Watch mode
-pnpm run test:watch
-```
+#### 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
-### Testing Tools
+### Type Definitions
-- **Vitest** - Unit testing framework
-- **Vue Test Utils** - Vue component testing
-- **Playwright** - End-to-end testing
+#### 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
-## ๐ฑ Progressive Web App
+## ๐จ Design System
-PWA features:
+### 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
-- **Service Worker** for offline functionality
-- **App Manifest** for installation
-- **Push Notifications** for updates
-- **Background Sync** for data synchronization
+### Typography
+- **Inter font family** for modern appearance
+- **Responsive text scales** for all screen sizes
+- **Consistent line heights** for readability
-## ๐ง Build & Deployment
+### Component Variants
+- **Button variants** - Primary, secondary, outline, ghost
+- **Card variants** - Default, elevated, outlined
+- **Input variants** - Default, error, success
-### Development Build
+### Dark Mode
+- **Automatic detection** of system preference
+- **Manual toggle** in theme controller
+- **Smooth transitions** between themes
+- **CSS custom properties** for dynamic theming
-```bash
-pnpm run dev
-```
+## ๐งช Testing Strategy
-### Production Build
+### 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
-```bash
-pnpm run build
-```
+### 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
-### 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)
- }
- }
-}
-```
+### 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
-See the [Deployment Guide](../shared/docs/deployment/) for production setup.
+### 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
-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
\ No newline at end of file
+### Code Standards
+1. **Vue 3 Composition API** with `
-