Quick Start

This guide will help you get the Rodando Passenger app running on your local machine quickly. For more detailed setup instructions, see the Installation guide.

Prerequisites

Before you begin, ensure you have:

Node.js (v16 or higher recommended)
npm or yarn package manager
Ionic CLI installed globally
Git for cloning the repository

Install Ionic CLI

If you don’t have Ionic CLI installed, install it globally:

npm install -g @ionic/cli

Verify the installation:

ionic --version

Clone and Install Dependencies

Clone the repository and install all dependencies:

git clone <your-repo-url>
cd rodandoApp-frontend
npm install

This will install all dependencies from package.json, including:

Angular 18.2
Ionic 8.4
Capacitor 7.4
NgRx 18.1
Mapbox GL 3.15
Socket.io Client 4.8

Configure Environment

The app uses environment files for configuration. The default development configuration is in src/environments/environment.ts:

src/environments/environment.ts

export const environment = {
  production: false,
  apiUrl: 'http://10.0.2.2:3000/api',  // Backend REST API
  appAudience: 'passenger_app',
  expectedUserType: 'passenger',
  mapbox: {
    accessToken: 'YOUR_MAPBOX_TOKEN_HERE'
  },
  debug: true,
  debugTags: ['DA', 'HTTP', 'LOC', 'PL', 'PAX'],
  wsBase: 'ws://10.0.2.2:3000'  // WebSocket for real-time updates
};

The default apiUrl uses 10.0.2.2 which is the Android emulator’s alias for localhost. If running on iOS simulator or web browser, change this to http://localhost:3000/api.

Required Configuration

Mapbox Access Token: Replace YOUR_MAPBOX_TOKEN_HERE with your Mapbox token:

Create a free account at mapbox.com
Get your access token from your account page
Update environment.mapbox.accessToken

Backend API: Ensure your backend API is running and update apiUrl and wsBase if needed.

Run the Development Server

Start the Ionic development server:

ionic serve

Or use the Angular CLI directly:

npm start
# or
ng serve

The app will open automatically in your default browser at http://localhost:8100.

The ionic serve command provides live reload - any changes you make to the source code will automatically refresh the browser.

Run on Mobile Device/Emulator (Optional)

To run on a native mobile platform:

Android

ionic capacitor build android
ionic capacitor run android

iOS (macOS only)

ionic capacitor build ios
ionic capacitor open ios

Running on mobile devices requires additional setup. See the Installation guide for prerequisites like Android Studio or Xcode.

Verify the Installation

Once the app is running, you should see:

Login Screen - The authentication page at /auth/login
No Console Errors - Check browser DevTools for any configuration issues
Map Loading - If Mapbox is configured correctly, maps should render properly

Test Authentication

The app uses a dual authentication flow:

Mobile Session: Stores refresh token in device secure storage
Web Session: Uses HTTP-only cookies for token management

When running in browser (ionic serve), the app defaults to web session mode.

You’ll need valid credentials from your backend API to log in. The app expects a passenger user type and will validate against the passenger_app audience.

Project Structure Overview

rodandoApp-frontend/
├── src/
│   ├── app/
│   │   ├── core/
│   │   │   ├── services/        # HTTP, WebSocket, Storage services
│   │   │   ├── guards/          # Auth guards with refresh logic
│   │   │   ├── interceptors/    # HTTP interceptors
│   │   │   └── models/          # TypeScript interfaces
│   │   ├── store/               # NgRx state management
│   │   │   ├── auth/            # Auth state (login, tokens)
│   │   │   ├── trips/           # Trip state (planner, passenger)
│   │   │   ├── users/           # User profile state
│   │   │   └── sessions/        # Session type management
│   │   ├── features/
│   │   │   ├── auth/            # Login/register pages
│   │   │   ├── tabs/            # Main tab pages (home, map, trips, profile)
│   │   │   └── sidebar/         # Sidebar navigation pages
│   │   ├── shared/
│   │   │   ├── layouts/         # DefaultLayout, MapLayout
│   │   │   └── components/      # Reusable UI components
│   │   └── app.routes.ts        # App routing configuration
│   ├── environments/            # Environment configs
│   └── theme/                   # Ionic theming and variables
├── capacitor.config.ts          # Capacitor native config
├── angular.json                 # Angular CLI configuration
├── ionic.config.json            # Ionic project config
└── package.json                 # Dependencies

Development Scripts

The following npm scripts are available:

Command	Description
`npm start`	Start development server (same as `ng serve`)
`npm run build`	Build production bundle
`npm test`	Run unit tests with Karma
`npm run lint`	Run ESLint on TypeScript and HTML files
`npm run watch`	Build in watch mode for development

The project uses @ionic/angular-toolkit which provides additional Ionic-specific build optimizations and schematics.

Common Development Tasks

Adding a New Page

ionic generate page features/my-feature/my-page

This creates a standalone component with routing configured.

Adding a Service

ionic generate service core/services/my-service

Using Path Aliases

The project has @/* configured as an alias for src/*:

// Instead of:
import { AuthService } from '../../../core/services/http/auth.service';

// Use:
import { AuthService } from '@/app/core/services/http/auth.service';

Troubleshooting

Port Already in Use

If port 8100 is already in use:

ionic serve --port 8101

Mapbox Not Loading

Check:

Your Mapbox access token is valid
The token is correctly set in environment.ts
Check browser console for CORS or API errors

WebSocket Connection Failed

Ensure:

Your backend WebSocket server is running at the configured wsBase URL
The URL uses ws:// (not wss://) for local development
Check that the backend is accessible from your device/emulator

Android Emulator Cannot Reach localhost

The Android emulator uses 10.0.2.2 to access the host machine’s localhost. If your backend is on localhost:3000, the emulator should use:

apiUrl: 'http://10.0.2.2:3000/api'
wsBase: 'ws://10.0.2.2:3000'

For iOS simulator, use http://localhost:3000/api instead.

Next Steps

Now that you have the app running:

Full Installation Guide

Detailed setup with platform-specific requirements

Authentication

Learn about login flow and session management

Trip Booking

Understand how passengers request rides

State Management

Explore NgRx Signals architecture

Get Started

Core Features

Architecture

Development

Prerequisites

Required Configuration

Android

iOS (macOS only)

Verify the Installation

Test Authentication

Project Structure Overview

Development Scripts

Common Development Tasks

Adding a New Page

Adding a Service

Using Path Aliases

Troubleshooting

Port Already in Use

Mapbox Not Loading

WebSocket Connection Failed

Android Emulator Cannot Reach localhost

Next Steps

Full Installation Guide

Authentication

Trip Booking

State Management

Additional Resources

Build docs developers (and LLMs) love

Get Started

Core Features

Architecture

Development

​Prerequisites

​Required Configuration

​Android

​iOS (macOS only)

​Verify the Installation

​Test Authentication

​Project Structure Overview

​Development Scripts

​Common Development Tasks

​Adding a New Page

​Adding a Service

​Using Path Aliases

​Troubleshooting

​Port Already in Use

​Mapbox Not Loading

​WebSocket Connection Failed

​Android Emulator Cannot Reach localhost

​Next Steps

Full Installation Guide

Authentication

Trip Booking

State Management

​Additional Resources

Build docs developers (and LLMs) love

Prerequisites

Required Configuration

Android

iOS (macOS only)

Verify the Installation

Test Authentication

Project Structure Overview

Development Scripts

Common Development Tasks

Adding a New Page

Adding a Service

Using Path Aliases

Troubleshooting

Port Already in Use

Mapbox Not Loading

WebSocket Connection Failed

Android Emulator Cannot Reach localhost

Next Steps

Additional Resources