Skip to main content

Mobile App Design Specification

Source: Claude Opus Design Document Date: October 15, 2025 Status: Complete - Ready for Implementation

Overview​

This is a comprehensive technical specification and design document for the Vanroute React Native mobile application. The design was created by Claude Opus and provides detailed UI/UX specifications, component layouts, and implementation guidelines.

Full Design Document Location: /MOBILE_APP_DESIGN_SPEC.md (in project root)

Key Design Elements​

Technology Stack​

  • Framework: React Native with Expo
  • UI Library: React Native Paper (Material Design)
  • Navigation: React Navigation (Bottom Tabs + Stack)
  • Maps: React Native Maps
  • State Management: React Context API / Redux Toolkit
  • Backend: Supabase (already implemented!)
  • Database: PostgreSQL with PostGIS (already built!)

Color Palette​

Primary Colors:

  • Primary: #2E7D32 (Forest Green)
  • Primary Light: #4CAF50
  • Primary Dark: #1B5E20

Semantic Colors:

  • Danger: #D32F2F (Critical warnings)
  • Warning: #F57C00 (Cautions)
  • Success: #388E3C (Clear routes)
  • Info: #1976D2 (Informational)

Neutral Colors:

  • Background: #F5F5F5
  • Surface: #FFFFFF
  • Text Primary: #212121
  • Text Secondary: #666666
App
├── Auth Stack (Login, Register, Onboarding)
└── Main Tabs
    ├── Map Tab
    ├── Route Tab (Stack: Planning, Results, Navigation)
    ├── Hazards Tab (Stack: List, Detail, Report, Verify)
    ├── Saved Tab
    └── Profile Tab (Stack: Main, Vehicles, Settings)

Screen Specifications​

1. Map Screen (Home)​

  • Full-screen map view
  • Search bar at top
  • Filter chips for hazard types
  • Hazard markers (clustered)
  • Bottom sheet for hazard summary
  • Current location tracking

Key Features:

  • Display OSM hazards from our database
  • Real-time user location
  • Filter by hazard type (height, weight, width, etc.)
  • Tap marker to see details

2. Route Planning Screen​

  • Origin/destination input with autocomplete
  • Vehicle selector (from user's vehicles)
  • Route preferences toggles
  • Add waypoints functionality
  • Calculate route button

Integration with Our Database:

  • Uses route_segments table for routing
  • Checks road_hazards for restrictions
  • Queries road_elevations for grades
  • Finds amenities along route

3. Route Results Screen​

  • Recommended route display
  • Hazard warnings timeline
  • Fuel stop recommendations
  • Elevation profile
  • Alternative routes
  • Start navigation button

Data Sources:

  • Hazards from road_hazards
  • Grades from road_elevations
  • Fuel from amenities (category: fuel_station)
  • Rest areas from rest_areas

4. Active Navigation Screen​

  • Full-screen map with route
  • Turn-by-turn directions
  • Hazard alerts (distance-based)
  • Real-time position tracking
  • Detour calculation

5. Report Hazard Screen​

  • Hazard type selection (icons)
  • Location picker (GPS + manual)
  • Measurement inputs
  • Photo upload
  • Description field
  • Submit button

Database Integration:

  • Inserts into user_reported_hazards
  • Photos uploaded to Supabase Storage
  • Status starts as 'pending'

6. Vehicle Management​

  • List user vehicles
  • Add/edit/delete vehicles
  • Set default vehicle
  • Vehicle specifications input
  • Vehicle type icons

Database Integration:

  • CRUD operations on vehicles table
  • Linked to user account

7. Profile & Settings​

  • User info display
  • Contribution stats
  • Saved routes list
  • Downloaded maps
  • Notification settings
  • Subscription management

Component Library​

Common Components​

  • Button - Styled Material Design buttons
  • Card - Container with elevation
  • Input - Text input with validation
  • SearchBar - Autocomplete search
  • LoadingSpinner - Activity indicator
  • ErrorMessage - Error display

Map Components​

  • MapView - Wrapper for React Native Maps
  • HazardMarker - Custom marker with clustering
  • RoutePolyline - Route line overlay
  • UserLocation - Current position marker
  • MapControls - Zoom, compass, center buttons

Hazard Components​

  • HazardCard - List item with hazard info
  • HazardList - Virtualized list
  • HazardForm - Report hazard form
  • HazardDetails - Full details view
  • VerificationForm - Verify hazard

Route Components​

  • RouteCard - Saved route item
  • RouteTimeline - Hazards along route
  • WaypointInput - Add waypoint
  • RoutePreferences - Settings toggles

Vehicle Components​

  • VehicleCard - Vehicle list item
  • VehicleForm - Add/edit vehicle
  • VehicleSelector - Choose vehicle
  • VehicleSpecs - Display specifications

Data Integration​

Our Advantage Over Design Doc​

The original design doc assumed basic user-reported data. We have much more:

FeatureDesign DocOur Implementation
HazardsUser-reported only57,742 OSM + user-reported
RoutesBasic polylines420,083 detailed segments
ElevationNot included2.97M elevation profiles
AmenitiesNot included56,588 fuel/rest/facilities
TownsNot included8,142 with boundaries

API Integration Examples​

Get Hazards:

const { data, error } = await supabase
  .from('road_hazards')
  .select('*')
  .gte('latitude', bounds.south)
  .lte('latitude', bounds.north);

Calculate Route:

const { data, error } = await supabase.rpc('calculate_safe_route', {
  origin_lat: -33.8688,
  origin_lng: 151.2093,
  dest_lat: -28.6474,
  dest_lng: 153.6020,
  vehicle_height: 3.2,
  vehicle_weight: 3.5
});

Typography​

Text Styles​

  • H1: 32px, Bold
  • H2: 24px, Bold
  • H3: 20px, Semibold
  • Body1: 16px, Regular
  • Body2: 14px, Regular
  • Caption: 12px, Regular
  • Button: 14px, Semibold, Uppercase

Spacing​

  • XS: 4px
  • SM: 8px
  • MD: 16px (default)
  • LG: 24px
  • XL: 32px
  • XXL: 48px

Monetization​

Subscription Tiers​

Free:

  • View hazards on map
  • Basic route planning (3/day)
  • Report hazards
  • One vehicle profile

Premium ($4.99/month or $29.99/year):

  • Unlimited route planning
  • Unlimited vehicles
  • Offline maps
  • Advanced hazard alerts
  • Weather integration
  • Priority support
  • No ads

Implementation Guide​

See the Integration Plan for detailed implementation steps connecting this design to our existing database.

Resources​

Full Design Document: /MOBILE_APP_DESIGN_SPEC.md Integration Plan: integration-plan.md Database Docs: ../../database/overview.md

Next Steps:

  1. Review full design specification
  2. Set up Expo project structure
  3. Implement UI components following design
  4. Connect to existing Supabase database
  5. Test with real hazard data