service-finder/docs/epic_10_admin_frontend_spec.md

Epic 10 - Mission Control (Admin Dashboard)

Frontend Specification for Service Finder Admin Interface - Dual-UI, Gamified, RBAC-protected SaaS System

📋 Overview

This epic defines the development of a modular "Launchpad" admin dashboard with strict geographical RBAC isolation. The Mission Control dashboard provides comprehensive oversight over the Service Finder ecosystem through role-based access control, ensuring each user only sees data and functionality relevant to their geographical scope and permissions level.

🎯 Core Concept: Modular Launchpad

The admin interface centers around a customizable "Launchpad" home screen with modular tiles that provide at-a-glance insights and quick access to key functions. The Launchpad adapts dynamically based on user role and geographical scope.

🧩 Launchpad Tiles (Role-based Visibility):

1. AI Logs Monitor - Real-time tracking of AI robot pipelines (GB Discovery, GB Hunter, VIES Validator, OSM Enricher)
2. Financial Dashboard - Revenue, expenses, ROI metrics with geographical filtering
3. Salesperson Hub - Performance metrics, leads, conversions for sales teams
4. User Management - Active users, registration trends, moderation queue
5. Service Moderation Map - Geographical view of pending/flagged services
6. Gamification Control - XP levels, badges, penalty system administration
7. System Health - API status, database metrics, uptime monitoring

👥 Role-Based Access Control (RBAC) - Geographical Isolation

Földrajzi izoláció kötelező! - Each role has strictly defined geographical boundaries.

1. Superadmin (Global Scope)

• Geographical Scope: Worldwide (no restrictions)
• Permissions: Full system access, all modules, all geographical regions
• Launchpad Tiles: All tiles visible and functional
• Critical Function: Can assign regional admins, override geographical restrictions

2. Admin (Területi Mindentudó / Regional Omniscient)

• Geographical Scope: Assigned region(s) (country/state/province level)
• Permissions: Full access within assigned region(s), cannot cross regional boundaries
• Launchpad Tiles: All tiles filtered to show only data from assigned region(s)
• Critical Function: Manages moderators and salespeople within region

3. Moderator (Területi Felügyelő / Regional Supervisor)

• Geographical Scope: Assigned sub-region(s) (city/district level)
• Permissions:
  • Service moderation within assigned sub-region(s)
  • User management for users registered in assigned sub-region(s)
  • Access to regional map view (only assigned area)
• Launchpad Tiles: Service Map, User Management, AI Logs (filtered)
• Restrictions: Cannot access financial data or salesperson metrics

4. Salesperson (Értékesítő)

• Geographical Scope: Assigned sales territory (may cross multiple sub-regions)
• Permissions:
  • View sales metrics and leads for assigned territory
  • Access customer profiles within territory
  • Limited service viewing (for sales context)
• Launchpad Tiles: Salesperson Hub, Customer Profiles, Service Map (read-only)
• Restrictions: Cannot moderate services or manage users

🎫 Development Tickets (Gitea Issues)

Ticket 1: RBAC Implementation & Role Management System

Scope: Backend/Frontend Core, Authentication, Authorization Complexity: High

Requirements:

1. Role & Scope Database Model

   • Extend existing User model with role_id and geographical_scope fields
   • Hierarchical scope system: Global → Country → Region → City
   • Scope inheritance (Admin sees all subordinate Moderator areas)

2. Authentication Middleware

   • JWT token enhancement with role and scope claims
   • Route-level permission validation
   • Geographical boundary enforcement on all API calls

3. Role Management UI

   • Admin interface for assigning roles and geographical scopes
   • Visual geographical selector (map-based or hierarchical tree)
   • Role permission matrix editor

4. Launchpad Tile Visibility Rules

   • Dynamic tile filtering based on role and scope
   • API endpoint for fetching role-appropriate tiles
   • Client-side tile visibility toggles

Ticket 2: Launchpad UI & Modular Tile System

Scope: Frontend Core, UI/UX, Component Library Complexity: Medium-High

Requirements:

1. Launchpad Grid Layout

   • Responsive drag-and-drop tile grid (like Windows Start menu)
   • Tile customization: size (1x1, 2x1, 2x2), position, visibility
   • Per-user tile arrangement persistence

2. Tile Component Framework

   • Base tile component with standardized header, content, actions
   • Tile types: Metric cards, charts, data tables, action buttons
   • Live data refresh with configurable intervals

3. Core Tile Implementations

   • AI Logs Monitor: Real-time pipeline status with progress bars
   • Financial Dashboard: Revenue charts, expense breakdown, ROI calculator
   • Salesperson Hub: Lead pipeline, conversion rates, performance metrics
   • User Management: Active users table, registration trends graph

4. Tile Configuration & Personalization

   • "Add Tile" modal with available tile catalog
   • Tile settings (data source, refresh rate, display options)
   • Role-based tile availability restrictions

Ticket 3: Geographical Map View with Scope Isolation

Scope: Frontend Mapping, Geographical Visualization Complexity: High

Requirements:

1. Map Integration with Scope Boundaries

   • Leaflet/Vue3-leaflet with OpenStreetMap/Mapbox tiles
   • Visual overlay of user's geographical scope (highlighted regions)
   • Automatic map centering and zoom to scope boundaries

2. Scope-Aware Data Filtering

   • Services, users, sales data filtered by geographical scope
   • Multi-level scope hierarchy support (country → region → city)
   • "Scope drill-down" ability for Admins (view all subordinate areas)

3. Service Moderation Map (Moderator View)

   • Service markers color-coded by status within assigned sub-region
   • Right-click context menu for moderation actions
   • Bulk selection and status updates

4. Sales Territory Visualization (Salesperson View)

   • Territory boundaries overlay on map
   • Customer location markers with sales metrics tooltips
   • Heatmap of lead density within territory

Ticket 4: User Management Interface with Geographical Filtering

Scope: Frontend User Administration, Data Tables Complexity: Medium

Requirements:

1. Geographically Filtered User Tables

   • User list automatically filtered by administrator's scope
   • Scope selector for Admins to switch between regions
   • Visual indication of current scope filter

2. Role Assignment Interface

   • Drag-and-drop role assignment with geographical scope picker
   • Bulk user role updates
   • Role change history and audit trail

3. User Detail View with Scope Context

   • Complete user profile with geographical registration data
   • Activity history filtered by scope
   • "Impersonate user" function for Superadmins (with scope limitations)

4. Moderation Queue for Moderators

   • Pending user approvals for assigned sub-region
   • Flagged user reviews with geographical context
   • Quick action buttons (approve, reject, require more info)

Ticket 5: AI Pipeline & Financial Monitoring Dashboards

Scope: Frontend Monitoring, Real-time Data, Charts Complexity: Medium

Requirements:

1. AI Pipeline Monitor with Scope Filtering

   • Real-time status of AI robots (GB Discovery, GB Hunter, etc.)
   • Progress bars, success/failure rates, last run timestamps
   • Geographical filtering of pipeline results (which regions were processed)

2. Financial Dashboard with RBAC Restrictions

   • Revenue/expense charts filtered by geographical scope
   • Role-based data granularity (Superadmin sees all, Admin sees region, etc.)
   • Export financial reports with automatic scope filtering

3. Sales Performance Metrics

   • Salesperson performance compared to territory averages
   • Lead conversion rates with geographical trends
   • Commission calculations and payout projections

4. System Health & Audit Logs

   • API response times, error rates, uptime metrics
   • Audit log viewer with role-based filtering
   • Geographical distribution of system usage

🛠️ Technology Stack

• Framework: Nuxt 3 (SSR/SPA hybrid) or Vue 3 with Vite
• UI Library: Vuetify 3 (Material Design) for consistency with existing design system
• State Management: Pinia with role/scope persistence
• Mapping: Leaflet with Vue3-leaflet wrapper
• Charts: Chart.js with Vue-chartjs wrapper
• HTTP Client: Axios with interceptors for scope headers
• Authentication: JWT tokens with role/scope claims
• Form Validation: Vee-Validate with Zod schemas
• Internationalization: Nuxt i18n (hu/en)
• Build Tool: Vite
• Package Manager: npm

🎨 Design Requirements

• Design System: Material Design 3 with Service Finder brand colors
• Color Coding by Role: Superadmin (purple), Admin (blue), Moderator (green), Salesperson (orange)
• Geographical Visualizations: Clear boundary indications, scope-aware color schemes
• Accessibility: WCAG 2.1 AA compliant, screen reader support for all tiles
• Responsive: Mobile-first, with Launchpad adapting to tablet/desktop layouts

🔧 Technical Specifications

• Code Quality: TypeScript strict mode, ESLint, Prettier
• Testing: Vitest for unit tests, Cypress for E2E with role-based test scenarios
• Performance: Lazy loading of tile components, virtual scrolling for data tables
• Security: Role validation on both client and server, scope injection prevention
• Browser Support: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+

📊 Success Metrics

• Page load time < 2 seconds with role/scope determination
• Tile loading < 1 second after initial page load
• Geographical filtering response time < 500ms
• Lighthouse score > 90
• Zero role escalation or scope bypass vulnerabilities

🔗 Dependencies

• Backend: Completed RBAC API endpoints with geographical scope support
• APIs: Role management API, Geographical scope API, Tile data APIs
• External: OpenStreetMap tiles, Mapbox for enhanced visualizations
• Data: Geographical boundary datasets for countries/regions/cities

📅 Implementation Phases

1. Phase 1 (Week 1-3): RBAC foundation, authentication enhancements, role middleware
2. Phase 2 (Week 4-6): Launchpad UI framework, core tile components
3. Phase 3 (Week 7-8): Geographical map integration, scope visualization
4. Phase 4 (Week 9-10): User management, financial dashboards, polish
5. Phase 5 (Week 11-12): Testing, security audit, performance optimization

🚀 Deployment Strategy

• Development: Feature flags for role-based UI elements
• Staging: Test with realistic geographical data and role scenarios
• Production: Gradual rollout with role groups (Superadmins first, then Admins, etc.)

---

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.