small-cactus/Fuel-Up

Fuel Up is an iOS-first fuel discovery app built with Expo and React Native. It combines a map-led home screen, live and historical price aggregation, trend views, predictive fueling onboarding, and native iOS surfaces such as widgets and Live Activities.

Quick Start

Prerequisites

Node.js 20+
npm
Xcode and iOS Simulator

Install dependencies

npm install

Launch the app in the iOS simulator

npm run ios:sim

Start Metro only

npm start

Environment

Fuel Up boots without committed credentials. Optional integrations are loaded from environment variables at runtime.

cp .env.example .env

Common variables:

Variable	Purpose
`EXPO_PUBLIC_SUPABASE_URL`	Supabase project URL for remote persistence and trend history
`EXPO_PUBLIC_SUPABASE_KEY`	Supabase publishable key
`EXPO_PUBLIC_PRIMARY_STATION_URL`	Dedicated station feed endpoint
`EXPO_PUBLIC_SECONDARY_STATION_URL`	Extended station feed endpoint
`EXPO_PUBLIC_TOMTOM_API_KEY`	TomTom place and fuel price lookups
`EXPO_PUBLIC_BARCHART_API_KEY`	Barchart station price lookups
`EXPO_PUBLIC_CARDOG_API_KEY`	Cardog regional pricing lookups
`EXPO_PUBLIC_EIA_API_KEY`	EIA market data
`EXPO_PUBLIC_FRED_API_KEY`	FRED market data

What The App Contains

Area	What it does
Home map	Finds nearby stations, ranks prices, clusters markers, and keeps the bottom-card selection synchronized with the map
Trends	Rebuilds historical station price rows into charts, a leaderboard, and regional summaries
Settings	Stores radius, preferred fuel grade, theme, onboarding reset, cache reset, and predictive location controls
Dev tools	Exposes request counters, cache reset helpers, local notification triggers, and Live Activity testing controls
Onboarding	Walks through the product narrative, predictive fueling demo, permissions, radius, and fuel-grade preferences

Architecture

Routing and app shell

app/_layout.js is the root gate. It wires the global providers, decides whether onboarding should appear, mounts the tab stack, and handles cluster-probe automation entry points.
app/(tabs)/_layout.js defines the native tab bar and the four primary tabs: Home, Trends, Settings, and Dev.
app/prices-sheet.js is presented as a form sheet from the root stack.

Shared state

src/AppStateContext.js owns volatile app-wide state such as manual location overrides, resolved search context, cache reset tokens, cluster probe requests, and the progressive root reveal.
src/PreferencesContext.js persists user-facing preferences in AsyncStorage, including search radius, preferred fuel grade, provider mode, and onboarding completion.
src/ThemeContext.js centralizes light, dark, and system appearance handling.

Fuel data pipeline

src/services/fuel/index.js is the aggregation entry point. It resolves the active provider mode, requests station and regional data, validates stale prices, deduplicates overlapping results, caches snapshots, and produces the ranked station list used by the map and sheet.
src/services/fuel/core.js contains provider-specific request builders, response normalizers, cache-key logic, and quote-selection helpers.
src/services/fuel/priceValidation.js applies validation and prediction rules before a quote is displayed.
src/services/fuel/trends.js, trendProjection.js, and trendLeaderboard.js rebuild Supabase history into the Trends screen’s charts and leaderboard.

Predictive fueling experience

src/screens/OnboardingScreen.js drives the full onboarding flow.
src/screens/onboarding/predictive/ contains the predictive fueling map scene, route simulation, camera choreography, and narrative UI shown during onboarding.
src/screens/onboarding/predictive/simulationMath.cjs and routeDiagnostics.cjs are the core math and validation utilities behind the predictive demo.

Native and platform integrations

src/lib/notifications.js handles push notification registration, token persistence, and Live Activity helpers.
src/lib/PriceDropActivity.tsx defines the widget / activity UI surface.
modules/fuel-up-map-kit-routing/ contains the local Expo module used for native MapKit routing support.
plugins/withProgressiveBlurNativeBuild.js and the patch scripts in scripts/ keep the native build path aligned with the project’s UI and widget setup.

Repository Layout

app/                                Expo Router screens and tab entry points
assets/                             App icon, logos, splash art, predictive visuals
modules/fuel-up-map-kit-routing/    Local Expo native module
plugins/                            Expo config plugins
scripts/                            Local tooling, patching, push, and diagnostics helpers
src/components/                     Shared UI components and overlays
src/lib/                            State, preferences, location, notifications, utilities
src/screens/                        Onboarding and predictive fueling screens
src/services/fuel/                  Aggregation, validation, caching, trends, projections
tests/                              Unit tests and simulator-driven quality checks

Verification

These commands were used to validate the current repository state:

npm test
npx expo config --json
npm run ios:sim
gitleaks dir . --no-banner

Scripts

Command	Description
`npm start`	Starts the Expo dev server
`npm run ios:sim`	Opens the app in the iOS simulator through Expo
`npm run ios`	Runs the configured physical-device workflow
`npm run android`	Runs the Android build path
`npm run web`	Starts the web target
`npm test`	Runs the default unit and logic test suite
`npm run test:cluster`	Runs cluster animation tests plus the simulator probe integration
`npm run push:send`	Sends a push notification using local APNs credentials

Bundle IDs

iOS: com.anthonyh.fuelup
Android: com.anthonyh.fuelup