Folder Structure

Understanding the organization and architecture of the WI-CARPOOL frontend codebase

Project Overview

WI-CARPOOL follows a modular React application structure with clear separation of concerns. The project is organized to promote maintainability, scalability, and developer productivity.

Root Directory Structure

wi-carpool-frontend/
├── public/                 # Static assets and PWA configuration
├── src/                   # Source code
├── package.json           # Dependencies and scripts
├── vite.config.ts        # Vite build configuration
├── tailwind.config.ts    # Tailwind CSS configuration
├── tsconfig.json         # TypeScript configuration
└── README.md             # Project documentation

Public Directory

The public/ directory contains static assets that are served directly by the web server.

Public Directory Structure

public/
├── documentation/        # Complete HTML documentation
│   ├── index.html       # Documentation homepage
│   ├── styles.css       # Documentation styles
│   └── script.js        # Documentation functionality
├── images/              # Static images
│   ├── home.png        # Homepage hero image
│   ├── happy.jpg       # Success/verification image
│   └── verify.svg      # Verification icons
├── icon-192.png        # PWA icon (192x192)
├── icon-512.png        # PWA icon (512x512)
├── manifest.json       # PWA manifest
├── sw.js              # Service worker for PWA
├── robots.txt         # Search engine crawler instructions
└── favicon.ico        # Browser favicon

Source Directory Structure

The src/ directory contains all the application source code, organized by functionality and purpose.

Main Source Structure

src/
├── api/                  # API integration layer
├── components/           # Reusable React components
├── contexts/            # React context providers
├── data/               # Static data and mock data
├── hooks/              # Custom React hooks
├── lib/                # Utility libraries
├── pages/              # Page components and routing
├── styles/             # Global styles and CSS modules
├── translations/       # Internationalization files
├── types/              # TypeScript type definitions
├── utils/              # Utility functions
├── App.tsx             # Main application component
├── main.tsx            # Application entry point
└── index.css           # Global CSS styles

API Layer

The API layer handles all communication with the Laravel backend through axios.

API Directory Structure

src/api/
├── services/            # API service modules
│   ├── authService.ts   # Authentication API calls
│   ├── rideService.ts   # Ride-related API calls
│   ├── profileService.ts # User profile API calls
│   ├── paymentService.ts # Payment API calls
│   ├── chatService.ts   # Messaging API calls
│   ├── driverService.ts # Driver-specific API calls
│   ├── commonService.ts # Common/shared API calls
│   ├── ratingService.ts # Rating and feedback API calls
│   ├── walletService.ts # Wallet and transaction API calls
│   └── preferencesService.ts # User preferences API calls
├── axiosInstance.ts     # Configured axios instance
├── constants.ts         # API endpoints and configuration
└── index.ts            # API layer exports

Components Structure

Components are organized by functionality and include both UI components and feature-specific components.

Components Directory

src/components/
├── ui/                  # Reusable UI components (shadcn/ui)
│   ├── button.tsx       # Button component
│   ├── card.tsx         # Card component
│   ├── dialog.tsx       # Dialog/modal component
│   ├── form.tsx         # Form components
│   ├── input.tsx        # Input component
│   ├── toast.tsx        # Toast notification component
│   └── ...              # Other UI components
├── auth/                # Authentication components
│   ├── SignInCard.tsx   # Sign-in form
│   ├── SignUpCard.tsx   # Sign-up form
│   ├── PhoneLoginForm.tsx # Phone number login
│   ├── SocialLoginButtons.tsx # Social media login
│   └── UserTypeToggle.tsx # Driver/Passenger toggle
├── dashboard/           # Dashboard components
│   ├── DashboardLayout.tsx # Dashboard layout wrapper
│   ├── DashboardSidebar.tsx # Dashboard navigation
│   ├── DashboardCard.tsx # Dashboard metric cards
│   └── StatsCard.tsx    # Statistics display
├── passenger/           # Passenger-specific components
│   ├── RidesList.tsx    # List of available rides
│   └── SearchRideForm.tsx # Ride search form
├── driver/              # Driver-specific components
│   └── WithdrawFundsDialog.tsx # Fund withdrawal
├── chat/                # Messaging components
│   └── MessageStatus.tsx # Message status indicators
├── places/              # Location and places components
│   ├── SuggestionItem.tsx # Place suggestion item
│   └── SuggestionsList.tsx # Places autocomplete
├── profile/             # Profile management
│   └── PreferencesEditor.tsx # User preferences
├── CountryCodePicker.tsx # Country code selection
├── CurrencySelector.tsx # Currency selection
├── LanguageSelector.tsx # Language switcher
├── PlacesAutocomplete.tsx # Google Places integration
├── RideCard.tsx         # Individual ride display
├── SearchForm.tsx       # Main search form
├── Navbar.tsx           # Navigation bar
├── Footer.tsx           # Page footer
├── ProtectedRoute.tsx   # Route protection
├── PWAInstallButton.tsx # PWA installation
└── RoleSwitcher.tsx     # Driver/Passenger role toggle

Pages Structure

Pages represent different routes in the application, organized by user type and functionality.

Pages Directory

src/pages/
├── driver/              # Driver dashboard pages
│   ├── Dashboard.tsx    # Driver dashboard
│   ├── PostRide.tsx     # Create new ride
│   ├── ManageBookings.tsx # Manage bookings
│   ├── Earnings.tsx     # Earnings and payouts
│   ├── Vehicle.tsx      # Vehicle management
│   ├── VehicleList.tsx  # List of vehicles
│   ├── AddVehicle.tsx   # Add new vehicle
│   ├── EditVehicle.tsx  # Edit vehicle details
│   ├── TripDetail.tsx   # Trip details
│   ├── TripTracker.tsx  # Live trip tracking
│   ├── Messages.tsx     # Driver messages
│   ├── Chat.tsx         # Individual chat
│   ├── Inbox.tsx        # Message inbox
│   ├── Ratings.tsx      # Driver ratings
│   ├── Wallet.tsx       # Driver wallet
│   ├── Transactions.tsx # Transaction history
│   └── Notifications.tsx # Driver notifications
├── passenger/           # Passenger dashboard pages
│   ├── Dashboard.tsx    # Passenger dashboard
│   ├── FindRide.tsx     # Search for rides
│   ├── UpcomingRides.tsx # Upcoming bookings
│   ├── TripDetail.tsx   # Trip details
│   ├── Messages.tsx     # Passenger messages
│   ├── Chat.tsx         # Individual chat
│   ├── Ratings.tsx      # Passenger ratings
│   ├── Wallet.tsx       # Passenger wallet
│   ├── Favorites.tsx    # Favorite routes
│   ├── AddVehicle.tsx   # Add passenger vehicle
│   └── Notifications.tsx # Passenger notifications
├── Index.tsx            # Homepage
├── SignIn.tsx           # Sign-in page
├── SignUp.tsx           # Sign-up page
├── ForgotPassword.tsx   # Password reset
├── Search.tsx           # Ride search
├── SearchResults.tsx    # Search results
├── SearchCarResults.tsx # Car search results
├── RideDetail.tsx       # Ride detail view
├── OfferRide.tsx        # Offer a ride
├── Profile.tsx          # User profile
├── UserProfile.tsx      # Profile management
├── MyTickets.tsx        # User tickets
├── About.tsx            # About page
├── HowItWorks.tsx       # How it works
├── Safety.tsx           # Safety information
├── ContactUs.tsx        # Contact form
├── Support.tsx          # Support center
├── HelpCenter.tsx       # Help center
├── Terms.tsx            # Terms of service
├── Privacy.tsx          # Privacy policy
├── Cookies.tsx          # Cookie policy
├── Careers.tsx          # Careers page
├── Press.tsx            # Press releases
├── Membership.tsx       # Membership info
├── Sitemap.tsx          # Site map
└── NotFound.tsx         # 404 error page

Context and State Management

React contexts provide global state management for authentication, language, and currency.

Contexts Directory

src/contexts/
├── auth/                # Authentication context
│   ├── AuthContext.tsx  # Auth context definition
│   ├── AuthProvider.tsx # Auth state provider
│   ├── useAuth.tsx      # Auth hook
│   ├── types.ts         # Auth type definitions
│   ├── utils.ts         # Auth utilities
│   └── index.ts         # Auth exports
├── AuthContext.tsx      # Legacy auth context (compatibility)
├── LanguageContext.tsx  # Language/i18n context
└── CurrencyContext.tsx  # Currency context

Hooks and Utilities

Custom hooks and utility functions provide reusable functionality across the application.

Hooks Directory

src/hooks/
├── useTranslation.tsx   # Translation hook
├── useRideSearch.tsx    # Ride search functionality
├── useUserVehicles.ts   # User vehicle management
├── usePlaceSuggestions.ts # Google Places integration
├── useGoogleMapsLoader.ts # Google Maps loading
├── use-toast.ts         # Toast notifications
└── use-mobile.tsx       # Mobile device detection

Utils Directory

src/utils/
├── loadGoogleMapsAPI.ts # Google Maps API loader
└── pwa.ts              # PWA utilities

Lib Directory

src/lib/
└── utils.ts            # General utility functions

Internationalization

Translation files support multiple languages for the application.

Translations Directory

src/translations/
├── en.ts               # English translations
├── es.ts               # Spanish translations
├── fr.ts               # French translations
├── ar.ts               # Arabic translations
├── hi.ts               # Hindi translations
├── pt.ts               # Portuguese translations
├── ru.ts               # Russian translations
├── nl.ts               # Dutch translations
├── af.ts               # Afrikaans translations
└── index.ts            # Translation exports

Styling and Themes

Styling is handled through Tailwind CSS with custom styles and theme configuration.

Styles Directory

src/styles/
└── scrollbar-hide.css  # Custom scrollbar styles

Main Style Files

src/
├── index.css           # Global CSS and Tailwind imports
└── App.css            # Application-specific styles

Type Definitions

TypeScript type definitions ensure type safety throughout the application.

Types Directory

src/types/
└── google-maps.d.ts    # Google Maps type definitions

Configuration Type Files

src/
├── vite-env.d.ts       # Vite environment types
├── tsconfig.json       # TypeScript configuration
├── tsconfig.app.json   # App-specific TypeScript config
└── tsconfig.node.json  # Node.js TypeScript config

Configuration Files

Various configuration files control the build process, styling, and development environment.

Root Configuration Files

├── vite.config.ts       # Vite build configuration
├── tailwind.config.ts   # Tailwind CSS configuration
├── postcss.config.js    # PostCSS configuration
├── components.json      # shadcn/ui component configuration
├── eslint.config.js     # ESLint configuration
├── package.json         # Dependencies and scripts
├── package-lock.json    # Dependency lock file
└── bun.lockb           # Bun package manager lock file

Key Architectural Patterns

🏗️ Component-Based Architecture

Modular components promote reusability and maintainability across the application.

🔄 Service Layer Pattern

API services abstract backend communication and provide consistent interfaces.

🎯 Context Pattern

React contexts manage global state for authentication, language, and currency.

🪝 Custom Hooks Pattern

Reusable hooks encapsulate complex logic and state management.

📱 PWA Architecture

Progressive Web App features provide native-like experience across devices.

🌍 i18n Architecture

Internationalization support enables multi-language functionality.

Development Guidelines

File Naming Conventions

  • Components: PascalCase (e.g., RideCard.tsx)
  • Pages: PascalCase (e.g., Dashboard.tsx)
  • Hooks: camelCase with "use" prefix (e.g., useAuth.tsx)
  • Services: camelCase with "Service" suffix (e.g., authService.ts)
  • Utils: camelCase (e.g., utils.ts)
  • Types: camelCase with descriptive names (e.g., google-maps.d.ts)

Import Organization

  1. React and React-related imports
  2. Third-party library imports
  3. Internal API and service imports
  4. Component imports
  5. Utility and type imports
  6. Relative imports (./)

Component Organization

  • Keep components focused and single-purpose
  • Use composition over inheritance
  • Prefer functional components with hooks
  • Extract reusable logic into custom hooks
  • Use TypeScript for type safety