ARS — Auto Repair Service

Rescuing your ride.

On-demand auto repair, on a map. ARS connects vehicle owners with nearby mechanics for booking, live ETA, in-app chat, payments, and AI-assisted diagnostics — with a real-time dashboard for mechanics.

---

📱 Screenshots

  

_{Splash · Choose your role (customer or mechanic)}

More screens (booking map, live ETA, chat, mechanic dashboard) require a live Firebase project — see Getting Started.

📖 About

ARS (Auto Repair Service) is a Flutter mobile app that connects vehicle owners with professional mechanics for on-demand automotive repair. A customer can describe a problem, get an AI-assisted diagnosis and cost estimate, find a nearby mechanic on a live map, watch their ETA, chat in real time, and pay — while mechanics manage incoming jobs from a real-time dashboard.

It's built Android-first with a feature-first clean architecture, Firebase for backend services, and a self-hosted OSRM routing engine for accurate, zero-cost ETAs tuned for Metro Manila.

✨ Key Features

• 🤖 AI Diagnostic Chatbot — 87.4% accurate automotive diagnosis with Taglish support (201 terms, 97.5% accuracy)
• 💰 Smart Cost Estimation — Metro Manila pricing with urgency classification
• 🗺️ Real-time Location Services — find nearby mechanics and track requests on a live map
• 🧭 Live ETA — self-hosted OSRM routing with 30-second auto-refresh
• 👤 Auth & Roles — separate customer and mechanic flows (Firebase Auth)
• 🚙 Vehicle Management — add and manage multiple vehicles
• 🔧 Service Booking — engine, brake, tire, battery, oil change, AC, and more
• 💬 In-app Chat — real-time messaging between customer and mechanic
• 📊 Service Tracking — monitor a job from request to completion
• 🏪 Mechanic Dashboard — real-time map of nearby requests, online/offline toggle, earnings
• 🔔 Push Notifications — Firebase Cloud Messaging + local notifications

🛠️ Tech Stack

• Framework: Flutter 3.9+ · Language: Dart 3.9+
• Architecture: Feature-first clean architecture (data / domain / presentation)
• State management: Riverpod — provider infrastructure in place; feature-by-feature migration from StatefulWidget in progress (mechanic earnings migrated as the reference slice, with unit tests)
• Design system: ARS token-based theme (orange #F97316, light + dark) with widget/token tests
• Backend (Firebase): Auth, Cloud Firestore, Cloud Storage, Cloud Messaging, Crashlytics
• Maps & location: flutter_map (OpenStreetMap tiles), google_maps_flutter, geolocator
• Routing/ETA: self-hosted OSRM (custom server, no external routing cost)
• AI / ML (companion service — see below): ARS Rapide diagnostic API (FastAPI + Gemini 2.0 Flash, LangGraph, ChromaDB/RAG, Redis cache)
• Testing: flutter_test — design-system, architecture, and feature (Riverpod notifier) tests
• Tooling: flutter_launcher_icons, flutter_lints

🏗️ Architecture

ARS organizes code by feature, each split into clean-architecture layers. Customer screens are prefixed user_*; mechanic screens mechanic_*.

lib/
├── core/                     # Shared: auth, theme/design-system, services
│   ├── providers/            # Riverpod core providers (Firebase, OSRM, auth, repos)
│   ├── theme/                # ARS design system (tokens, light/dark themes)
│   ├── services/             # Notifications, OSRM routing, location sharing
│   ├── widgets/ utils/ models/ constants/
├── features/
│   ├── onboarding/           # Splash, onboarding, role selection
│   ├── customer/             # user_* — auth, booking, vehicles, dashboard, ...
│   │   └── booking/{data,domain,presentation}/
│   └── mechanic/             # mechanic_* — auth, dashboard, services, earnings
│       └── earnings/presentation/providers/   # ← Riverpod migration template
├── firebase_options.dart     # gitignored — generated via `flutterfire configure`
└── main.dart                 # Entry point (ProviderScope + Firebase init)

Principles: feature isolation, clear data/domain/presentation boundaries, shared code in core/, single responsibility per module. See docs/ARCHITECTURE.md.

🚀 Getting Started

Prerequisites

• Flutter SDK 3.9+ and Dart 3.9+
• Android Studio or VS Code, and an Android device/emulator

Setup

# 1. Clone
git clone https://github.com/KpG782/ars.git
cd ars

# 2. Install dependencies
flutter pub get

3. Firebase (optional — bring your own project). This repo ships placeholder Firebase config (lib/firebase_options.dart and android/app/google-services.json hold clearly-fake values) so the app builds and runs out of the box with the backend disabled. To enable real auth, Firestore, Storage, and push, generate your own and overwrite the placeholders:

dart pub global activate flutterfire_cli
flutterfire configure          # overwrites firebase_options.dart + google-services.json

The app is wrapped so it still launches with the placeholder config (UI works), but auth, Firestore, and push require your own project.

4. (Optional) AI chatbot key. Copy .env.example to .env and set your key; without it, the AI diagnostic chat is simply disabled:

cp .env.example .env       # then set ARS_CHATBOT_API_KEY=...

5. (Optional) Google Maps key — set it in android/app/src/main/AndroidManifest.xml (com.google.android.geo.API_KEY) if you use Google Maps tiles; OpenStreetMap tiles work without one.

6. Run

flutter run

Handy commands

flutter analyze        # static analysis (currently clean)
flutter test           # run the test suite
flutter build apk --debug

🤖 AI & API Integrations

The diagnostic intelligence runs in ARS Rapide, a separate FastAPI service this app integrates with over HTTP (X-API-Key).

• ARS Rapide Diagnostic API — RAG-based automotive diagnosis, Taglish support, cost estimation
  • Accuracy: 87.4% diagnostic accuracy · Taglish 97.5% (201 terms)
  • Response time: ~3.7s (cache miss) / <1s (cache hit, Redis)
  • Stack: Gemini 2.0 Flash · LangGraph (agentic state machine) · ChromaDB (vector search) · Redis · Prometheus metrics
• Firebase: Auth (email/password), Cloud Firestore (real-time), Cloud Storage (docs/photos), FCM (push)
• Maps/Location: OpenStreetMap tiles, Google Maps, Geolocator
• OSRM (self-hosted): real-time route + ETA between customer and mechanic, 30s auto-refresh, fallback estimation, Manila road network optimized, no external API cost

Firestore access is enforced by firestore.rules with composite indexes in firestore.indexes.json; see docs/FIREBASE_SCHEMA_REVIEW.md.

🗺️ Roadmap

Done

• Feature-first clean architecture
• Customer + mechanic auth and onboarding
• Service booking with live map
• Self-hosted OSRM ETA (30s refresh, fallback)
• In-app chat + push notifications
• AI diagnostic chatbot integration (Taglish, cost estimation)
• ARS design system (light/dark) + tests
• Riverpod infrastructure + first feature migrated (earnings)
• Firestore security rules + composite indexes

Planned

• Payment integration (GCash / cards)
• Reviews & ratings
• Complete the Riverpod migration across remaining features
• Advanced filters, full Tagalog/English localization, offline mode

👤 Author

Ken Patrick Garcia — @KpG782

⚠️ Actively-developed portfolio project. Firebase config ships as fake placeholders so the app builds out of the box — run flutterfire configure to point it at a real project. Real secrets (the .env chatbot key, native iOS/macOS plists) are not committed; add your own to enable backend features.

📄 License

Released under the MIT License.

---

_{Built with Flutter 💙}