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.