FuelIQ

A fleet fuel management system built for Kenya's transport industry. FuelIQ helps fleet managers track fuel consumption, monitor driver performance, and reduce operating costs through ML-powered predictions and real-time trip tracking.

---

Features

Driver App

• Real-time GPS trip tracking with live waypoint recording
• Fuel consumption predictions powered by a Gradient Boosting ML model
• Personal performance dashboard (distance, fuel used, efficiency score)
• Assigned vehicle details and service status
• Offline trip queuing with automatic sync on reconnect

Fleet Manager App

• Fleet-wide analytics and fuel efficiency trends
• Driver performance rankings and comparisons
• Vehicle management (status, assignments, service scheduling)
• Budget tracking by route
• AI-generated fuel-saving recommendations

Admin App

• User and company management
• System-wide analytics
• Fuel price and settings configuration

---

Tech Stack

Mobile (this repo)

Layer	Technology
Framework	React Native 0.81 + Expo SDK 52
Navigation	Expo Router 6 (file-based)
Language	TypeScript (strict mode)
Styling	NativeWind (Tailwind CSS for RN)
State	Zustand
Server state	TanStack Query v5
Animations	React Native Reanimated 4
Storage	Expo SecureStore
Icons	Expo Vector Icons (Ionicons)

Backend (in /backend)

Layer	Technology
Framework	FastAPI 0.115
Language	Python 3.11
Database	PostgreSQL (production) / SQLite (local dev)
ORM	SQLAlchemy 2.0 + Alembic migrations
Auth	JWT (python-jose) + bcrypt
ML Model	Gradient Boosting Regressor (scikit-learn)
Server	Uvicorn
Deployment	Railway (Docker)

ML Model

• Algorithm: Gradient Boosting Regressor
• Accuracy: R² = 0.9922, MAE = 0.84 L, MAPE = 5.45%
• Features: 13 inputs — engine size, cylinders, distance, speed, idle time, load weight, fuel type, route type
• Output: Predicted fuel consumption (litres) + efficiency score (0–100) + driving recommendations
• Size: 1.4 MB (bundled in Docker image)

---

Project Structure

fueliq/
├── app/                        # Expo Router screens (file-based routing)
│   ├── (driver)/               # Driver role screens
│   │   ├── dashboard/
│   │   ├── trips/
│   │   ├── vehicles/
│   │   └── profile/
│   ├── (manager)/              # Fleet manager role screens
│   │   ├── dashboard/
│   │   ├── drivers/
│   │   ├── vehicles/
│   │   ├── analytics/
│   │   ├── budgets/
│   │   └── settings/
│   ├── (admin)/                # Admin role screens
│   ├── auth/                   # Login / register screens
│   └── index.tsx               # Root redirect (routes by role)
├── features/                   # Feature modules
│   ├── auth/
│   ├── trips/
│   ├── vehicles/
│   ├── drivers/
│   ├── analytics/
│   ├── budgets/
│   ├── predictions/
│   └── admin/
├── lib/                        # Shared utilities
│   ├── api/                    # API client + endpoint definitions
│   ├── constants/              # Config, roles
│   ├── query/                  # React Query setup + offline sync
│   ├── storage/                # SecureStore + offline queue
│   └── utils/
├── providers/                  # React context providers
│   ├── auth-provider.tsx
│   ├── query-provider.tsx
│   └── offline-provider.tsx
├── ui/                         # Shared UI components
├── types/                      # Global TypeScript types
└── backend/                    # FastAPI backend
    ├── app/
    │   ├── routers/            # API route handlers
    │   ├── models/             # SQLAlchemy models
    │   ├── services/           # Business logic
    │   ├── core/               # Auth, security
    │   └── config.py
    ├── ml/
    │   ├── models/             # Trained .joblib model files
    │   ├── scripts/            # Training + data generation scripts
    │   └── src/                # Feature engineering + preprocessing
    ├── alembic/                # DB migrations
    ├── Dockerfile
    └── railway.toml

---

Getting Started

Prerequisites

• Node.js 18+
• Bun (npm install -g bun)
• Python 3.11+
• Android Studio / Xcode (for emulator)

Mobile Setup

# Install dependencies
bun install

# Start the dev server
npm start

# Run on Android emulator
npm run android

# Run on iOS simulator
npm run ios

Backend Setup (local)

cd backend

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Create .env file
cp .env.example .env

# Run DB migrations
alembic upgrade head

# Start the server
uvicorn app.main:app --reload --port 8000

The API will be available at http://localhost:8000. Swagger docs at http://localhost:8000/docs.

Local API Configuration

For local development, the mobile app points to http://10.0.2.2:8000/api/v1 (Android emulator's alias for localhost). Edit lib/constants/config.ts if you need a different host.

---

Deployment

The backend is deployed on Railway with a PostgreSQL database hosted on Supabase.

Backend (Railway)

1. Push the repo to GitHub
2. Create a new Railway project → Deploy from GitHub → set root directory to backend
3. Railway auto-detects the Dockerfile and builds it
4. Set these environment variables in Railway dashboard:

DATABASE_URL=postgresql://postgres:[PASSWORD]@[HOST]:5432/postgres
SECRET_KEY=<long-random-string>
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7
FUEL_PRICE_KES=180.0
ML_MODEL_PATH=ml/models/fuel_consumption_model.joblib

5. On first deploy, Railway runs alembic upgrade head automatically (configured in railway.toml) then starts the server.

Database (Supabase)

1. Create a free project at supabase.com
2. Go to Settings → Database → Connection string → URI
3. Use the URI as the DATABASE_URL environment variable in Railway

Mobile Production Build (APK)

# Install EAS CLI
npm install -g eas-cli

# Login to Expo
eas login

# Build APK
eas build --platform android --profile preview

Update lib/constants/config.ts with your Railway URL before building:

API_BASE_URL: __DEV__
  ? "http://10.0.2.2:8000/api/v1"
  : "https://fueliq-production.up.railway.app//api/v1",

---

API Reference

Base URL: /api/v1

Resource	Endpoints
Auth	POST /auth/login, /auth/register, /auth/refresh, /auth/logout, GET /auth/me
Trips	GET/POST /trips, GET/PUT /trips/{id}, POST /trips/{id}/end, GET /trips/active
Vehicles	GET/POST /vehicles, GET/PUT/DELETE /vehicles/{id}, POST /vehicles/{id}/assign
Drivers	GET /drivers, GET /drivers/{id}, GET /drivers/performance
Analytics	GET /analytics/fuel-efficiency, /analytics/daily, /analytics/summary
Recommendations	GET /recommendations
Budgets	GET/POST /budgets, GET/PUT /budgets/{routeId}
Predictions	POST /predict/fuel-consumption
Admin	GET/POST /admin/users, GET /admin/analytics, GET/PUT /admin/settings

Full interactive docs available at https://fueliq-production.up.railway.app//docs.

---

Roles & Permissions

Role	Access
driver	Own trips, assigned vehicle, personal analytics
fleet_manager	All drivers, all vehicles, fleet analytics, budgets
admin	Full access + user management + system settings

---

Environment Variables

Backend (backend/.env)

Variable	Description	Default
DATABASE_URL	PostgreSQL or SQLite connection string	sqlite:///./fueliq.db
SECRET_KEY	JWT signing secret	—
ALGORITHM	JWT algorithm	HS256
ACCESS_TOKEN_EXPIRE_MINUTES	Access token TTL	30
REFRESH_TOKEN_EXPIRE_DAYS	Refresh token TTL	7
FUEL_PRICE_KES	Fuel price in Kenyan Shillings	180.0
ML_MODEL_PATH	Path to the .joblib model file	ml/models/fuel_consumption_model.joblib

---

Development Notes

• Package manager: Bun (bun.lock present) — use bun install not npm install
• Path alias: @/* maps to the project root
• Platform-specific files: Use .ios.tsx / .web.ts extensions for platform overrides
• New Architecture: Enabled (newArchEnabled: true in app.json)
• React Compiler: Enabled for automatic memoization
• Typed routes: Enabled — Expo Router generates types for all routes
• Mock API: Set USE_MOCK_API: true in lib/constants/config.ts to run fully offline without a backend