service-finder/docs/epic_11_public_frontend_spec.md

# Epic 11 - The Smart Garage (User Frontend)
**Frontend Specification for Service Finder Public Interface - Dual-UI, Gamified, Brand-Aware Vehicle Management**

## 📋 Overview
This epic defines the development of a dual-interface public frontend for Service Finder end-users (B2C and B2B). The "Smart Garage" offers two distinct experiences: a youthful, gamified "Private Garage" for individual vehicle owners and a clean, analytical "Corporate Fleet" interface for business users. Upon login, users choose their preferred interface, which then tailors the entire experience to their needs.

## 🎯 Core Concept: Dual-UI Architecture
**Kétarcú UI** - One system, two completely different visual and functional experiences based on user type.

### 🏠 **Private Garage** (Privát Garázs)
- **Target Audience:** Individual vehicle owners, enthusiasts, young drivers
- **Design Aesthetic:** Youthful, energetic, gamified, themeable
- **Color Scheme:** Vibrant colors, gradients, dynamic animations
- **Key Focus:** Fun, engagement, community, personal achievement
- **Gamification:** Heavy emphasis on points, levels, badges, daily challenges

### 🏢 **Corporate Fleet** (Céges Flotta)
- **Target Audience:** Fleet managers, business owners, logistics companies
- **Design Aesthetic:** Professional, clean, data-driven, minimalist
- **Color Scheme:** Corporate blues/grays, clean lines, subtle accents
- **Key Focus:** ROI, TCO (Total Cost of Ownership), analytics, efficiency
- **Gamification:** Light - focuses on efficiency metrics and cost savings

## 🚪 Entry Point: Profile Selector Screen
Upon successful authentication, users are presented with a choice screen before entering the main application.

### Profile Selector Requirements:
1. **Visual Choice Interface**
   - Two large, visually distinct cards: "Private Garage" and "Corporate Fleet"
   - Animated previews showing each interface's style
   - Brief description of each mode's benefits

2. **Smart Default & Memory**
   - Remember user's last choice (cookie/localStorage)
   - Allow switching modes later via settings
   - "Not sure? Try Private Garage" for new users

3. **Role Enforcement**
   - B2B accounts (company-associated) default to Fleet but can choose Garage
   - B2C accounts default to Garage but can request Fleet access

## 🧩 Core Features (Both Interfaces)

### 1. **Daily Quiz** (Napi Kvíz)
- **Purpose:** Engage users daily, educate about vehicle maintenance, reward participation
- **Implementation:** Dismissible pop-up appearing once per 24 hours
- **Functionality:**
  - Multiple-choice questions about vehicle care, safety, Service Finder features
  - Immediate feedback with explanations
  - Points awarded for correct answers (scaling with difficulty)
  - Streak counter for consecutive days of participation
- **Future Expansion:** Foundation for full educational module

### 2. **Garage Display** (Garázs Csempék)
- **Core Requirement:** Display user's vehicles with **real brand logos and country flags**
- **Implementation:**
  - Vehicle cards/tiles showing make, model, year, license plate
  - High-quality SVG brand logos (downloaded from brand repositories)
  - Country flag based on vehicle origin/registration
  - Quick status indicators (service due, expenses this month, fuel level if connected)
- **Visual Design:**
  - Private Garage: Animated cards, hover effects, themeable backgrounds
  - Corporate Fleet: Compact table view, sortable columns, export options

### 3. **Quick Action Buttons** (Gyors-akció Gombok)
- **Primary Actions:**
  1. **[Költség felvitele]** - Quick expense entry
  2. **[Szerviz keresése]** - Service finder launch
  3. **[Üzemanyag]** - Fuel tracking (if enabled)
  4. **[Jármű hozzáadása]** - Add new vehicle
- **Implementation:**
  - Floating action button (FAB) or fixed toolbar
  - Context-sensitive actions (e.g., if vehicle selected, actions apply to that vehicle)
  - One-tap modals for quick data entry

### 4. **Trophy Showcase** (Vitrin - Gamification Kupák és Díjak)
- **Purpose:** Visual display of user achievements
- **Implementation:**
  - Trophy cabinet/shelf metaphor
  - 3D-rendered or high-quality 2D trophy graphics
  - Categories: Participation, Knowledge, Savings, Community
  - Empty slots for future achievements (creates goals)
- **Private Garage:** Prominent display, celebration animations when earned
- **Corporate Fleet:** Subtle badge system, efficiency achievement markers

### 5. **Vehicle Detail & Analytics**
- **Private Garage:** Fun stats (km driven equivalent to moon distance, CO2 saved vs trees)
- **Corporate Fleet:** Serious analytics (TCO per km, maintenance cost trends, ROI calculations)
- **Shared Features:**
  - Service history timeline
  - Expense categorization charts
  - Fuel efficiency graphs
  - Predictive maintenance alerts

## 🎫 Development Tickets (Gitea Issues)

### Ticket 1: Dual-UI Profile Selector & Mode Switching System
**Scope:** Frontend Core, Authentication Flow, User Preferences
**Complexity:** Medium

#### Requirements:
1. **Profile Selector Component**
   - Two large interactive cards with animated previews
   - Visual distinction between Private Garage and Corporate Fleet styles
   - Responsive design (mobile/tablet/desktop)

2. **User Preference Management**
   - API integration for saving/retrieving interface preference
   - Local storage fallback for offline usage
   - Preference change auditing

3. **Authentication Flow Integration**
   - Redirect to selector after successful login
   - Skip selector if preference already set (configurable)
   - "Remember my choice" option with expiration

4. **Mode Switching Mechanism**
   - Settings page option to switch between interfaces
   - Confirmation modal explaining implications
   - Session restart or dynamic theme switching

### Ticket 2: Daily Quiz System with Dismissible Pop-up
**Scope:** Frontend Engagement, Education, Gamification
**Complexity:** Medium

#### Requirements:
1. **Quiz Pop-up Component**
   - Dismissible modal that appears once per 24 hours per user
   - Configurable appearance delay (e.g., 30 seconds after page load)
   - "Remind me later" and "Don't show again today" options

2. **Question Management**
   - Dynamic question loading from API/content management system
   - Multiple-choice format with 4 options
   - Question categories (Maintenance, Safety, Service Finder Features, Vehicle Knowledge)

3. **Scoring & Rewards**
   - Points awarded based on question difficulty
   - Streak counter for consecutive days of participation
   - Visual feedback (confetti for correct, gentle correction for wrong)

4. **Quiz Administration**
   - Admin interface for adding/editing questions
   - Question scheduling (seasonal questions, promotional content)
   - Analytics dashboard for quiz participation rates

### Ticket 3: Garage Tile System with Real Brand Logos & Country Flags
**Scope:** Frontend UI, Asset Management, Vehicle Display
**Complexity:** High

#### Requirements:
1. **Brand Logo Integration**
   - SVG logo library for all major vehicle brands (200+ brands)
   - Logo licensing verification and compliance
   - Fallback generic vehicle icon for unknown brands
   - Logo optimization and lazy loading

2. **Vehicle Card/Tile Components**
   - Two display modes: Card view (Private Garage) and Table row (Corporate Fleet)
   - Vehicle image placeholder with brand logo overlay
   - Country flag based on vehicle registration/origin
   - Quick status indicators (service due, insurance expiry, etc.)

3. **Garage Layout Management**
   - Grid layout for Private Garage (themable, rearrangeable)
   - Sortable table for Corporate Fleet (by cost, mileage, age, etc.)
   - Filtering by vehicle type, status, location

4. **Asset Management System**
   - Centralized asset service for logos and flags
   - CDN integration for fast delivery
   - Cache management and version control

### Ticket 4: Quick Action Buttons & Contextual Shortcuts
**Scope:** Frontend UX, Productivity, User Flows
**Complexity:** Medium

#### Requirements:
1. **Quick Action System**
   - Floating Action Button (FAB) that expands to show actions
   - Context-aware actions (different actions if vehicle is selected)
   - Keyboard shortcuts for power users

2. **Core Action Implementations**
   - **Expense Entry:** Modal form with smart categorization (fuel, maintenance, insurance, etc.)
   - **Service Finder:** Launch service search with pre-filled vehicle details
   - **Fuel Tracking:** Quick fuel entry with odometer, amount, price per liter
   - **Vehicle Add:** Streamlined vehicle addition form

3. **Action Customization**
   - User-configurable quick actions (choose which 4 appear)
   - Role-based action availability (fleet managers see different actions)
   - Usage analytics to suggest most relevant actions

4. **Mobile Optimization**
   - Bottom navigation bar for mobile devices
   - Swipe gestures for quick access
   - Haptic feedback on action completion

### Ticket 5: Trophy Showcase & Gamification Display
**Scope:** Frontend Gamification, Visual Design, Animation
**Complexity:** Medium-High

#### Requirements:
1. **Trophy Cabinet Component**
   - 3D shelf or grid display of earned trophies
   - Trophy categories with distinct visual styles
   - Empty trophy slots with "locked" visual state

2. **Trophy System Integration**
   - API integration with backend gamification system
   - Real-time trophy unlock notifications
   - Trophy detail views (unlock criteria, rarity statistics)

3. **Achievement Animations**
   - Celebration sequence when trophy earned
   - Subtle glow/pulse for newly earned trophies
   - Share functionality (social media integration)

4. **Corporate Fleet Achievement System**
   - Professional badge system for efficiency milestones
   - Cost-saving achievement markers
   - Team/company-wide achievement boards

### Ticket 6: Vehicle Analytics & TCO Dashboard
**Scope:** Frontend Data Visualization, Analytics, Business Intelligence
**Complexity:** High

#### Requirements:
1. **Dual-Interface Analytics**
   - Private Garage: Fun, engaging visualizations (km to moon, CO2 to trees)
   - Corporate Fleet: Professional business intelligence (TCO, ROI, depreciation)

2. **TCO Calculation Dashboard**
   - Total Cost of Ownership breakdown (acquisition, fuel, maintenance, insurance, tax)
   - Cost per kilometer/mile calculations
   - Comparison against vehicle class averages

3. **Predictive Analytics**
   - Maintenance cost forecasting based on mileage/age
   - Fuel price trend analysis
   - Optimal replacement timing suggestions

4. **Report Generation**
   - Export analytics as PDF/Excel
   - Scheduled report delivery (email)
   - Shareable dashboard links for team collaboration

## 🛠️ Technology Stack
- **Framework:** Vue 3 with Composition API (consistent with admin interface)
- **UI Library:** Vuetify 3 for Corporate Fleet, custom themed components for Private Garage
- **State Management:** Pinia with separate stores for Garage/Fleet modes
- **Charts:** Chart.js for analytics, D3.js for advanced visualizations
- **Maps:** Leaflet for service finder integration
- **Animation:** GSAP for smooth transitions and trophy animations
- **HTTP Client:** Axios with interceptors for mode-specific API routing
- **Authentication:** JWT tokens with mode preference claim
- **Build Tool:** Vite with separate build configurations for optimization
- **Package Manager:** npm

## 🎨 Design Requirements
- **Private Garage Design System:**
  - Vibrant color palette with gradients
  - Rounded corners, soft shadows, playful typography
  - Interactive elements with hover/focus animations
  - Theme support (light/dark/seasonal themes)

- **Corporate Fleet Design System:**
  - Material Design 3 with corporate refinement
  - Clean lines, ample white space, professional typography
  - Subtle animations for transitions only
  - Accessibility-focused (WCAG 2.1 AA compliant)

- **Brand Logo Integration:** High-quality SVG logos with consistent sizing and coloring
- **Country Flags:** Standardized flag library with proper aspect ratios

## 🔧 Technical Specifications
- **Code Quality:** TypeScript strict mode, component-based architecture
- **Testing:** Vitest for unit tests, Cypress for E2E with mode-switching scenarios
- **Performance:** Lazy loading of mode-specific bundles, image optimization
- **Security:** Content Security Policy for SVG assets, XSS protection
- **Browser Support:** Chrome 90+, Firefox 88+, Safari 14+, Edge 90+

## 📊 Success Metrics
- **User Engagement:** Daily quiz participation > 40% of active users
- **Performance:** Mode switching < 500ms, page load < 2 seconds
- **Satisfaction:** User preference retention > 80% (users don't switch back)
- **Business:** Fleet users report time savings > 2 hours/week on vehicle management

## 🔗 Dependencies
- **Backend:** Vehicle API with brand/origin data, Gamification API for trophies
- **APIs:** Quiz content API, Expense tracking API, Service finder API
- **External:** Brand logo SVG repository, Country flag library
- **Design:** Complete design systems for both interfaces

## 📅 Implementation Phases
1. **Phase 1 (Week 1-3):** Foundation - Profile selector, mode switching, basic layout
2. **Phase 2 (Week 4-6):** Core features - Garage tiles, quick actions, basic analytics
3. **Phase 3 (Week 7-9):** Gamification - Daily quiz, trophy system, animations
4. **Phase 4 (Week 10-12):** Advanced analytics - TCO dashboard, predictive features
5. **Phase 5 (Week 13-14):** Polish - Performance optimization, accessibility, testing

## 🚀 Deployment Strategy
- **Development:** Feature flags for dual-UI components
- **Staging:** A/B testing of interface preferences with test users
- **Production:** Gradual rollout starting with Private Garage, then Corporate Fleet

---

*This specification serves as the foundation for Gitea ticket creation and frontend development planning. Each "Ticket" section corresponds to a separate development ticket that will be created in the Gitea project management system.*