ev-gramacharge

Imported from TheArchitect416/ev-gramacharge (AGENTS.md). Install upstream with npx skills add TheArchitect416/ev-gramacharge. Copyright stays with the author.

EV-Grama Charge - Agent Knowledge Base

Generated: 2026-05-10 Updated: 2026-05-10 (Phase 10 complete, all phases done) Package: com.internship.gramacharge Min SDK: 26 | Target SDK: 36

Overview

Community-driven EV charging app for rural/semi-urban India. Peer-to-peer model: hosts list 15A sockets; riders find/book on live map.

Tech Stack

• Kotlin 2.0.21 + Jetpack Compose BOM 2026.02.01 (no XML)
• Hilt 2.51.1 for DI
• Firebase 32.7.0 (Auth, Firestore, FCM, Storage)
• Mapbox 11.8.0 for maps
• Material 3 with custom brand theme
• AGP 8.7.3 with Gradle 9.3.1

Brand Colors

Package Structure

com.internship.gramacharge
├── di/                  # Hilt modules (AppModule, RepositoryModule)
├── data/
│   ├── model/           # Host, Booking, Rider
│   ├── repository/      # HostRepository, BookingRepository
│   └── preferences/     # DataStore UserPreferences
├── domain/
│   └── calculator/     # ChargingCalculator (pure Kotlin)
├── ui/
│   ├── theme/           # Color, Theme, Type
│   ├── navigation/      # Screen routes, AppNavGraph
│   ├── screens/         # 10 screens (splash → history)
│   ├── components/      # StatusBadge, HostCard, AvailabilityToggle
│   └── viewmodel/       # AuthViewModel
└── service/             # EvGramaFCMService

Navigation Flow

Splash → RoleSelector → OtpLogin → MapHome (Rider)
                              └→ HostDashboard (Host)

Key Patterns

State Management

// ViewModel: expose StateFlow with stateIn
val uiState: StateFlow<UiState> = flow
    .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), initialValue)

// Composable: collect lifecycle-aware
val state by viewModel.uiState.collectAsStateWithLifecycle()

DI Pattern

@HiltViewModel
class MyViewModel @Inject constructor(
    private val repository: MyRepository
) : ViewModel()

@Composable
fun MyScreen(viewModel: MyViewModel = hiltViewModel())

Design Principles

1. Clarity - Clean typography, generous whitespace
2. Accessibility - 48dp touch targets, color+shape for status
3. Performance - Lifecycle-aware collection, lazy lists
4. No Dark Mode - Light theme only (per prompt)

Commands

# Build debug APK
./gradlew assembleDebug

# Run unit tests
./gradlew test

# Run UI tests
./gradlew connectedAndroidTest

What NOT To Do

• ❌ XML layouts or ViewBinding
• ❌ LiveData (use StateFlow)
• ❌ GlobalScope (use viewModelScope)
• ❌ Firestore on main thread
• ❌ Mock data (leave Firebase wiring)

Obsidian Knowledge Base

Project planning and documentation stored in Obsidian vault:

• GramaCharge/Projects/EV-Grama Charge.md - Project overview
• GramaCharge/Projects/Project Plan.md - Full phase-wise plan
• GramaCharge/Projects/Technical Decisions.md - Architecture decisions
• GramaCharge/Projects/Design Guidelines.md - UI/UX guidelines
• GramaCharge/Projects/Firebase Setup Guide.md - Firebase setup

Important Notes

• Firebase requires google-services.json (placeholder exists)
• Mapbox requires MAPBOX_ACCESS_TOKEN in local.properties
• Build will fail without real credentials (expected until setup)
• 12 phases, 25-30 commits total for full implementation

Phase 0 Complete

Dependencies Configured

• Compose BOM + UI + Material3 + Icons Extended
• Hilt DI (android + compiler + navigation)
• Firebase (Auth, Firestore, Messaging, Storage)
• Mapbox SDK
• GeoFirestore
• Lottie animations
• DataStore preferences
• Coil image loading
• Accompanist permissions
• GeoHash library
• KSP for annotation processing

Files Created/Modified

• gradle/libs.versions.toml - Complete dependency catalog (50+ libs)
• build.gradle.kts - Firebase + Hilt plugins
• settings.gradle.kts - Mapbox Maven + JitPack repos
• app/build.gradle.kts - All implementations + BuildConfig
• app/google-services.json - Placeholder config
• local.properties - MAPBOX_ACCESS_TOKEN placeholder
• firestore.rules - Security rules
• firestore.indexes.json - Composite indexes

Next: Phase 3 - Navigation Architecture

Phase 1 Complete

DI Modules Created

• di/AppModule.kt - FirebaseAuth, Firestore (with persistence), FirebaseMessaging, FirebaseStorage, Context, DataStore
• di/RepositoryModule.kt - HostRepository and BookingRepository bindings

Data Models Created

• data/model/Host.kt - Host entity with all Firestore fields + toMap()
• data/model/Booking.kt - Booking entity with status management
• data/model/Rider.kt - Rider profile entity

UserPreferences Created

• data/preferences/UserPreferences.kt - DataStore-based user session (role, userId, onboardingDone)

Repositories Created

• data/repository/HostRepository.kt - Interface with 5 methods
• data/repository/HostRepositoryImpl.kt - GeoFirestore nearby query, real-time listeners
• data/repository/BookingRepository.kt - Interface with 5 methods
• data/repository/BookingRepositoryImpl.kt - Transaction-safe booking with host availability lock

Domain Created

• domain/calculator/ChargingCalculator.kt - Pure Kotlin charging calculations with vehicle presets

MainActivity Updated

• @AndroidEntryPoint annotation added for Hilt

Next: Phase 2 - UI Foundation

Phase 2 Complete

Theme Files Created

• ui/theme/Color.kt - Brand colors (ElectricBlue, ElectricGreen, BusyRed, OfflineGrey)
• ui/theme/Theme.kt - Material 3 lightColorScheme with custom brand colors
• ui/theme/Type.kt - Full typography scale

UI Components Created

• ui/components/StatusBadge.kt - HostStatus enum, StatusBadge composable, StatusDot, DiamondShape
• ui/components/HostCard.kt - HostCard composable with ProfileImage, SocketChip, RatingDisplay
• ui/components/AvailabilityToggle.kt - AvailabilityToggle composable with CustomSwitch

Next: Phase 3 - Navigation Architecture

Phase 3 Complete

Navigation Files Created

• ui/navigation/Screen.kt - Sealed class with all 10 route definitions
• ui/navigation/AppNavGraph.kt - NavHost with fade transitions (300ms)

Screen Composables Created (all stubs)

• SplashScreen, RoleSelectorScreen, OtpLoginScreen
• MapHomeScreen, HostProfileScreen, BookingConfirmScreen, BookingCalculatorScreen, BookingActiveScreen
• HostDashboardScreen, HostEditProfileScreen, BookingHistoryScreen

MainActivity Updated

• Replaced placeholder with AppNavGraph and rememberNavController

Build Verified

• Debug APK builds successfully with ./gradlew assembleDebug

Next: Phase 5 - Rider Experience

Phase 4 Complete

AuthViewModel Created

• ui/viewmodel/AuthViewModel.kt - Full Firebase Phone Auth implementation
  • AuthUiState sealed class (Idle, Loading, OtpSent, Verified, Error)
  • AuthEvent sealed class for navigation (NavigateToMapHome, NavigateToHostDashboard, NavigateToRoleSelector)
  • sendOtp() - Sends OTP via Firebase Phone Auth
  • verifyOtp() - Verifies OTP and signs in
  • resendOtp() - Resends OTP with forceResendingToken
  • checkAuthState() - Checks stored user session
  • setUserRole() - Saves role (rider/host) to DataStore
  • signOut() - Clears session and navigates to role selector

Screens Updated

• SplashScreen.kt - Added auth check, redirects based on stored session
• RoleSelectorScreen.kt - Phone validation, role selection, ViewModel integration
• OtpLoginScreen.kt - Full OTP verification UI with resend, error handling, loading states

Firebase Integration

• Phone Auth callbacks registered with PhoneAuthProvider.OnVerificationStateChangedCallbacks
• Automatic OTP verification on code received
• Error handling for invalid credentials, recaptcha failures, timeouts
• Phone number formatting (+91 prefix for India)

Build Verified

• Debug APK builds successfully with ./gradlew assembleDebug

Next: Phase 7 - Push Notifications & FCM

Phase 6 Complete

Host ViewModels Created

• ui/viewmodel/HostDashboardViewModel.kt - Dashboard UI state (Loading/Error/Success), availability toggle, earnings tracking, recent bookings
• ui/viewmodel/HostEditProfileViewModel.kt - EditableHostProfile data class, HostEditProfileUiState sealed class (Loading/Editing/Saving/Saved/Error), save/update logic
• ui/viewmodel/BookingHistoryViewModel.kt - HistoryFilter enum (ALL/PENDING/COMPLETED/CANCELLED), filtered bookings by date, pull-to-refresh

Host Screens Implemented

• ui/screens/HostDashboardScreen.kt - Greeting card, availability toggle (AvailabilityToggle), earnings summary (today/this week/total), quick action buttons (Edit Profile, View History, Sign Out), recent bookings list with BookingCard
• ui/screens/BookingHistoryScreen.kt - Summary header (total/pending/completed/cancelled counts), filter chips row (All/Pending/Completed/Cancelled), pull-to-refresh with LazyColumn, BookingCard list
• ui/screens/HostEditProfileScreen.kt - Complete form with name, phone (read-only), address, socket type dropdown, power rating dropdown, price/hour & price/unit fields, working hours time pickers (Start/End), Save Changes button with loading overlay

Build Verified

• Debug APK builds successfully with ./gradlew assembleDebug
• All Phase 6 files compile without errors

Next: Phase 10 - Testing

Phase 7 Complete

Application Class Created

• GramaChargeApplication.kt - HiltAndroidApp with notification channel setup
  • CHANNEL_BOOKING - High priority for booking confirmations, reminders, completions
  • CHANNEL_GENERAL - Default priority for app-wide announcements

FCM Service Implemented

• service/EvGramaFCMService.kt - Full Firebase Cloud Messaging integration
  • onNewToken() - Saves new FCM token to Firestore
  • onMessageReceived() - Handles both data and notification payloads
  • Message types: booking_new, booking_confirmed, booking_cancelled, booking_completed, reminder
  • Notification tap navigates to MainActivity with extras
  • Expandable notifications on Android 7.0+
  • Permission-safe notification display

AndroidManifest Updated

• Added android:name=".GramaChargeApplication" to application tag
• Registered EvGramaFCMService with com.google.firebase.MESSAGING_EVENT intent filter
• Added POST_NOTIFICATIONS permission

Notification Icon Created

• res/drawable/ic_notification.xml - Vector drawable lightning bolt icon

Build Verified

• Debug APK builds successfully with ./gradlew assembleDebug
• All Phase 7 files compile without errors

Phase 8 Complete

BookingActiveViewModel Created

• ui/viewmodel/BookingActiveViewModel.kt - Full active booking management
  • BookingActiveUiState sealed class (Loading, Active, Completed, Error)
  • elapsedSeconds StateFlow with real-time timer via viewModelScope.launch
  • completeBooking() - Calls repository to update status
  • cancelBooking() - Cancels the active booking with host confirmation
  • Polling mechanism for booking status changes

BookingActiveScreen Implemented

• ui/screens/BookingActiveScreen.kt - Full active booking UI
  • CircularProgressIndicator (160dp) with animated progress
  • Live timer display (HH:MM:SS format)
  • Host info card with contact options
  • "Charging in progress..." status with progress percentage
  • "Complete & Pay" and "Cancel Booking" action buttons
  • Automatic navigation to history on completion

BookingRepository Extended

• Added getActiveBookingForRider(riderId) - Queries active/confirmed bookings
• Added completeBooking(bookingId) - Updates status to completed with endTime

Build Verified

• Debug APK builds successfully with ./gradlew assembleDebug
• All Phase 8 files compile without errors

Next: Phase 10 - Testing

Phase 9 Complete

Firebase Security Rules Enhanced

• firestore.rules - Comprehensive rules with helper functions
  • isAuthenticated() - Check if request has valid auth
  • isOwner() - Verify user owns the document
  • isRiderOrHost() - Verify user is participant in booking
  • Hosts: read (all authenticated), create/update (owner only)
  • Bookings: read (participants), create (rider), update (participants)
  • Riders: read/write (owner only)
  • userTokens: read/write (owner only) - for FCM push notifications
  • Safety valve: deny all other paths

Firestore Indexes Updated

• firestore.indexes.json - Optimized for common queries
  • bookings: (hostId, createdAt), (riderId, createdAt)
  • bookings: (hostId, status), (riderId, status)
  • hosts: (userId, isAvailable)

CI/CD Workflow Created

• .github/workflows/android.yml - GitHub Actions workflow
  • Build job: compiles debug APK
  • Unit tests job: runs ./gradlew testDebugUnitTest
  • Lint job: runs ./gradlew lintDebug
  • Firebase deploy job: deploys rules/indexes on main push
  • Summary job: reports all job statuses

Templates Added

• .github/pull_request_template.md - Standard PR description template
• .github/ISSUE_TEMPLATE/bug_report.md - Bug report template with device info

Build Verified

• Debug APK builds successfully with ./gradlew assembleDebug
• Phase 9 committed as 93782b2

Next: Phase 10 - Testing