Overview
Facades provide a clean abstraction layer between components and the underlying state management and services. They orchestrate complex workflows, manage side effects, and expose simple APIs for components to consume.Facade Pattern Benefits
Encapsulation
Hide complexity from components
Reusability
Share business logic across features
Testability
Easy to mock and test in isolation
Type Safety
Full TypeScript type inference
Available Facades
AuthFacade
Authentication workflows and token management
TripPlannerFacade
Trip planning and route calculation
TripPassengerFacade
Trip requests and passenger operations
TripActiveFacade
Active trip state and real-time updates
SessionsFacade
Session lifecycle management
UsersFacade
User registration and management
AuthFacade
Orchestrates authentication flows including login, logout, token refresh, and session restoration.Public API
Authenticates user and initializes session
- Calls
AuthService.login() - Stores tokens (secure storage for mobile, cookie for web)
- Fetches user profile with
AuthService.me() - Schedules automatic token refresh
- Returns user object on success
Logs out user and clears all session data
- Calls
AuthService.logoutWeb()orlogoutMobile() - Clears tokens from storage
- Resets AuthStore state
- Cancels auto-refresh timer
- Navigates to login page
Refreshes access token using refresh token or cookie
- Determines platform (mobile vs web)
- Calls
AuthService.refresh() - Updates tokens in store and storage
- Reschedules next auto-refresh
- Returns new access token
Attempts to restore session on app startup
- Loads session type from storage
- Retrieves stored refresh token (mobile) or cookie (web)
- Calls
refreshSession()to get new access token - Fetches user profile if refresh succeeds
- Returns true if session restored, false otherwise
Usage Example
src/app/features/auth/login/login.component.ts
Token Refresh Scheduling
AuthFacade automatically schedules token refresh 30 seconds before expiration:src/app/store/auth/auth.facade.ts
TripPlannerFacade
Manages trip planning workflow from destination search to fare estimation.Public API
Initializes trip planning with user’s current location
- Gets current GPS location
- Sets origin point in store
- Loads cached destination if available
- Recalculates route if both origin and destination exist
Searches for destinations using Mapbox Places API
- Calls
MapboxPlacesService.search() - Filters results within Santiago de Cuba bounds
- Returns array of place suggestions
Sets destination and calculates route
- Updates destination in store
- Calls
MapboxDirectionsService.getRoute() - Fetches fare estimate
- Caches for 24 hours
Recalculates route after user adjusts destination pin on map
- Performs reverse geocoding for new coordinates
- Updates route and fare estimate
- Updates store with new values
Clears trip planning state (soft reset, preserves origin)
Clears all trip planning state including origin
Usage Example
src/app/features/tabs/map/map.component.ts
TripPassengerFacade
Handles trip requests and real-time trip tracking for passengers.Public API
Creates a new trip request
- Validates origin, destination, and fare quote
- Calls backend API to create trip
- Starts real-time Socket.io connection
- Returns trip details
Cancels an active trip
- Calls backend cancellation API
- Disconnects Socket.io listeners
- Clears trip state
Subscribes to real-time trip events via Socket.io
- Listens to driver assignment events
- Tracks driver location updates
- Handles trip status changes
- Updates trip store reactively
SessionsFacade
Manages session lifecycle and device tracking.Public API
Fetches the current active session
Updates session type in store and storage
Lists all active sessions for the user
Error Handling
Facades handle errors gracefully and update store state:Best Practices
Observable APIs: Facades return Observables for async operations, allowing components to handle loading/error states reactively
Testing Facades
Facades are easy to test by mocking dependencies:TripActiveFacade
Provides read-only access to active trip state with computed selectors for UI consumption.Public API
Whether there is an active trip
Current trip phase (pending, assigning, accepted, arriving, in_progress, completed, cancelled)
Active trip ID
Driver information (name, rating, phone)
Vehicle information (plate, make, model, color, year)
Driver’s name or ’—’ if unavailable
Driver’s average rating
Vehicle plate number or ’—’
Formatted vehicle title (e.g., “Toyota Corolla · 2020”)
Estimated time of arrival in minutes
Live fare amount with waiting penalties
Total waiting time in seconds
Whether waiting penalty has been applied
Human-readable penalty message
Usage Example
src/app/features/tabs/trips/active/active.component.ts
src/app/store/trips/trip-active.facade.ts
UsersFacade
Handles user registration and management operations.Public API
Returns signal with all users in the store
Returns registration status including loading, error, and form errors
Registers a new user with credentials
- Validates and builds registration payload
- Calls
UserService.register() - Updates users store on success
- Shows success/error notifications
- Returns created user
Usage Example
src/app/features/auth/register/register.component.ts
src/app/store/users/users.facade.ts
Related Documentation
Stores
Signal-based state stores
Effects
Side effect management
Services
HTTP and WebSocket services
State Management
Architecture overview