CampusEV — Driver App

The driver-facing Android app of the CampusEV campus live-tracking system. A driver logs in, selects the vehicle they're operating (type + number) and a route, taps Start, and the app streams the phone's GPS in the background — so students can watch the vehicle move in real time. Stop ends the shift.

Part of the CampusEV system: Driver app · Student app · Backend service.

---

✨ Features

• Background GPS streaming via a foreground service — keeps sending location with the screen locked (no ACCESS_BACKGROUND_LOCATION needed, since it starts from the foreground).
• Login + approval gating — a driver signs in; an admin must approve the account, and can disable tracking at any time (kill switch).
• Self-service shift setup — the driver picks their vehicle (EV / VAN / BUS + number) and route, then Start/Stop.
• Bilingual — English and ଓଡ଼ିଆ (Odia), switchable in-app (per-app locale, persisted).
• Clean MVVM architecture — repository layer, unidirectional state, manual DI.

---

🧱 Tech stack

Area	Choice
Language	Kotlin
UI	Jetpack Compose (Material 3)
Architecture	MVVM + Repository, unidirectional data flow with StateFlow
DI	Manual (AppContainer) — no framework
Networking	Retrofit + OkHttp
Serialization	kotlinx.serialization (snake_case JSON)
Location	FusedLocationProvider in a foreground service
Token storage	Jetpack DataStore
Localization	AppCompat per-app locales (English / Odia)
Concurrency	Kotlin coroutines + Flow
Min SDK	26 (Android 8.0)
CI	GitHub Actions (build + unit tests)

---

🗂️ Project structure

app/src/main/java/com/campusev/driverapp/
  ui/auth        LoginScreen · LoginViewModel · LoginUiState
  ui/home        DriverHomeScreen · DriverHomeViewModel · DriverHomeUiState (vehicle/route + Start/Stop)
  ui/theme       Compose theme
  data/auth      AuthRepository · AuthTokenStore (DataStore) · SessionState
  data/driver    DriverRepository (vehicles, select, status)
  data/location  LocationRepository · LocationFix
  data/network   ApiService (Retrofit) · AuthInterceptor · dto/ (ApiEnvelope + DTOs)
  location       LocationForegroundService (streams GPS → repo + backend)
  di             AppContainer (manual DI) + CampusEvDriverApp (Application)
  core/locale    AppLanguage (English / Odia switch)
  MainActivity   thin: theme + entry only

Deeper detail: docs/ARCHITECTURE.md.

---

✅ Prerequisites

• Android Studio (latest stable) with the Android SDK.
• JDK 21 (the bundled JetBrains Runtime is fine; CLI Gradle builds need JBR/JDK 21).
• A physical Android device running API 26+ — strongly recommended, since background GPS is unreliable on emulators.
• Internet access — the app talks to the backend service.
• An approved driver account — register in-app, then an admin approves it (via the backend) before you can go on duty.

---

⚙️ Setup & configuration

1. Clone & open the project in Android Studio; let Gradle sync.
2. Backend endpoint — the base URL is provided through BuildConfig.BASE_URL, set in app/build.gradle.kts. Point it at your own backend deployment. (Deployment URLs are intentionally kept out of the public docs — don't commit real URLs to the README.)
3. Secrets — none are required to build. Anything sensitive belongs in local.properties, which is git-ignored (see Secrets & .gitignore).

---

▶️ Build & run

./gradlew :app:assembleDebug        # build the debug APK

…or hit Run on the app configuration in Android Studio.

On the device:

1. Log in (with an approved account).
2. Pick your vehicle + route and tap Start.
3. Grant location and notification permissions when prompted.
4. Lock the screen — location keeps streaming (watch Logcat tag LocationForegroundService).

The backend may take a few seconds to respond to the first request if it has been idle.

Permissions used: INTERNET, ACCESS_NETWORK_STATE, ACCESS_FINE_LOCATION, FOREGROUND_SERVICE (+ location type), POST_NOTIFICATIONS.

---

🧪 Testing

./gradlew :app:testDebugUnitTest

🔁 CI

GitHub Actions builds the app and runs unit tests on every push and PR (.github/workflows/ci.yml). No secrets are required to compile.

---

🔐 Secrets & .gitignore

The repo's .gitignore excludes what shouldn't be published — local.properties, .idea/, and build/. Keep API keys, backend URLs, and any deployment details out of committed files and out of this README. Before pushing, sanity-check that local.properties is not staged.

---

🤝 Contributing

This project uses spec-driven development — non-trivial work starts as a written spec that's reviewed before coding.

• CONTRIBUTING.md — the workflow, branching, conventions, Definition of Done
• docs/specs/ — feature specs (copy docs/specs/TEMPLATE.md to start one)
• docs/ARCHITECTURE.md — how the app is structured
• CLAUDE.md — operating manual for AI assistants

Every user-facing string must be added in both English (res/values/strings.xml) and Odia (res/values-or/strings.xml).

---

🗺️ Status & roadmap

• ✅ Core flow: login → select vehicle/route → Start/Stop → background GPS streaming — spec 0001
• 🔜 Trip origin → destination pickers — spec 0002
• ⬜ In-app trip history / stats

---

License

TBD — add a LICENSE file before making the repository public if you intend to set usage terms.

---

Part of the CampusEV system: Driver app · Student app · Backend service.