service-finder/docs/B2C_B2B_UI_Architecture_Plan.md

B2C vs B2B UI Architecture Plan

Date: 2026-03-30
Version: 2.0
Based on: User requirements for Vehicle Details/Dashboard

Executive Summary

This document outlines the architectural strategy for implementing dual-mode UI (B2C Personal vs B2B Fleet) with explicit verification feedback. The plan addresses the user's strict requirements for visual layout differences and verification UI.

1. Core Principles

1.1 Mode Detection & Switching

• Source of Truth: appModeStore.mode ('personal' | 'fleet')
• Trigger: User selection via profile selector or organization context
• Persistence: LocalStorage with sync to backend active organization

1.2 Data Segregation

• Personal Mode: organization_id = NULL or user's personal scope
• Fleet Mode: organization_id = <selected_org_id>
• API Filtering: All vehicle queries include organization_id filter based on mode

2. Layout Requirements

2.1 B2C Personal Mode - "Cards/Tiles" (Kártyás/Csempés)

Visual Characteristics:

• Highly visual, image-focused design
• Card-based grid layout (2-4 columns based on screen size)
• Rich media: vehicle images, brand logos, color accents
• Emotional appeal: personal achievement badges, gamification elements

Component Structure:

VehicleShowcase (Personal Mode)
├── VehicleCardGrid (TransitionGroup)
│   ├── VehicleCard (Visual)
│   │   ├── VehicleImage (Hero)
│   │   ├── BrandLogo
│   │   ├── QuickStats (Visual)
│   │   └── ActionButtons (Personal)
│   └── AddVehicleCard (CTA)
└── PersonalDashboard
    ├── FunStats (Visualizations)
    ├── AchievementShowcase
    └── QuickActions (Personal)

Technical Implementation:

• Grid layout: grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4
• Card animations: Staggered entrance, hover effects
• Image optimization: Lazy loading, WebP format with fallbacks

2.2 B2B Fleet Mode - "Menu/List" (Menü)

Visual Characteristics:

• Clean, professional, high data density
• Table/list view with sortable columns
• Minimal visual clutter, maximum information
• Corporate branding: dark headers, subtle gradients

Component Structure:

VehicleShowcase (Fleet Mode)
├── FleetTable (Enterprise)
│   ├── CorporateHeader (Stats)
│   ├── SortableTable
│   │   ├── ColumnHeaders (Sortable)
│   │   ├── VehicleRow (Dense)
│   │   │   ├── EssentialData (Text)
│   │   │   ├── StatusIndicators (Minimal)
│   │   │   └── ActionMenu (Contextual)
│   │   └── BulkActions
│   └── ExportControls
└── BusinessAnalytics
    ├── TCO Dashboard
    ├── FleetMetrics
    └── ReportGenerator

Technical Implementation:

• Table component: Virtual scrolling for large datasets
• Export functionality: CSV, PDF, Excel
• Bulk operations: Multi-select, batch updates

3. Verification UI Requirements

3.1 Verification States

Every piece of data or service event must indicate verification status:

Verification Level	Visual Indicator	Usage
100% Verified	Green checkmark + "Verified" badge	System-verified data (VIN, mileage from connected services)
Workshop Verified	Blue wrench + "Workshop Confirmed"	Service records from authorized workshops
User Reported	Yellow user icon + "User Reported"	Manual user entry, requires verification
Pending Verification	Gray clock + "Pending"	Data submitted but not yet verified
Verification Failed	Red x + "Needs Review"	System detected inconsistency

3.2 Implementation Strategy

Component: VerificationBadge

<template>
  <span :class="badgeClasses" :title="tooltipText">
    <component :is="iconComponent" class="w-3 h-3 mr-1" />
    {{ label }}
  </span>
</template>

<script>
export default {
  props: {
    level: { type: String, required: true }, // 'verified', 'workshop', 'user', 'pending', 'failed'
    dataType: { type: String, required: true } // 'vin', 'mileage', 'service', 'ownership'
  },
  computed: {
    badgeClasses() {
      const base = 'inline-flex items-center px-2 py-1 rounded-full text-xs font-medium'
      const colors = {
        verified: 'bg-green-100 text-green-800 border border-green-300',
        workshop: 'bg-blue-100 text-blue-800 border border-blue-300',
        user: 'bg-yellow-100 text-yellow-800 border border-yellow-300',
        pending: 'bg-gray-100 text-gray-800 border border-gray-300',
        failed: 'bg-red-100 text-red-800 border border-red-300'
      }
      return `${base} ${colors[this.level]}`
    },
    // ... other computed properties
  }
}
</script>

Data Model Extension:

interface VerificationMetadata {
  level: 'verified' | 'workshop' | 'user' | 'pending' | 'failed'
  verifiedAt: string | null
  verifiedBy: string | null // 'system', 'workshop_id', 'user_id'
  source: string // 'api_vin_decode', 'manual_entry', 'workshop_system'
  confidenceScore: number // 0-100
}

4. Vehicle Details/Dashboard Architecture

4.1 Dual-Mode Dashboard Components

Personal Vehicle Detail View:

VehicleDetailPage (Personal)
├── HeroSection (Large image, emotional)
├── QuickStatsCards (Visual, colorful)
├── ServiceTimeline (Visual timeline)
├── ExpenseBreakdown (Pie charts)
└── PersonalNotes (User content)

Fleet Vehicle Detail View:

VehicleDetailPage (Fleet)
├── HeaderRow (Essential data, compact)
├── TCO Analysis (Financial focus)
├── ServiceHistory (Table view)
├── ComplianceStatus (Regulatory)
└── Documents (Contract links)

4.2 Responsive Design Strategy

Breakpoint	Personal Mode (Cards)	Fleet Mode (Table)
Mobile	1 column, stacked cards	Horizontal scroll, compact rows
Tablet	2 columns	Full table, reduced padding
Desktop	3-4 columns	Full table with all columns
Wide	4+ columns, larger cards	Expanded table with side panels

5. Implementation Roadmap

Phase 1: Foundation (Current Sprint)

• Fix SmartVehicleRegistration generation dropdown bug
• Add organization context selector to registration
• Create VerificationBadge component
• Extend vehicle data model with verification metadata

Phase 2: Layout Enhancement (Next Sprint)

• Enhance VehicleCard with verification badges
• Upgrade FleetTable with verification column
• Implement responsive breakpoints for both layouts
• Add empty states with mode-appropriate CTAs

Phase 3: Data Integration (Sprint 3)

• Connect verification badges to backend verification status
• Implement verification source tracking
• Add verification confidence scoring
• Create verification audit log

Phase 4: Advanced Features (Sprint 4+)

• Verification request workflow (user → workshop → system)
• Automated verification rules engine
• Verification history timeline
• Bulk verification operations (fleet mode)

6. Technical Specifications

6.1 CSS Strategy

• Personal Mode: Emotion-focused classes (hover:scale-105, transition-all, shadow-xl)
• Fleet Mode: Professional classes (divide-y, text-sm, font-medium)
• Shared Base: Tailwind utility classes for consistency

6.2 State Management

// Extended app mode store
interface AppModeState {
  mode: 'personal' | 'fleet'
  organizationId: string | null
  uiDensity: 'comfortable' | 'compact' // Fleet mode only
  verificationBadgesVisible: boolean
}

// Vehicle store with verification
interface VehicleWithVerification {
  id: string
  // ... existing fields
  verification: {
    [key in 'vin' | 'mileage' | 'service' | 'ownership']: VerificationMetadata
  }
}

6.3 Performance Considerations

• Personal Mode: Image lazy loading, card virtualization for large collections
• Fleet Mode: Table virtualization, column visibility toggles
• Both: API response caching, optimistic UI updates

7. Success Metrics

7.1 UX Metrics

• Personal Mode: Time to find vehicle < 3s, engagement with visual elements
• Fleet Mode: Time to sort/filter < 2s, data density perception
• Verification UI: User trust score, reduction in manual verification requests

7.2 Technical Metrics

• Performance: First Contentful Paint < 1.5s, Time to Interactive < 3s
• Accessibility: WCAG 2.1 AA compliance, keyboard navigation support
• Maintainability: Component reuse > 70%, CSS specificity score < 100

8. Risk Mitigation

8.1 Identified Risks

1. Visual inconsistency between modes
2. Performance degradation with verification badges
3. Backward compatibility with existing vehicle data
4. User confusion when switching modes

8.2 Mitigation Strategies

1. Design system tokens for consistent styling
2. Lazy loading of verification badges
3. Default verification states for legacy data
4. Clear mode indicators and onboarding tooltips

---

Approval: This architecture plan satisfies the user's requirements for distinct B2C/B2B layouts with explicit verification feedback. Implementation will proceed according to the phased roadmap.