Skip to content

README.md

Latest commit

 

History

History
188 lines (132 loc) · 8.45 KB

README.md

File metadata and controls

188 lines (132 loc) · 8.45 KB
Raw

OctaneTrack

Kotlin Jetpack Compose Material 3 FastAPI SQLite Python License: MIT

OctaneTrack is a full-stack vehicle telemetry platform that pairs an offline-first Kotlin/Jetpack Compose Android client with a FastAPI + SQLite REST backend. It computes rolling fuel-efficiency metrics from consecutive full-tank fill-ups, forecasts mileage-based maintenance due dates from your historical driving cadence, and maintains a complete cost-of-ownership ledger across fuel and service invoices.

📸 Visual Walkthrough

Authentication & Vehicle Access Dashboard Telemetry Fuel Log Ledger
JWT Login / Register Live Metrics & Odometer Consumption & Full-Tank Badges
Service History Cost & Consumption Reports
Service Logs & Intervals TCO, Trends & Best/Worst

✨ Core Features

🚗 Vehicle Onboarding & Multi-Car Management

  • Guided vehicle creation dialog with km / mi unit toggle and FAB speed-dial entry point.
  • Instant vehicle switching from the top bar — all tabs re-sync to the newly selected vehicle.
  • Non-destructive soft-delete: deactivating a vehicle flips is_active server-side and auto-switches the client to the next active vehicle (or resets to the empty state).

⛽ Fuel Telemetry & Rolling Economics

  • Consecutive full-tank consumption algorithm: each full fill-up computes L/100km (and MPG) over the distance since the previous full fill.
  • Partial-tank aggregation: multi-fill sequences between two full tanks have their volumes summed before the economy figure is computed.
  • Per-fill cost-per-kilometer tracking with best/worst economy badges.

🔧 Predictive Maintenance Engine

  • Derives an average daily distance rate from historical fuel-log timestamps and odometer deltas.
  • Projects a calendar due date for every mileage-based service interval (next_due_odometer).
  • Dashboard surfaces the nearest upcoming service with remaining distance and days.

📊 Detailed Analytics & Reports

  • Total Cost of Ownership (TCO) aggregating fuel invoices and maintenance invoices.
  • Monthly spend bars, best/worst consumption cards, and a per-fill consumption trend visualization.

📴 Offline-First Resilience

  • Room Database (v2) local cache with isActive filtering and destructive migration.
  • Reactive StateFlow / Flow streams driving the MVVM OctaneViewModel.
  • JWT authentication with tokens persisted in EncryptedSharedPreferences, a Bearer OkHttp interceptor, and automatic 401 logout.
  • Three-state screens (Loading / Error + Retry / Content), pull-to-refresh, and a friendly Snackbar error pipeline.

🏗️ System Architecture & Tech Stack

┌─────────────────────────────┐         ┌──────────────────────────────┐
│  Android Client (Kotlin)    │  HTTPS  │  FastAPI Backend (Python)    │
│  ─────────────────────────  │  JSON   │  ──────────────────────────  │
│  Compose UI (Material 3)    │ ◄─────► │  routers/ (auth, vehicles,   │
│  OctaneViewModel (StateFlow)│  Bearer │    fuel, service, reports)   │
│  OctaneRepository           │  JWT    │  Pydantic v2 schemas         │
│  Retrofit2 + OkHttp3        │         │  SQLAlchemy 2.0 ORM          │
│  Room cache + EncryptedPrefs│         │  SQLite database             │
└─────────────────────────────┘         └──────────────────────────────┘

Client (Android):

Concern Technology
Language Kotlin
UI Jetpack Compose + Material 3 design tokens (explicit high-contrast light/dark themes)
Networking Retrofit2 + OkHttp3 + HttpLoggingInterceptor (BODY level)
Local Storage Jetpack Room (SQLite) + EncryptedSharedPreferences
Concurrency Kotlin Coroutines + StateFlow / Flow

Backend (REST API):

Concern Technology
Framework FastAPI (Python 3.10+)
Database SQLite via SQLAlchemy 2.0 ORM
Auth/Security OAuth2 Password Bearer with JWT (PyJWT) + Bcrypt hashing (Passlib)
Validation Pydantic v2 schemas

API Surface

Method Endpoint Purpose
POST /api/auth/register · /api/auth/login · /api/auth/login/json · /api/auth/me Account lifecycle
POST / GET /api/vehicles Create / list active vehicles
GET / DELETE /api/vehicles/{id} Fetch / soft-delete (is_active=false)
GET / POST / DELETE /api/fuel Fuel log CRUD (scoped by vehicle_id)
GET / POST / DELETE /api/service Service log CRUD
GET /api/reports/summary TCO, efficiency, projections

All data endpoints are user-scoped — every query filters by the JWT identity.

🧮 Mathematical & Forecasting Logic

Implemented in backend/routers/reports.py and verified by exact-assertion tests in backend/tests/.

Fuel Efficiency (per full-tank interval)

$$\text{Fuel Economy }(L/100\text{km}) = \left(\frac{\sum \text{Fuel Volume (L)}}{\text{Odometer}_{\text{end}} - \text{Odometer}_{\text{start}}}\right) \times 100$$

Partial fills between two consecutive full tanks contribute their volume to the numerator; distance is measured full-stop to full-stop.

Dynamic Daily Distance Rate

$$\text{Daily Mileage Rate} = \frac{\text{Latest Odometer} - \text{Initial Odometer}}{\text{Days Elapsed}}$$

Days are derived from the timestamps of the earliest and latest fuel logs.

Projected Service Due Date

$$\text{Projected Date} = \text{Current Date} + \left(\frac{\text{Next Due Odometer} - \text{Current Odometer}}{\text{Daily Mileage Rate}}\right)$$

The dashboard renders the nearest projection as "in N km · ~N days remaining".

Cost of Ownership

$$\text{Cost/km} = \frac{\text{Fuel Total} + \text{Service Total}}{\text{Distance Driven}}$$

🚀 Local Setup & Installation

Backend

# 1. Create & activate a virtual environment
cd backend
python3 -m venv .venv
source .venv/bin/activate

# 2. Install dependencies
pip install -r requirements.txt

# 3. Seed the demo database (demo user, vehicle @43,500 km, fuel logs & services)
python seed.py

# 4. Launch the API
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

Interactive docs: http://localhost:8000/docs · Demo credentials: demo@octanetrack.com / password123

Android Client

  1. Point the client at your server. The base URL is a BuildConfig field (BASE_URL, default http://10.0.2.2:8000/api/ for the Android Emulator): 
    # Emulator (default — no flag needed)
./gradlew installDebug

# Physical device on the same LAN
./gradlew installDebug -Poctanetrack.baseUrl=http://192.168.x.x:8000/api/
  2. Open the project in Android Studio, select a device/emulator, and press Run ▶, or build from the CLI: 
    ./gradlew assembleDebug
  3. Log in with the seeded demo account (hint shown on the auth screen) and start logging fill-ups.

Tests

# Backend (34 tests)
pytest backend/tests/

# Android (unit + MockWebServer API tests)
./gradlew testDebugUnitTest

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.