feat: Phase 1 critical gaps — gamification API, Razorpay checkout, Google OAuth, notifications

- Fix gamification endpoints to use Node.js server (app.eventifyplus.com)
- Replace 6 mock gamification methods with real API calls (dashboard, leaderboard, shop, redeem, submit)
- Add booking models, service, payment service (Razorpay), checkout provider
- Add 3-step CheckoutScreen with Razorpay native modal integration
- Add Google OAuth login (Flutter + Django backend)
- Add full notifications system (Django model + 3 endpoints + Flutter UI)
- Register CheckoutProvider, NotificationProvider in main.dart MultiProvider
- Wire notification bell in HomeScreen app bar
- Add razorpay_flutter ^1.3.7 and google_sign_in ^6.2.2 packages

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

lib/features/auth/providers/auth_provider.dart

@@ -59,6 +59,19 @@ class AuthProvider extends ChangeNotifier {
     }
   }
 
+  /// Google OAuth login.
+  Future<void> googleLogin() async {
+    _loading = true;
+    notifyListeners();
+    try {
+      final user = await _authService.googleLogin();
+      _user = user;
+    } finally {
+      _loading = false;
+      notifyListeners();
+    }
+  }
+
   Future<void> logout() async {
     await _authService.logout();
     _user = null;

lib/features/auth/services/auth_service.dart

@@ -1,10 +1,12 @@
 // lib/features/auth/services/auth_service.dart
 import 'package:flutter/foundation.dart' show kDebugMode, debugPrint;
 import 'package:shared_preferences/shared_preferences.dart';
+import 'package:google_sign_in/google_sign_in.dart';
 import '../../../core/api/api_client.dart';
 import '../../../core/api/api_endpoints.dart';
 import '../../../core/auth/auth_guard.dart';
 import '../../../core/storage/token_storage.dart';
+import '../../../core/analytics/posthog_service.dart';
 import '../models/user_model.dart';
 
 class AuthService {
@@ -58,6 +60,12 @@ class AuthService {
       // Save phone if provided (optional)
       if (res['phone_number'] != null) await prefs.setString('phone_number', res['phone_number'].toString());
 
+      PostHogService.instance.identify(savedEmail, properties: {
+        'username': displayCandidate,
+        'login_method': 'email',
+      });
+      PostHogService.instance.capture('user_logged_in');
+
       return UserModel.fromJson(res);
     } catch (e) {
       if (kDebugMode) debugPrint('AuthService.login error: $e');
@@ -130,6 +138,54 @@ class AuthService {
     }
   }
 
+  /// GOOGLE OAUTH LOGIN → returns UserModel
+  Future<UserModel> googleLogin() async {
+    try {
+      final googleSignIn = GoogleSignIn(scopes: ['email']);
+      final account = await googleSignIn.signIn();
+      if (account == null) throw Exception('Google sign-in cancelled');
+
+      final auth = await account.authentication;
+      final idToken = auth.idToken;
+      if (idToken == null) throw Exception('Failed to get Google ID token');
+
+      final res = await _api.post(
+        ApiEndpoints.googleLogin,
+        body: {'id_token': idToken},
+        requiresAuth: false,
+      );
+
+      final token = res['token'];
+      if (token == null) throw Exception('Token missing from response');
+
+      final serverEmail = (res['email'] as String?) ?? account.email;
+      final displayName = (res['username'] as String?) ?? account.displayName ?? serverEmail;
+
+      AuthGuard.setGuest(false);
+      await TokenStorage.saveToken(token.toString(), serverEmail);
+
+      final prefs = await SharedPreferences.getInstance();
+      await prefs.setString('current_email', serverEmail);
+      await prefs.setString('email', serverEmail);
+      final perKey = 'display_name_$serverEmail';
+      if ((prefs.getString(perKey) ?? '').isEmpty) {
+        await prefs.setString(perKey, displayName);
+      }
+      if (res['phone_number'] != null) await prefs.setString('phone_number', res['phone_number'].toString());
+
+      PostHogService.instance.identify(serverEmail, properties: {
+        'username': displayName,
+        'login_method': 'google',
+      });
+      PostHogService.instance.capture('user_logged_in');
+
+      return UserModel.fromJson(res);
+    } catch (e) {
+      if (kDebugMode) debugPrint('AuthService.googleLogin error: $e');
+      rethrow;
+    }
+  }
+
   /// Logout – clear auth token and current_email (keep per-account display_name entries so they persist)
   Future<void> logout() async {
     try {
@@ -141,6 +197,8 @@ class AuthService {
       // Also remove canonical 'email' pointing to current user
       await prefs.remove('email');
       // Do not delete display_name_<email> entries — they are per-account and should remain on device.
+      PostHogService.instance.capture('user_logged_out');
+      PostHogService.instance.reset();
     } catch (e) {
       if (kDebugMode) debugPrint('AuthService.logout warning: $e');
     }

lib/features/booking/models/booking_models.dart

@@ -0,0 +1,87 @@
+// lib/features/booking/models/booking_models.dart
+
+class TicketMetaModel {
+  final int id;
+  final int eventId;
+  final String ticketType;
+  final double price;
+  final int availableQuantity;
+  final String? description;
+
+  const TicketMetaModel({
+    required this.id,
+    required this.eventId,
+    required this.ticketType,
+    required this.price,
+    this.availableQuantity = 0,
+    this.description,
+  });
+
+  factory TicketMetaModel.fromJson(Map<String, dynamic> json) {
+    return TicketMetaModel(
+      id: (json['id'] as num?)?.toInt() ?? 0,
+      eventId: (json['event_id'] as num?)?.toInt() ?? (json['event'] as num?)?.toInt() ?? 0,
+      ticketType: json['ticket_type'] as String? ?? json['name'] as String? ?? '',
+      price: (json['price'] as num?)?.toDouble() ?? 0.0,
+      availableQuantity: (json['available_quantity'] as num?)?.toInt() ?? 0,
+      description: json['description'] as String?,
+    );
+  }
+}
+
+class CartItemModel {
+  final TicketMetaModel ticket;
+  int quantity;
+
+  CartItemModel({required this.ticket, this.quantity = 1});
+
+  double get subtotal => ticket.price * quantity;
+}
+
+class ShippingDetails {
+  final String name;
+  final String email;
+  final String phone;
+  final String? address;
+  final String? city;
+  final String? state;
+  final String? zipCode;
+
+  const ShippingDetails({
+    required this.name,
+    required this.email,
+    required this.phone,
+    this.address,
+    this.city,
+    this.state,
+    this.zipCode,
+  });
+
+  Map<String, dynamic> toJson() => {
+    'name': name,
+    'email': email,
+    'phone': phone,
+    if (address != null) 'address': address,
+    if (city != null) 'city': city,
+    if (state != null) 'state': state,
+    if (zipCode != null) 'zip_code': zipCode,
+  };
+}
+
+class OrderSummary {
+  final List<CartItemModel> items;
+  final double subtotal;
+  final double discount;
+  final double tax;
+  final double total;
+  final String? couponCode;
+
+  const OrderSummary({
+    required this.items,
+    required this.subtotal,
+    this.discount = 0,
+    this.tax = 0,
+    required this.total,
+    this.couponCode,
+  });
+}

lib/features/booking/providers/checkout_provider.dart

@@ -0,0 +1,147 @@
+// lib/features/booking/providers/checkout_provider.dart
+
+import 'package:flutter/foundation.dart';
+import '../../../core/utils/error_utils.dart';
+import '../models/booking_models.dart';
+import '../services/booking_service.dart';
+
+enum CheckoutStep { tickets, details, payment, confirmation }
+
+class CheckoutProvider extends ChangeNotifier {
+  final BookingService _service = BookingService();
+
+  // Event being booked
+  int? eventId;
+  String eventName = '';
+
+  // Step tracking
+  CheckoutStep currentStep = CheckoutStep.tickets;
+
+  // Ticket selection
+  List<TicketMetaModel> availableTickets = [];
+  List<CartItemModel> cart = [];
+
+  // Shipping
+  ShippingDetails? shippingDetails;
+
+  // Coupon
+  String? couponCode;
+
+  // Status
+  bool loading = false;
+  String? error;
+  String? paymentId;
+
+  /// Initialize checkout for an event.
+  Future<void> initForEvent(int eventId, String eventName) async {
+    this.eventId = eventId;
+    this.eventName = eventName;
+    currentStep = CheckoutStep.tickets;
+    cart = [];
+    shippingDetails = null;
+    couponCode = null;
+    paymentId = null;
+    error = null;
+    loading = true;
+    notifyListeners();
+
+    try {
+      availableTickets = await _service.getTicketMeta(eventId);
+    } catch (e) {
+      error = userFriendlyError(e);
+    } finally {
+      loading = false;
+      notifyListeners();
+    }
+  }
+
+  /// Add or update cart item.
+  void setTicketQuantity(TicketMetaModel ticket, int qty) {
+    cart.removeWhere((c) => c.ticket.id == ticket.id);
+    if (qty > 0) {
+      cart.add(CartItemModel(ticket: ticket, quantity: qty));
+    }
+    notifyListeners();
+  }
+
+  double get subtotal => cart.fold(0, (sum, item) => sum + item.subtotal);
+  double get total => subtotal; // expand with discount/tax later
+
+  bool get hasItems => cart.isNotEmpty;
+
+  /// Move to next step.
+  void nextStep() {
+    if (currentStep == CheckoutStep.tickets && hasItems) {
+      currentStep = CheckoutStep.details;
+    } else if (currentStep == CheckoutStep.details && shippingDetails != null) {
+      currentStep = CheckoutStep.payment;
+    }
+    notifyListeners();
+  }
+
+  /// Move to previous step.
+  void previousStep() {
+    if (currentStep == CheckoutStep.payment) {
+      currentStep = CheckoutStep.details;
+    } else if (currentStep == CheckoutStep.details) {
+      currentStep = CheckoutStep.tickets;
+    }
+    notifyListeners();
+  }
+
+  /// Set shipping details from form.
+  void setShipping(ShippingDetails details) {
+    shippingDetails = details;
+    notifyListeners();
+  }
+
+  /// Process checkout on backend.
+  Future<Map<String, dynamic>> processCheckout() async {
+    loading = true;
+    error = null;
+    notifyListeners();
+
+    try {
+      final tickets = cart.map((c) => {
+        'ticket_meta_id': c.ticket.id,
+        'quantity': c.quantity,
+      }).toList();
+
+      final res = await _service.processCheckout(
+        eventId: eventId!,
+        tickets: tickets,
+        shippingDetails: shippingDetails?.toJson() ?? {},
+        couponCode: couponCode,
+      );
+      return res;
+    } catch (e) {
+      error = userFriendlyError(e);
+      rethrow;
+    } finally {
+      loading = false;
+      notifyListeners();
+    }
+  }
+
+  /// Mark payment as complete.
+  void markPaymentSuccess(String id) {
+    paymentId = id;
+    currentStep = CheckoutStep.confirmation;
+    notifyListeners();
+  }
+
+  /// Reset checkout state.
+  void reset() {
+    eventId = null;
+    eventName = '';
+    currentStep = CheckoutStep.tickets;
+    availableTickets = [];
+    cart = [];
+    shippingDetails = null;
+    couponCode = null;
+    paymentId = null;
+    error = null;
+    loading = false;
+    notifyListeners();
+  }
+}

lib/features/booking/services/booking_service.dart

@@ -0,0 +1,53 @@
+// lib/features/booking/services/booking_service.dart
+
+import '../../../core/api/api_client.dart';
+import '../../../core/api/api_endpoints.dart';
+import '../models/booking_models.dart';
+
+class BookingService {
+  final ApiClient _api = ApiClient();
+
+  /// Fetch available ticket types for an event.
+  Future<List<TicketMetaModel>> getTicketMeta(int eventId) async {
+    final res = await _api.post(
+      ApiEndpoints.ticketMetaList,
+      body: {'event_id': eventId},
+    );
+    final rawList = res['ticket_metas'] ?? res['tickets'] ?? res['data'] ?? [];
+    if (rawList is List) {
+      return rawList
+          .map((e) => TicketMetaModel.fromJson(Map<String, dynamic>.from(e as Map)))
+          .toList();
+    }
+    return [];
+  }
+
+  /// Add item to cart.
+  Future<Map<String, dynamic>> addToCart({
+    required int ticketMetaId,
+    required int quantity,
+  }) async {
+    return await _api.post(
+      ApiEndpoints.cartAdd,
+      body: {'ticket_meta_id': ticketMetaId, 'quantity': quantity},
+    );
+  }
+
+  /// Process checkout — creates booking + returns order ID for payment.
+  Future<Map<String, dynamic>> processCheckout({
+    required int eventId,
+    required List<Map<String, dynamic>> tickets,
+    required Map<String, dynamic> shippingDetails,
+    String? couponCode,
+  }) async {
+    return await _api.post(
+      ApiEndpoints.checkout,
+      body: {
+        'event_id': eventId,
+        'tickets': tickets,
+        'shipping': shippingDetails,
+        if (couponCode != null) 'coupon_code': couponCode,
+      },
+    );
+  }
+}

lib/features/booking/services/payment_service.dart

@@ -0,0 +1,67 @@
+// lib/features/booking/services/payment_service.dart
+
+import 'package:razorpay_flutter/razorpay_flutter.dart';
+import 'package:flutter/foundation.dart';
+
+typedef PaymentSuccessCallback = void Function(PaymentSuccessResponse response);
+typedef PaymentErrorCallback = void Function(PaymentFailureResponse response);
+typedef ExternalWalletCallback = void Function(ExternalWalletResponse response);
+
+class PaymentService {
+  late Razorpay _razorpay;
+
+  // Razorpay test key — matches web app
+  static const String _testKey = 'rzp_test_S49PVZmqAVoWSH';
+
+  PaymentSuccessCallback? onSuccess;
+  PaymentErrorCallback? onError;
+  ExternalWalletCallback? onExternalWallet;
+
+  void initialize({
+    required PaymentSuccessCallback onSuccess,
+    required PaymentErrorCallback onError,
+    ExternalWalletCallback? onExternalWallet,
+  }) {
+    _razorpay = Razorpay();
+    this.onSuccess = onSuccess;
+    this.onError = onError;
+    this.onExternalWallet = onExternalWallet;
+
+    _razorpay.on(Razorpay.EVENT_PAYMENT_SUCCESS, _handleSuccess);
+    _razorpay.on(Razorpay.EVENT_PAYMENT_ERROR, _handleError);
+    _razorpay.on(Razorpay.EVENT_EXTERNAL_WALLET, _handleExternalWallet);
+  }
+
+  void openPayment({
+    required double amount,
+    required String email,
+    required String phone,
+    required String eventName,
+    String? orderId,
+  }) {
+    final options = <String, dynamic>{
+      'key': _testKey,
+      'amount': (amount * 100).toInt(), // paise
+      'currency': 'INR',
+      'name': 'Eventify',
+      'description': 'Ticket: $eventName',
+      'prefill': {
+        'email': email,
+        'contact': phone,
+      },
+      'theme': {'color': '#0B63D6'},
+    };
+    if (orderId != null) options['order_id'] = orderId;
+
+    if (kDebugMode) debugPrint('PaymentService: opening Razorpay with amount=${amount * 100} paise');
+    _razorpay.open(options);
+  }
+
+  void _handleSuccess(PaymentSuccessResponse res) => onSuccess?.call(res);
+  void _handleError(PaymentFailureResponse res) => onError?.call(res);
+  void _handleExternalWallet(ExternalWalletResponse res) => onExternalWallet?.call(res);
+
+  void dispose() {
+    _razorpay.clear();
+  }
+}

lib/features/gamification/models/gamification_models.dart

@@ -94,41 +94,162 @@ class UserGamificationProfile {
 }
 
 // ---------------------------------------------------------------------------
-// LeaderboardEntry
+// LeaderboardEntry — maps from Node.js API response fields
 // ---------------------------------------------------------------------------
 class LeaderboardEntry {
   final int rank;
   final String username;
   final String? avatarUrl;
   final int lifetimeEp;
+  final int monthlyPoints;
   final ContributorTier tier;
   final int eventsCount;
   final bool isCurrentUser;
+  final String? district;
 
   const LeaderboardEntry({
     required this.rank,
     required this.username,
     this.avatarUrl,
     required this.lifetimeEp,
+    this.monthlyPoints = 0,
     required this.tier,
     required this.eventsCount,
     this.isCurrentUser = false,
+    this.district,
   });
 
   factory LeaderboardEntry.fromJson(Map<String, dynamic> json) {
-    final ep = (json['lifetime_ep'] as int?) ?? 0;
+    // Node.js API returns 'points' for lifetime EP and 'name' for username
+    final ep = (json['points'] as num?)?.toInt() ?? (json['lifetime_ep'] as num?)?.toInt() ?? 0;
+    final tierStr = json['level'] as String? ?? json['tier'] as String?;
     return LeaderboardEntry(
-      rank: (json['rank'] as int?) ?? 0,
-      username: json['username'] as String? ?? '',
+      rank: (json['rank'] as num?)?.toInt() ?? 0,
+      username: json['name'] as String? ?? json['username'] as String? ?? '',
       avatarUrl: json['avatar_url'] as String?,
       lifetimeEp: ep,
-      tier: tierFromEp(ep),
-      eventsCount: (json['events_count'] as int?) ?? 0,
+      monthlyPoints: (json['monthlyPoints'] as num?)?.toInt() ?? 0,
+      tier: tierStr != null ? _tierFromString(tierStr) : tierFromEp(ep),
+      eventsCount: (json['eventsAdded'] as num?)?.toInt() ?? (json['events_count'] as num?)?.toInt() ?? 0,
       isCurrentUser: (json['is_current_user'] as bool?) ?? false,
+      district: json['district'] as String?,
     );
   }
 }
 
+/// Parse tier string from API (e.g. "Gold") to enum.
+ContributorTier _tierFromString(String s) {
+  switch (s.toLowerCase()) {
+    case 'diamond':  return ContributorTier.DIAMOND;
+    case 'platinum': return ContributorTier.PLATINUM;
+    case 'gold':     return ContributorTier.GOLD;
+    case 'silver':   return ContributorTier.SILVER;
+    default:         return ContributorTier.BRONZE;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CurrentUserStats — from leaderboard API's currentUser field
+// ---------------------------------------------------------------------------
+class CurrentUserStats {
+  final int rank;
+  final int points;
+  final int monthlyPoints;
+  final String level;
+  final int rewardCycleDays;
+  final int eventsAdded;
+  final String? district;
+
+  const CurrentUserStats({
+    required this.rank,
+    required this.points,
+    this.monthlyPoints = 0,
+    required this.level,
+    this.rewardCycleDays = 0,
+    this.eventsAdded = 0,
+    this.district,
+  });
+
+  factory CurrentUserStats.fromJson(Map<String, dynamic> json) {
+    return CurrentUserStats(
+      rank: (json['rank'] as num?)?.toInt() ?? 0,
+      points: (json['points'] as num?)?.toInt() ?? 0,
+      monthlyPoints: (json['monthlyPoints'] as num?)?.toInt() ?? 0,
+      level: json['level'] as String? ?? 'Bronze',
+      rewardCycleDays: (json['rewardCycleDays'] as num?)?.toInt() ?? 0,
+      eventsAdded: (json['eventsAdded'] as num?)?.toInt() ?? 0,
+      district: json['district'] as String?,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// LeaderboardResponse — wraps the full leaderboard API response
+// ---------------------------------------------------------------------------
+class LeaderboardResponse {
+  final List<LeaderboardEntry> entries;
+  final CurrentUserStats? currentUser;
+  final int totalParticipants;
+
+  const LeaderboardResponse({
+    required this.entries,
+    this.currentUser,
+    this.totalParticipants = 0,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// SubmissionModel — event submissions from dashboard API
+// ---------------------------------------------------------------------------
+class SubmissionModel {
+  final String id;
+  final String eventName;
+  final String category;
+  final String status; // PENDING, APPROVED, REJECTED
+  final String? district;
+  final int epAwarded;
+  final DateTime createdAt;
+  final List<String> images;
+
+  const SubmissionModel({
+    required this.id,
+    required this.eventName,
+    this.category = '',
+    required this.status,
+    this.district,
+    this.epAwarded = 0,
+    required this.createdAt,
+    this.images = const [],
+  });
+
+  factory SubmissionModel.fromJson(Map<String, dynamic> json) {
+    final rawImages = json['images'] as List? ?? [];
+    return SubmissionModel(
+      id: (json['id'] ?? json['submission_id'] ?? '').toString(),
+      eventName: json['event_name'] as String? ?? '',
+      category: json['category'] as String? ?? '',
+      status: json['status'] as String? ?? 'PENDING',
+      district: json['district'] as String?,
+      epAwarded: (json['total_ep_awarded'] as num?)?.toInt() ?? (json['ep_awarded'] as num?)?.toInt() ?? 0,
+      createdAt: DateTime.tryParse(json['created_at'] as String? ?? '') ?? DateTime.now(),
+      images: rawImages.map((e) => e.toString()).toList(),
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// DashboardResponse — wraps the full dashboard API response
+// ---------------------------------------------------------------------------
+class DashboardResponse {
+  final UserGamificationProfile profile;
+  final List<SubmissionModel> submissions;
+
+  const DashboardResponse({
+    required this.profile,
+    this.submissions = const [],
+  });
+}
+
 // ---------------------------------------------------------------------------
 // ShopItem — mirrors `RedeemShopItem` table
 // ---------------------------------------------------------------------------

lib/features/gamification/providers/gamification_provider.dart

@@ -13,6 +13,9 @@ class GamificationProvider extends ChangeNotifier {
   List<LeaderboardEntry> leaderboard = [];
   List<ShopItem> shopItems = [];
   List<AchievementBadge> achievements = [];
+  List<SubmissionModel> submissions = [];
+  CurrentUserStats? currentUserStats;
+  int totalParticipants = 0;
 
   // Leaderboard filters — matches web version
   String leaderboardDistrict = 'Overall Kerala';
@@ -31,15 +34,22 @@ class GamificationProvider extends ChangeNotifier {
 
     try {
       final results = await Future.wait([
-        _service.getProfile(),
+        _service.getDashboard(),
         _service.getLeaderboard(district: leaderboardDistrict, timePeriod: leaderboardTimePeriod),
         _service.getShopItems(),
         _service.getAchievements(),
       ]);
 
-      profile    = results[0] as UserGamificationProfile;
-      leaderboard = results[1] as List<LeaderboardEntry>;
-      shopItems  = results[2] as List<ShopItem>;
+      final dashboard = results[0] as DashboardResponse;
+      profile = dashboard.profile;
+      submissions = dashboard.submissions;
+
+      final lbResponse = results[1] as LeaderboardResponse;
+      leaderboard = lbResponse.entries;
+      currentUserStats = lbResponse.currentUser;
+      totalParticipants = lbResponse.totalParticipants;
+
+      shopItems = results[2] as List<ShopItem>;
       achievements = results[3] as List<AchievementBadge>;
     } catch (e) {
       error = userFriendlyError(e);
@@ -57,7 +67,10 @@ class GamificationProvider extends ChangeNotifier {
     leaderboardDistrict = district;
     notifyListeners();
     try {
-      leaderboard = await _service.getLeaderboard(district: district, timePeriod: leaderboardTimePeriod);
+      final response = await _service.getLeaderboard(district: district, timePeriod: leaderboardTimePeriod);
+      leaderboard = response.entries;
+      currentUserStats = response.currentUser;
+      totalParticipants = response.totalParticipants;
     } catch (e) {
       error = userFriendlyError(e);
     }
@@ -72,7 +85,10 @@ class GamificationProvider extends ChangeNotifier {
     leaderboardTimePeriod = period;
     notifyListeners();
     try {
-      leaderboard = await _service.getLeaderboard(district: leaderboardDistrict, timePeriod: period);
+      final response = await _service.getLeaderboard(district: leaderboardDistrict, timePeriod: period);
+      leaderboard = response.entries;
+      currentUserStats = response.currentUser;
+      totalParticipants = response.totalParticipants;
     } catch (e) {
       error = userFriendlyError(e);
     }

lib/features/gamification/services/gamification_service.dart

@@ -1,146 +1,139 @@
 // lib/features/gamification/services/gamification_service.dart
 //
-// Stub service using the real API contract from TechDocs v2.
-// All methods currently return mock data.
-// TODO: replace each mock block with a real ApiClient call once
-//       the backend endpoints are live on uat.eventifyplus.com.
+// Real API service for the Contributor / Gamification module.
+// Calls the Node.js gamification server at app.eventifyplus.com.
 
-import 'dart:math';
+import '../../../core/api/api_client.dart';
+import '../../../core/api/api_endpoints.dart';
+import '../../../core/storage/token_storage.dart';
 import '../models/gamification_models.dart';
 
 class GamificationService {
+  final ApiClient _api = ApiClient();
+
+  /// Helper: get current user's email for API calls.
+  Future<String> _getUserEmail() async {
+    final email = await TokenStorage.getUsername();
+    return email ?? '';
+  }
+
   // ---------------------------------------------------------------------------
-  // User Gamification Profile
-  // TODO: replace with ApiClient.get(ApiEndpoints.gamificationProfile)
+  // Dashboard (profile + submissions)
+  // GET /v1/gamification/dashboard?user_id={email}
   // ---------------------------------------------------------------------------
-  Future<UserGamificationProfile> getProfile() async {
-    await Future.delayed(const Duration(milliseconds: 400));
-    return const UserGamificationProfile(
-      userId: 'mock-user-001',
-      lifetimeEp: 320,
-      currentEp: 70,
-      currentRp: 45,
-      tier: ContributorTier.SILVER,
+  Future<DashboardResponse> getDashboard() async {
+    final email = await _getUserEmail();
+    final url = '${ApiEndpoints.gamificationDashboard}?user_id=$email';
+    final res = await _api.post(url, requiresAuth: false);
+
+    final profileJson = res['profile'] as Map<String, dynamic>? ?? {};
+    final rawSubs = res['submissions'] as List? ?? [];
+
+    final submissions = rawSubs
+        .map((s) => SubmissionModel.fromJson(Map<String, dynamic>.from(s as Map)))
+        .toList();
+
+    return DashboardResponse(
+      profile: UserGamificationProfile.fromJson(profileJson),
+      submissions: submissions,
     );
   }
 
+  /// Convenience — returns just the profile (backward-compatible with provider).
+  Future<UserGamificationProfile> getProfile() async {
+    final dashboard = await getDashboard();
+    return dashboard.profile;
+  }
+
   // ---------------------------------------------------------------------------
   // Leaderboard
-  // district: 'Overall Kerala' | 'Thiruvananthapuram' | 'Kollam' | ...
-  // timePeriod: 'all_time' | 'this_month'
-  // TODO: replace with ApiClient.get(ApiEndpoints.leaderboard, params: {'district': district, 'period': timePeriod})
+  // GET /v1/gamification/leaderboard?period=all|month&district=X&user_id=Y&limit=50
   // ---------------------------------------------------------------------------
-  Future<List<LeaderboardEntry>> getLeaderboard({
+  Future<LeaderboardResponse> getLeaderboard({
     required String district,
     required String timePeriod,
   }) async {
-    await Future.delayed(const Duration(milliseconds: 500));
+    final email = await _getUserEmail();
 
-    // Realistic mock names per district
-    final names = [
-      'Annette Black', 'Jerome Bell', 'Theresa Webb', 'Courtney Henry',
-      'Cameron Williamson', 'Dianne Russell', 'Wade Warren', 'Albert Flores',
-      'Kristin Watson', 'Guy Hawkins',
-    ];
+    // Map Flutter filter values to API params
+    final period = timePeriod == 'this_month' ? 'month' : 'all';
 
-    final rng = Random(district.hashCode ^ timePeriod.hashCode);
-    final baseEp = timePeriod == 'this_month' ? 800 : 4500;
+    final params = <String, String>{
+      'period': period,
+      'user_id': email,
+      'limit': '50',
+    };
+    if (district != 'Overall Kerala') {
+      params['district'] = district;
+    }
 
-    final entries = List.generate(10, (i) {
-      final ep = baseEp - (i * (timePeriod == 'this_month' ? 55 : 280)) + rng.nextInt(30);
-      return LeaderboardEntry(
-        rank: i + 1,
-        username: names[i],
-        lifetimeEp: ep,
-        tier: tierFromEp(ep),
-        eventsCount: 149 - i * 12,
-        isCurrentUser: i == 7, // mock: current user is rank 8
+    final query = Uri(queryParameters: params).query;
+    final url = '${ApiEndpoints.leaderboard}?$query';
+    final res = await _api.post(url, requiresAuth: false);
+
+    final rawList = res['leaderboard'] as List? ?? [];
+    final entries = rawList
+        .map((e) => LeaderboardEntry.fromJson(Map<String, dynamic>.from(e as Map)))
+        .toList();
+
+    CurrentUserStats? currentUser;
+    if (res['currentUser'] != null && res['currentUser'] is Map) {
+      currentUser = CurrentUserStats.fromJson(
+        Map<String, dynamic>.from(res['currentUser'] as Map),
       );
-    });
+    }
 
-    return entries;
-  }
-
-  // ---------------------------------------------------------------------------
-  // Redeem Shop Items
-  // TODO: replace with ApiClient.get(ApiEndpoints.shopItems)
-  // ---------------------------------------------------------------------------
-  Future<List<ShopItem>> getShopItems() async {
-    await Future.delayed(const Duration(milliseconds: 400));
-    return const [
-      ShopItem(
-        id: 'item-001',
-        name: 'Amazon ₹500 Voucher',
-        description: 'Redeem for any purchase on Amazon India.',
-        rpCost: 50,
-        stockQuantity: 20,
-      ),
-      ShopItem(
-        id: 'item-002',
-        name: 'Swiggy ₹200 Voucher',
-        description: 'Free food delivery credit on Swiggy.',
-        rpCost: 20,
-        stockQuantity: 35,
-      ),
-      ShopItem(
-        id: 'item-003',
-        name: 'Eventify Pro — 1 Month',
-        description: 'Premium access to Eventify.Plus features.',
-        rpCost: 30,
-        stockQuantity: 100,
-      ),
-      ShopItem(
-        id: 'item-004',
-        name: 'Zomato ₹150 Voucher',
-        description: 'Discount on your next Zomato order.',
-        rpCost: 15,
-        stockQuantity: 50,
-      ),
-      ShopItem(
-        id: 'item-005',
-        name: 'BookMyShow ₹300 Voucher',
-        description: 'Movie & event ticket credit on BookMyShow.',
-        rpCost: 30,
-        stockQuantity: 15,
-      ),
-      ShopItem(
-        id: 'item-006',
-        name: 'Exclusive Badge',
-        description: 'Rare "Pioneer" badge for your profile.',
-        rpCost: 5,
-        stockQuantity: 0, // out of stock
-      ),
-    ];
-  }
-
-  // ---------------------------------------------------------------------------
-  // Redeem an item
-  // TODO: replace with ApiClient.post(ApiEndpoints.shopRedeem, body: {'item_id': itemId})
-  // ---------------------------------------------------------------------------
-  Future<RedemptionRecord> redeemItem(String itemId) async {
-    await Future.delayed(const Duration(milliseconds: 600));
-    // Generate a fake voucher code
-    final code = 'EVT-${itemId.toUpperCase().replaceAll('-', '').substring(0, 4)}-${Random().nextInt(9000) + 1000}';
-    return RedemptionRecord(
-      id: 'redemption-${DateTime.now().millisecondsSinceEpoch}',
-      itemId: itemId,
-      rpSpent: 0, // provider will look up cost
-      voucherCode: code,
-      timestamp: DateTime.now(),
+    return LeaderboardResponse(
+      entries: entries,
+      currentUser: currentUser,
+      totalParticipants: (res['totalParticipants'] as num?)?.toInt() ?? entries.length,
     );
   }
 
+  // ---------------------------------------------------------------------------
+  // Shop Items
+  // GET /v1/shop/items
+  // ---------------------------------------------------------------------------
+  Future<List<ShopItem>> getShopItems() async {
+    final res = await _api.post(ApiEndpoints.shopItems, requiresAuth: false);
+    final rawItems = res['items'] as List? ?? [];
+    return rawItems
+        .map((e) => ShopItem.fromJson(Map<String, dynamic>.from(e as Map)))
+        .toList();
+  }
+
+  // ---------------------------------------------------------------------------
+  // Redeem Item
+  // POST /v1/shop/redeem  body: { user_id, item_id }
+  // ---------------------------------------------------------------------------
+  Future<RedemptionRecord> redeemItem(String itemId) async {
+    final email = await _getUserEmail();
+    final res = await _api.post(
+      ApiEndpoints.shopRedeem,
+      body: {'user_id': email, 'item_id': itemId},
+      requiresAuth: false,
+    );
+    final voucher = res['voucher'] as Map<String, dynamic>? ?? res;
+    return RedemptionRecord.fromJson(Map<String, dynamic>.from(voucher));
+  }
+
   // ---------------------------------------------------------------------------
   // Submit Contribution
-  // TODO: replace with ApiClient.post(ApiEndpoints.contributeSubmit, body: data)
+  // POST /v1/gamification/submit-event  body: event data
   // ---------------------------------------------------------------------------
   Future<void> submitContribution(Map<String, dynamic> data) async {
-    await Future.delayed(const Duration(milliseconds: 800));
-    // Mock always succeeds
+    final email = await _getUserEmail();
+    final body = <String, dynamic>{'user_id': email, ...data};
+    await _api.post(
+      ApiEndpoints.contributeSubmit,
+      body: body,
+      requiresAuth: false,
+    );
   }
 
   // ---------------------------------------------------------------------------
   // Achievements
+  // TODO: wire to achievements API when available on Node.js server
   // ---------------------------------------------------------------------------
   Future<List<AchievementBadge>> getAchievements() async {
     await Future.delayed(const Duration(milliseconds: 300));

lib/features/notifications/models/notification_model.dart

@@ -0,0 +1,33 @@
+// lib/features/notifications/models/notification_model.dart
+
+class NotificationModel {
+  final int id;
+  final String title;
+  final String message;
+  final String type; // event, promo, system, booking
+  bool isRead;
+  final DateTime createdAt;
+  final String? actionUrl;
+
+  NotificationModel({
+    required this.id,
+    required this.title,
+    required this.message,
+    this.type = 'system',
+    this.isRead = false,
+    required this.createdAt,
+    this.actionUrl,
+  });
+
+  factory NotificationModel.fromJson(Map<String, dynamic> json) {
+    return NotificationModel(
+      id: (json['id'] as num?)?.toInt() ?? 0,
+      title: json['title'] as String? ?? '',
+      message: json['message'] as String? ?? '',
+      type: json['notification_type'] as String? ?? json['type'] as String? ?? 'system',
+      isRead: (json['is_read'] as bool?) ?? false,
+      createdAt: DateTime.tryParse(json['created_at'] as String? ?? '') ?? DateTime.now(),
+      actionUrl: json['action_url'] as String?,
+    );
+  }
+}

lib/features/notifications/providers/notification_provider.dart

@@ -0,0 +1,72 @@
+// lib/features/notifications/providers/notification_provider.dart
+
+import 'package:flutter/foundation.dart';
+import '../../../core/utils/error_utils.dart';
+import '../models/notification_model.dart';
+import '../services/notification_service.dart';
+
+class NotificationProvider extends ChangeNotifier {
+  final NotificationService _service = NotificationService();
+
+  List<NotificationModel> notifications = [];
+  int unreadCount = 0;
+  bool loading = false;
+  String? error;
+
+  /// Load full notification list.
+  Future<void> loadNotifications() async {
+    loading = true;
+    error = null;
+    notifyListeners();
+    try {
+      notifications = await _service.getNotifications();
+      unreadCount = notifications.where((n) => !n.isRead).length;
+    } catch (e) {
+      error = userFriendlyError(e);
+    } finally {
+      loading = false;
+      notifyListeners();
+    }
+  }
+
+  /// Lightweight count refresh (no full list fetch).
+  Future<void> refreshUnreadCount() async {
+    try {
+      unreadCount = await _service.getUnreadCount();
+      notifyListeners();
+    } catch (_) {
+      // Silently fail — badge just won't update
+    }
+  }
+
+  /// Mark single notification as read.
+  Future<void> markAsRead(int id) async {
+    try {
+      await _service.markAsRead(notificationId: id);
+      final idx = notifications.indexWhere((n) => n.id == id);
+      if (idx >= 0) {
+        notifications[idx].isRead = true;
+        unreadCount = notifications.where((n) => !n.isRead).length;
+        notifyListeners();
+      }
+    } catch (e) {
+      error = userFriendlyError(e);
+      notifyListeners();
+    }
+  }
+
+  /// Mark all as read.
+  Future<void> markAllAsRead() async {
+    try {
+      await _service.markAsRead(); // null = mark all
+      for (final n in notifications) {
+        n.isRead = true;
+      }
+      unreadCount = 0;
+      notifyListeners();
+    } catch (e) {
+      error = userFriendlyError(e);
+      notifyListeners();
+    }
+  }
+}

lib/features/notifications/services/notification_service.dart

@@ -0,0 +1,41 @@
+// lib/features/notifications/services/notification_service.dart
+
+import '../../../core/api/api_client.dart';
+import '../../../core/api/api_endpoints.dart';
+import '../models/notification_model.dart';
+
+class NotificationService {
+  final ApiClient _api = ApiClient();
+
+  /// Fetch notifications for current user (paginated).
+  Future<List<NotificationModel>> getNotifications({int page = 1, int pageSize = 20}) async {
+    final res = await _api.post(
+      ApiEndpoints.notificationList,
+      body: {'page': page, 'page_size': pageSize},
+    );
+    final rawList = res['notifications'] ?? res['data'] ?? [];
+    if (rawList is List) {
+      return rawList
+          .map((e) => NotificationModel.fromJson(Map<String, dynamic>.from(e as Map)))
+          .toList();
+    }
+    return [];
+  }
+
+  /// Mark a single notification as read, or all if [notificationId] is null.
+  Future<void> markAsRead({int? notificationId}) async {
+    final body = <String, dynamic>{};
+    if (notificationId != null) {
+      body['notification_id'] = notificationId;
+    } else {
+      body['mark_all'] = true;
+    }
+    await _api.post(ApiEndpoints.notificationMarkRead, body: body);
+  }
+
+  /// Get unread notification count (lightweight).
+  Future<int> getUnreadCount() async {
+    final res = await _api.post(ApiEndpoints.notificationCount);
+    return (res['unread_count'] as num?)?.toInt() ?? 0;
+  }
+}

lib/features/notifications/widgets/notification_bell.dart

@@ -0,0 +1,61 @@
+// lib/features/notifications/widgets/notification_bell.dart
+
+import 'package:flutter/material.dart';
+import 'package:provider/provider.dart';
+import '../providers/notification_provider.dart';
+import 'notification_panel.dart';
+
+class NotificationBell extends StatelessWidget {
+  const NotificationBell({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return Consumer<NotificationProvider>(
+      builder: (context, provider, _) {
+        return GestureDetector(
+          onTap: () => _showPanel(context),
+          child: Stack(
+            clipBehavior: Clip.none,
+            children: [
+              const Padding(
+                padding: EdgeInsets.all(8.0),
+                child: Icon(Icons.notifications_outlined, size: 26, color: Colors.black87),
+              ),
+              if (provider.unreadCount > 0)
+                Positioned(
+                  right: 4,
+                  top: 4,
+                  child: Container(
+                    padding: const EdgeInsets.symmetric(horizontal: 5, vertical: 2),
+                    decoration: BoxDecoration(
+                      color: Colors.red,
+                      borderRadius: BorderRadius.circular(10),
+                    ),
+                    constraints: const BoxConstraints(minWidth: 18, minHeight: 18),
+                    child: Text(
+                      provider.unreadCount > 99 ? '99+' : '${provider.unreadCount}',
+                      style: const TextStyle(color: Colors.white, fontSize: 10, fontWeight: FontWeight.w600),
+                      textAlign: TextAlign.center,
+                    ),
+                  ),
+                ),
+            ],
+          ),
+        );
+      },
+    );
+  }
+
+  void _showPanel(BuildContext context) {
+    context.read<NotificationProvider>().loadNotifications();
+    showModalBottomSheet(
+      context: context,
+      isScrollControlled: true,
+      backgroundColor: Colors.transparent,
+      builder: (_) => ChangeNotifierProvider.value(
+        value: context.read<NotificationProvider>(),
+        child: const NotificationPanel(),
+      ),
+    );
+  }
+}

lib/features/notifications/widgets/notification_panel.dart

@@ -0,0 +1,101 @@
+// lib/features/notifications/widgets/notification_panel.dart
+
+import 'package:flutter/material.dart';
+import 'package:provider/provider.dart';
+import '../providers/notification_provider.dart';
+import 'notification_tile.dart';
+
+class NotificationPanel extends StatelessWidget {
+  const NotificationPanel({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return DraggableScrollableSheet(
+      expand: false,
+      initialChildSize: 0.6,
+      minChildSize: 0.35,
+      maxChildSize: 0.95,
+      builder: (context, scrollController) {
+        return Container(
+          decoration: const BoxDecoration(
+            color: Colors.white,
+            borderRadius: BorderRadius.vertical(top: Radius.circular(24)),
+          ),
+          child: Column(
+            children: [
+              // Handle bar
+              Center(
+                child: Container(
+                  margin: const EdgeInsets.only(top: 12, bottom: 8),
+                  width: 48,
+                  height: 5,
+                  decoration: BoxDecoration(
+                    color: Colors.grey.shade300,
+                    borderRadius: BorderRadius.circular(3),
+                  ),
+                ),
+              ),
+              // Header
+              Padding(
+                padding: const EdgeInsets.symmetric(horizontal: 20, vertical: 8),
+                child: Row(
+                  mainAxisAlignment: MainAxisAlignment.spaceBetween,
+                  children: [
+                    const Text('Notifications', style: TextStyle(fontSize: 20, fontWeight: FontWeight.w700)),
+                    Consumer<NotificationProvider>(
+                      builder: (_, provider, __) {
+                        if (provider.unreadCount == 0) return const SizedBox.shrink();
+                        return TextButton(
+                          onPressed: provider.markAllAsRead,
+                          child: const Text('Mark all read', style: TextStyle(fontSize: 13)),
+                        );
+                      },
+                    ),
+                  ],
+                ),
+              ),
+              const Divider(height: 1),
+              // List
+              Expanded(
+                child: Consumer<NotificationProvider>(
+                  builder: (_, provider, __) {
+                    if (provider.loading) {
+                      return const Center(child: CircularProgressIndicator());
+                    }
+                    if (provider.notifications.isEmpty) {
+                      return Center(
+                        child: Column(
+                          mainAxisSize: MainAxisSize.min,
+                          children: [
+                            Icon(Icons.notifications_none, size: 56, color: Colors.grey.shade300),
+                            const SizedBox(height: 12),
+                            Text('No notifications yet', style: TextStyle(color: Colors.grey.shade500, fontSize: 15)),
+                          ],
+                        ),
+                      );
+                    }
+                    return ListView.separated(
+                      controller: scrollController,
+                      padding: const EdgeInsets.symmetric(vertical: 8),
+                      itemCount: provider.notifications.length,
+                      separatorBuilder: (_, __) => const Divider(height: 1, indent: 72),
+                      itemBuilder: (ctx, idx) {
+                        final notif = provider.notifications[idx];
+                        return NotificationTile(
+                          notification: notif,
+                          onTap: () {
+                            if (!notif.isRead) provider.markAsRead(notif.id);
+                          },
+                        );
+                      },
+                    );
+                  },
+                ),
+              ),
+            ],
+          ),
+        );
+      },
+    );
+  }
+}

lib/features/notifications/widgets/notification_tile.dart

@@ -0,0 +1,94 @@
+// lib/features/notifications/widgets/notification_tile.dart
+
+import 'package:flutter/material.dart';
+import '../models/notification_model.dart';
+
+class NotificationTile extends StatelessWidget {
+  final NotificationModel notification;
+  final VoidCallback? onTap;
+
+  const NotificationTile({Key? key, required this.notification, this.onTap}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return InkWell(
+      onTap: onTap,
+      child: Container(
+        color: notification.isRead ? Colors.transparent : const Color(0xFFF0F4FF),
+        padding: const EdgeInsets.symmetric(horizontal: 20, vertical: 14),
+        child: Row(
+          crossAxisAlignment: CrossAxisAlignment.start,
+          children: [
+            _buildIcon(),
+            const SizedBox(width: 14),
+            Expanded(
+              child: Column(
+                crossAxisAlignment: CrossAxisAlignment.start,
+                children: [
+                  Text(
+                    notification.title,
+                    style: TextStyle(
+                      fontWeight: notification.isRead ? FontWeight.w400 : FontWeight.w600,
+                      fontSize: 14,
+                    ),
+                    maxLines: 1,
+                    overflow: TextOverflow.ellipsis,
+                  ),
+                  const SizedBox(height: 4),
+                  Text(
+                    notification.message,
+                    style: TextStyle(color: Colors.grey.shade600, fontSize: 13),
+                    maxLines: 2,
+                    overflow: TextOverflow.ellipsis,
+                  ),
+                  const SizedBox(height: 6),
+                  Text(
+                    _timeAgo(notification.createdAt),
+                    style: TextStyle(color: Colors.grey.shade400, fontSize: 12),
+                  ),
+                ],
+              ),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+
+  Widget _buildIcon() {
+    final config = _typeConfig(notification.type);
+    return Container(
+      width: 40,
+      height: 40,
+      decoration: BoxDecoration(
+        color: config.color.withOpacity(0.15),
+        shape: BoxShape.circle,
+      ),
+      child: Icon(config.icon, color: config.color, size: 20),
+    );
+  }
+
+  static _TypeConfig _typeConfig(String type) {
+    switch (type) {
+      case 'event':   return _TypeConfig(Colors.blue, Icons.event);
+      case 'promo':   return _TypeConfig(Colors.green, Icons.local_offer);
+      case 'booking': return _TypeConfig(Colors.orange, Icons.confirmation_number);
+      default:        return _TypeConfig(Colors.grey, Icons.info_outline);
+    }
+  }
+
+  static String _timeAgo(DateTime dt) {
+    final diff = DateTime.now().difference(dt);
+    if (diff.inMinutes < 1) return 'Just now';
+    if (diff.inMinutes < 60) return '${diff.inMinutes}m ago';
+    if (diff.inHours < 24) return '${diff.inHours}h ago';
+    if (diff.inDays < 7) return '${diff.inDays}d ago';
+    return '${dt.day}/${dt.month}/${dt.year}';
+  }
+}
+
+class _TypeConfig {
+  final Color color;
+  final IconData icon;
+  const _TypeConfig(this.color, this.icon);
+}