Database Design
Understanding the data structures and relationships in the WI-CARPOOL system backend
Frontend Data Flow
The frontend application manages data through several layers:
🔌 API Services
Axios-based services handle all communication with the Laravel backend API endpoints.
⚡ React Query
TanStack React Query manages server state, caching, and synchronization.
🗂️ Local Storage
Client-side persistence for user sessions, preferences, and cached data.
⚛️ React Context
Global state management for authentication, language, and currency settings.
Data Entities Overview
Based on the API endpoints and frontend implementation, the system works with these main data entities:
User Management
- Users - Driver and passenger profiles
- Authentication - JWT tokens and sessions
- User Preferences - Language, currency, settings
- User Locations - Saved addresses and places
Ride Management
- Rides - Offered rides by drivers
- Bookings - Passenger ride bookings
- Trip Details - Complete trip information
- Ride Alerts - Passenger ride requests
Vehicle Management
- Vehicles - Driver vehicle information
- Vehicle Types - Car categories and descriptions
- Vehicle Documents - Registration and insurance
Financial Data
- Payments - Transaction records
- Wallets - User account balances
- Earnings - Driver revenue tracking
- Payouts - Driver withdrawal records
Communication
- Conversations - Chat sessions
- Messages - Individual chat messages
- Notifications - System notifications
System Data
- Countries - Supported countries
- Currencies - Supported currencies
- Languages - Supported languages
- Companies - Organization data
API Response Structures
The frontend expects consistent API response formats from the Laravel backend:
Standard API Response Format
// Successful Response
{
"status_code": "1", // "1" indicates success
"status_message": "Success",
"data": {
// Response data object
}
}
// Error Response
{
"status_code": "0", // "0" indicates error
"status_message": "Error message",
"data": null
}Frontend Data Models
The frontend works with these data structures based on API responses:
User Data Structure
// User object from authentication
interface User {
id: number;
name: string;
email: string;
phone_number: string;
user_type: 'driver' | 'passenger';
profile_picture?: string;
is_verified: boolean;
token: string; // JWT token
access_token: string; // Alternative token field
currency_code: string;
language_code: string;
country_code: string;
}Ride Data Structure
// Ride object for offered rides
interface Ride {
id: number;
driver_id: number;
from_location: string;
to_location: string;
departure_time: string;
arrival_time: string;
available_seats: number;
price_per_seat: number;
currency: string;
vehicle_id: number;
status: 'active' | 'completed' | 'cancelled';
created_at: string;
updated_at: string;
}Booking Data Structure
// Booking object for passenger bookings
interface Booking {
id: number;
ride_id: number;
passenger_id: number;
seats_booked: number;
total_amount: number;
status: 'pending' | 'confirmed' | 'completed' | 'cancelled';
booking_time: string;
payment_status: 'pending' | 'completed' | 'failed';
}Vehicle Data Structure
// Vehicle object for driver vehicles
interface Vehicle {
id: number;
driver_id: number;
make: string;
model: string;
year: number;
color: string;
license_plate: string;
vehicle_type: string;
seats: number;
is_default: boolean;
documents: VehicleDocument[];
}Client-Side Data Management
Local Storage Structure
The frontend stores certain data locally for persistence:
Local Storage Keys
// Key-value pairs stored in localStorage
{
"user": "{...}", // Serialized user object with token
"language": "en", // Selected language code
"currency": "USD", // Selected currency code
"theme": "light", // UI theme preference
"ride_preferences": "{...}", // User ride preferences
"recent_searches": "[...]", // Recent location searches
}React Query Cache
Server state is managed through React Query with these query keys:
Query Key Patterns
// Query keys used throughout the application
queryKey: ['user', 'profile'] // User profile data
queryKey: ['rides', 'driver', userId] // Driver's rides
queryKey: ['rides', 'passenger', userId] // Passenger's bookings
queryKey: ['vehicles', userId] // User's vehicles
queryKey: ['messages', conversationId] // Chat messages
queryKey: ['wallet', userId] // Wallet information
queryKey: ['countries'] // Available countries
queryKey: ['currencies'] // Available currencies
queryKey: ['languages'] // Available languagesData Synchronization
🔄 Real-time Updates
React Query automatically refetches data when the window regains focus or comes back online.
📦 Optimistic Updates
UI updates immediately while API calls are in progress, with rollback on failure.
⚡ Background Sync
Data is refetched in the background to keep the UI fresh without user intervention.
💾 Offline Support
Cached data remains available when offline, with automatic sync when connection returns.
API Endpoint Categories
The frontend interacts with these categories of API endpoints:
| Category | Purpose | Key Endpoints | Data Flow |
|---|---|---|---|
| Authentication | User login/registration | /register, /login, /logout | Bidirectional |
| User Management | Profile and preferences | /get_rider_profile, /update_rider_profile | Bidirectional |
| Ride Management | Ride creation and booking | /add_ride, /book_ride, /search_rides | Bidirectional |
| Vehicle Management | Vehicle CRUD operations | /vehicle_details, /update_vehicle | Bidirectional |
| Payment System | Financial transactions | /web_payment, /add_wallet | Bidirectional |
| Messaging | Real-time communication | /get_conversation_list, /send_message | Bidirectional |
| System Data | Reference data | /country_list, /currency_list | Read-only |
Data Validation
The frontend implements client-side validation using Zod schemas:
Example Validation Schema
// Zod schema for user registration
const registrationSchema = z.object({
name: z.string().min(2, "Name must be at least 2 characters"),
email: z.string().email("Invalid email address"),
phone_number: z.string().min(10, "Phone number must be valid"),
password: z.string().min(8, "Password must be at least 8 characters"),
user_type: z.enum(["driver", "passenger"]),
country_code: z.string(),
language_code: z.string(),
currency_code: z.string()
});Error Handling
The frontend handles various data-related errors:
Network Errors
- Connection Failures - Show offline indicators
- Timeout Errors - Retry mechanisms
- Server Errors - Graceful error messages
Data Validation Errors
- Form Validation - Real-time field validation
- API Validation - Server-side error display
- Type Errors - TypeScript compile-time checks
Authentication Errors
- Token Expiry - Automatic logout and redirect
- Permission Errors - Access denied messages
- Session Management - Secure token handling
Performance Considerations
📊 Data Pagination
Large datasets are paginated to improve performance and user experience.
🎯 Selective Loading
Only necessary data is fetched based on current user context and route.
💾 Intelligent Caching
React Query cache prevents unnecessary API calls and improves response times.
🔄 Background Updates
Critical data is updated in the background without disrupting user interaction.
Backend Integration Notes
Required Backend Features
- JWT Authentication - Token-based authentication system
- RESTful API Design - Consistent API endpoint structure
- CORS Configuration - Proper cross-origin request handling
- File Upload Support - Image and document upload capabilities
- Real-time Features - WebSocket or Pusher integration for live updates
- Payment Gateway Integration - Multiple payment method support
- Geolocation Services - Integration with mapping services