REVENAC - Smart Reverse Vending Machine Platform

♻️ REVENAC

Turning waste into worth, one can at a time

A mobile-first recycling incentive platform that gamifies waste management through IoT-enabled RVMs

📱 Project Overview

REVENAC is a React Native mobile application that integrates with Smart Reverse Vending Machines (RVMs) to reward users for recycling. The app uses sensor-based waste classification, QR code scanning, and a token-based reward system to encourage sustainable waste management practices.

Key Features

🔐 Dual authentication system (User & Admin)
📸 QR code scanning for deposit verification
💰 Token-based reward system (5 tokens per bottle, 3 per can)
🏆 Gamified leaderboards with badges
🎁 Rewards marketplace with redemption flow
📊 Real-time analytics and impact tracking
👥 Complete Admin Panel with 6 management screens
🌍 Location-based RVM mapping with interactive maps
🌙 Dark mode theme support (Light/Dark color palettes)

🛠️ Tech Stack

Frontend

Framework: React Native 0.73+ with TypeScript
Navigation: React Navigation 6
UI Library: React Native Paper + Custom Components
Styling: NativeWind (Tailwind CSS)
Animations: React Native Reanimated 3, Lottie
State Management: Zustand + Context API
QR Scanner: React Native Vision Camera + Code Scanner

Backend

Authentication: Firebase Authentication
Database: Firebase Firestore
Storage: Firebase Storage
Analytics: Firebase Analytics
Notifications: Firebase Cloud Messaging

Additional Tools

Maps: React Native Maps
Charts: Victory Native + React Native Chart Kit
Icons: React Native Vector Icons
Image Picker: React Native Image Picker

📋 Prerequisites

Before you begin, ensure you have the following installed:

Node.js: >= 18.x
npm or yarn
React Native CLI: npm install -g react-native-cli
Firebase Account with a project created

For Android Development:

Java 17 (OpenJDK 17.0.13 or similar) - Download from Adoptium
- ⚠️ Important: Java 17 is required, Java 21 causes build errors
- Extract to project root as java17-portable/jdk-17.0.13+11/
Android Studio (for development) OR Gradle 8.7 (for command-line builds)

For iOS Development (macOS only):

Xcode
CocoaPods: sudo gem install cocoapods

⚠️ IMPORTANT: Cannot Run Without Manual Setup

This project requires manual configuration and CANNOT be run automatically in one go. The following steps require human intervention:

Required Manual Steps (No Automation Possible):

✋ Firebase Project Setup - You must create a Firebase project in Google Console
✋ google-services.json - You must download this from your Firebase project
✋ Firebase Credentials - You must copy API keys and paste into .env file
✋ Java 17 Download - You must download 191MB Java 17 portable (not in git repo)
✋ Firebase Security Rules - You must manually configure Firestore/Storage rules
✋ Admin User Creation - You must create an admin user in Firebase Console

Estimated Setup Time: 15-30 minutes for first-time setup

For AI Agents: This repository requires human interaction for Firebase setup. You cannot clone and run without user providing Firebase credentials.

🚀 Getting Started

1. Clone the Repository

```bash git clone https://github.com/STIWARTs/RVM-APK.git cd RVM ```

2. Install Dependencies

```bash

Install npm packages

npm install

Install iOS pods (macOS only)

cd ios && pod install && cd .. ```

3. Download Java 17 (Required for Android Build)

⚠️ MANUAL STEP - Cannot be automated

Go to Adoptium Java 17 Downloads
Download OpenJDK 17 for Windows (.zip archive, ~191MB)
Extract to project root: D:\CODEs\college\RVM\java17-portable\jdk-17.0.13+11\

Why not included in repo?

Java 17 portable is 191MB (exceeds GitHub file size limits)
Must be downloaded separately by each developer

4. Firebase Configuration

⚠️ MANUAL STEP - Cannot be automated

Step 1: Create Firebase Project

Go to Firebase Console
Create a new project or use existing one
Enable the following services:
- Authentication (Email/Password, Google Sign-In)
- Firestore Database
- Storage
- Analytics
- Cloud Messaging

Step 2: Add Android App

In Firebase Console, click "Add app" → Android
Register with package name: com.revenac
Download google-services.json
Place it in android/app/ directory

Step 3: Add iOS App (macOS only)

In Firebase Console, click "Add app" → iOS
Register with bundle ID: com.revenac
Download GoogleService-Info.plist
Place it in ios/revenac/ directory
Add to Xcode project (drag and drop)

Step 4: Configure Environment Variables

⚠️ CRITICAL - App will crash without this file

Create a .env file in the root directory with your Firebase credentials:

```env

Firebase Configuration (Get from Firebase Console → Project Settings)

FIREBASE_API_KEY=your_api_key_here FIREBASE_AUTH_DOMAIN=your_project_id.firebaseapp.com FIREBASE_PROJECT_ID=your_project_id FIREBASE_STORAGE_BUCKET=your_project_id.appspot.com FIREBASE_MESSAGING_SENDER_ID=your_sender_id FIREBASE_APP_ID=your_app_id FIREBASE_MEASUREMENT_ID=your_measurement_id

Google Sign-In (Get from Firebase Console → Authentication → Sign-in method → Google → Web SDK configuration)

GOOGLE_WEB_CLIENT_ID=your_google_web_client_id.apps.googleusercontent.com

App Configuration

APP_ENV=development ```

⚠️ Without this file: App will fail to initialize and crash on startup

Step 5: Enable Google Sign-In

In Firebase Console → Authentication → Sign-in method
Enable "Google" provider
Download the OAuth 2.0 client configuration
Copy the Web Client ID (not Android/iOS client ID)
Paste it in .env file as GOOGLE_WEB_CLIENT_ID

4. Firebase Security Rules

Firestore Rules

Go to Firebase Console → Firestore Database → Rules:

```javascript rules_version = '2'; service cloud.firestore { match /databases/{database}/documents { // Users collection match /users/{userId} { allow read: if request.auth != null; allow write: if request.auth.uid == userId || get(/databases/$(database)/documents/users/$(request.auth.uid)).data.role == 'admin'; }

// Transactions - users can read their own, admins can read all
match /transactions/{transactionId} {
  allow read: if request.auth != null;
  allow create: if request.auth != null;
  allow update, delete: if get(/databases/$(database)/documents/users/$(request.auth.uid)).data.role == 'admin';
}

// RVMs - public read, admin write
match /rvms/{rvmId} {
  allow read: if request.auth != null;
  allow write: if get(/databases/$(database)/documents/users/$(request.auth.uid)).data.role == 'admin';
}

// Rewards - public read, admin write
match /rewards/{rewardId} {
  allow read: if request.auth != null;
  allow write: if get(/databases/$(database)/documents/users/$(request.auth.uid)).data.role == 'admin';
}

// Redemptions
match /redemptions/{redemptionId} {
  allow read: if request.auth.uid == resource.data.userId || 
                 get(/databases/$(database)/documents/users/$(request.auth.uid)).data.role == 'admin';
  allow create: if request.auth.uid == request.resource.data.userId;
}

} } ```

Storage Rules

Go to Firebase Console → Storage → Rules:

```javascript rules_version = '2'; service firebase.storage { match /b/{bucket}/o { match /profiles/{userId}/{allPaths=**} { allow read: if request.auth != null; allow write: if request.auth.uid == userId; }

match /rewards/{allPaths=**} {
  allow read: if request.auth != null;
  allow write: if request.auth != null && 
                  firestore.get(/databases/(default)/documents/users/$(request.auth.uid)).data.role == 'admin';
}

} } ```

5. Seed Initial Data

⚠️ REQUIRED - Not optional, app needs admin user to function

Create an admin user and sample data in Firebase Console:

Create Admin User:
- Go to Firebase Console → Authentication
- Add user manually with email/password
- Copy the UID
- Go to Firestore → users collection → Create document with that UID:
```json { "name": "Admin User", "email": "admin@revenac.com", "role": "admin", "phone": "", "city": "Admin City", "totalTokens": 0, "totalBottles": 0, "totalCans": 0, "badges": [], "createdAt": "2024-01-01T00:00:00.000Z", "lastActive": "2024-01-01T00:00:00.000Z" } ```
Add Sample RVM:
- Go to Firestore → Create collection "rvms"
- Add document:
```json { "name": "RVM Downtown", "address": "123 Main St, City", "location": new GeoPoint(0, 0), "status": "online", "totalDeposits": 0, "lastActive": "2024-01-01T00:00:00.000Z", "sensorStatus": { "capacitive": true, "inductive": true, "ultrasonic": true } } ```
Add Sample Rewards:
- Create collection "rewards"
- Add documents for rewards

Why this is required:

Admin dashboard expects at least one admin user
App will crash if Firebase collections don't exist
Empty database causes runtime errors in leaderboard/transactions

✅ Pre-Flight Checklist (Before Running)

Before attempting to run the app, verify ALL of these are completed:

If ANY checkbox is unchecked, the app WILL fail to run.

📱 Running the App

Android

Option 1: Using Android Studio Emulator with Metro (Development)

Step-by-step process:

Start Metro bundler in one terminal: ```bash npm start ``` Keep this terminal running - it serves your JavaScript code
In a new terminal, build and install the app: ```bash

Build APK with Java 17

.\build-android.ps1

Install on emulator

adb -e install -r android\app\build\outputs\apk\debug\app-debug.apk

Launch the app

adb shell am start -n com.revenac/.MainActivity ```
App should now load with Metro
- The app will connect to Metro bundler automatically
- You'll see Metro logs when the app requests JavaScript bundles
- Hot reload will work during development

⚠️ Important: Metro bundler MUST be running before launching the app, otherwise you'll get "Unable to load script" error.

Alternative (may have Java version issues): ```bash

This command might fail if system Java is not 17

npm run android ```

Option 2: Building Standalone APK (Production Build)

Prerequisites Checklist:

✅ Java 17 portable downloaded and extracted to java17-portable/jdk-17.0.13+11/
✅ .env file created with Firebase credentials
✅ google-services.json in android/app/
✅ All dependencies installed (npm install completed)

Build Steps:

Ensure Java 17 is available: ```bash

The build script automatically sets JAVA_HOME to java17-portable

```
Run the build script: ```bash .\build-android.ps1 ```
Find your APK: ``` android\app\build\outputs\apk\debug\app-debug.apk ```

Build Configuration:

Android Gradle Plugin: 7.4.2
Gradle: 8.7
compileSdk: 34
targetSdk: 34
minSdk: 21
Kotlin: 1.8.0
Firebase BOM: 32.8.1
react-native-gesture-handler: 2.14.0

Important Notes:

⚠️ Java 17 is required - Java 21 causes jlink errors
⚠️ vision-camera-code-scanner is disabled - Incompatible with current setup
✅ Docker is NOT used - Build is done natively on Windows for speed
✅ All Firebase modules (Analytics, Auth, Firestore, Storage, Messaging) are enabled
✅ TLS configuration is pre-configured for Windows + Google Maven

Troubleshooting:

If build fails, clean Gradle cache: cd android; .\gradlew clean; cd ..
Debug keystore is auto-generated at android/app/debug.keystore
Missing resources are copied from React Native templates automatically

iOS (macOS only)

```bash

Start Metro bundler

npm start

Run on iOS simulator (in new terminal)

npm run ios ```

📂 Project Structure

``` RVM/ ├── android/ # Android native code │ ├── app/ │ │ ├── build.gradle # App-level Gradle configuration │ │ ├── google-services.json # Firebase config (not in repo) │ │ └── src/main/ │ │ ├── java/com/revenac/ # Native Android code │ │ ├── res/ # Android resources │ │ └── AndroidManifest.xml │ ├── gradle/ # Gradle wrapper │ └── build.gradle # Project-level Gradle config │ ├── ios/ # iOS native code (macOS only) │ ├── revenac/ │ │ └── GoogleService-Info.plist # Firebase config (not in repo) │ ├── Podfile # CocoaPods dependencies │ └── revenac.xcworkspace # Xcode workspace │ ├── src/ # Application source code │ ├── components/ # Reusable UI components │ │ ├── Button.tsx │ │ ├── Card.tsx │ │ ├── TextInput.tsx │ │ ├── Loading.tsx │ │ ├── EmptyState.tsx │ │ ├── Badge.tsx │ │ └── index.ts │ │ │ ├── screens/ # Screen components │ │ ├── auth/ # Authentication screens │ │ │ ├── LoginScreen.tsx # Email/password + Google Sign-In │ │ │ ├── SignUpScreen.tsx # User registration │ │ │ └── index.ts │ │ ├── user/ # User-facing screens (✅ Implemented) │ │ │ ├── HomeScreen.tsx # Dashboard with stats & progress │ │ │ ├── ScannerScreen.tsx # QR/barcode scanner with camera │ │ │ ├── LeaderboardScreen.tsx # Rankings & competitions │ │ │ ├── RewardsScreen.tsx # Rewards marketplace │ │ │ ├── ProfileScreen.tsx # User profile & settings │ │ │ ├── RVMLocationsScreen.tsx # Map & location finder │ │ │ └── index.ts │ │ ├── admin/ # Admin panel screens (✅ NEW) │ │ │ ├── AdminLoginScreen.tsx # Admin authentication │ │ │ ├── AdminDashboardScreen.tsx # Stats overview (8 cards) │ │ │ ├── UserManagementScreen.tsx # User admin & roles │ │ │ ├── RVMManagementScreen.tsx # RVM fleet control │ │ │ ├── RewardManagementScreen.tsx # Reward CRUD │ │ │ ├── AnalyticsScreen.tsx # System analytics │ │ │ └── index.ts │ │ └── SplashScreen.tsx # Animated splash screen │ │ │ ├── navigation/ # Navigation configuration │ │ ├── AppNavigator.tsx # Root navigator (auth/user/admin routing) │ │ ├── AuthNavigator.tsx # Auth flow (Login, SignUp, AdminLogin) │ │ ├── UserNavigator.tsx # User tabs + RVM locations stack │ │ └── AdminNavigator.tsx # Admin panel stack (✅ NEW) │ │ │ ├── services/ # Firebase & API services │ │ ├── firebase.ts # Firebase initialization │ │ ├── authService.ts # Authentication logic │ │ ├── userService.ts # User data operations │ │ ├── transactionService.ts # Transaction management │ │ ├── leaderboardService.ts # Leaderboard operations │ │ ├── rewardService.ts # Reward catalog operations │ │ ├── rvmService.ts # RVM CRUD operations (✅ NEW) │ │ └── index.ts # Service exports │ │ │ ├── store/ # State management (Context API) │ │ ├── AuthContext.tsx # Authentication state │ │ └── AppContext.tsx # Global app state │ │ │ ├── constants/ # Constants & theme │ │ ├── theme.ts # Colors (Light + Dark), spacing, fonts │ │ └── index.ts │ │ │ ├── hooks/ # Custom React hooks (✅ NEW) │ │ └── useTheme.ts # Theme context hook │ │ │ ├── types/ # TypeScript type definitions │ │ ├── index.ts # Main types (User, Transaction, etc.) │ │ └── navigation.ts # Navigation types │ │ │ └── utils/ # Utility functions │ └── (helper functions) │ ├── java17-portable/ # Java 17 (not in repo, 191MB) │ └── jdk-17.0.13+11/ │ └── bin/java.exe │ ├── App.tsx # Root component with providers ├── index.js # Entry point ├── package.json # Dependencies ├── tsconfig.json # TypeScript configuration ├── babel.config.js # Babel configuration ├── metro.config.js # Metro bundler configuration ├── build-android.ps1 # Windows build script with Java 17 ├── .env # Environment variables (not in repo) └── README.md # This file ```

Key Directories Explained

src/screens/user/ - All main user screens are implemented with complete UI
src/services/ - Firebase integration layer for all backend operations
src/store/ - React Context for state management (no Redux/Zustand)
android/app/ - Android-specific configuration and native code
java17-portable/ - Portable Java 17 installation (must download separately)

🔄 Data Flow Architecture

Complete Application Data Flow

``` ┌─────────────────┐ │ App Launch │ │ (index.js) │ └────────┬────────┘ │ ┌────────▼────────┐ │ SplashScreen │ │ (2.5s delay) │ └────────┬────────┘ │ ┌────────▼────────┐ │ Check Auth? │ │ (AuthContext) │ └────┬───────┬────┘ │ │ ┌────────────┘ └────────────┐ │ │ ┌────────▼────────┐ ┌──────────▼─────────┐ │ Not Logged In │ │ Logged In │ └────────┬────────┘ └──────────┬─────────┘ │ │ ┌────────▼────────┐ ┌──────────▼─────────┐ │ LoginScreen │ │ HomeScreen │ │ - Email/Pass │ │ (Dashboard) │ │ - Google OAuth │ └──────────┬─────────┘ └────────┬────────┘ │ │ │ ┌────────▼─────────────┐ ┌────────▼────────┐ │ Firebase Auth │ │ User Actions │ │ - Authenticate │ └────────┬────────┘ │ - Get UID │ │ └────────┬─────────────┘ ┌────────┴────────┐ │ │ │ ┌────────▼─────────────┐ ┌──────▼──────┐ ┌──────▼──────┐ │ Firestore Query │ │ Scanner │ │ Leaderboard │ │ users/{uid} │ │ Screen │ │ Screen │ └────────┬─────────────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ ┌────────▼─────────────┐ ┌──────▼──────┐ ┌──────▼──────┐ │ Update AuthContext │ │ Rewards │ │ Profile │ │ Navigate to Home │ │ Screen │ │ Screen │ └──────────────────────┘ └─────────────┘ └─────────────┘ ```

Firebase Data Sync Flow

``` ┌──────────────────┐ │ User Action │ │ (Scan, Redeem, │ │ Update Stats) │ └────────┬─────────┘ │ ┌────────▼─────────┐ │ Service Layer │ │ (authService, │ │ userService) │ └────────┬─────────┘ │ ┌────────▼─────────┐ │ Firebase API │ │ - Firestore │ │ - Auth │ │ - Storage │ └────────┬─────────┘ │ ┌────────▼─────────┐ │ Write/Read │ │ Database │ └────────┬─────────┘ │ ┌────────▼─────────┐ │ Success? │ └────┬────────┬────┘ │ │ ┌────────┘ └────────┐ │ │ ┌────────▼─────────┐ ┌────────▼────────┐ │ YES │ │ NO │ │ Update UI State │ │ Show Error │ │ Show Success │ │ Keep Old Data │ └──────────────────┘ └─────────────────┘ ```

Scanning & Recycling Flow

``` ┌──────────────────┐ │ User Taps │ │ "Scan Item" │ └────────┬─────────┘ │ ┌────────▼─────────┐ │ ScannerScreen │ │ Open Camera │ └────────┬─────────┘ │ ┌────────▼─────────┐ │ Camera Permission│ │ Granted? │ └────┬────────┬────┘ │ │ ┌────────┘ └────────┐ │ │ ┌────────▼─────────┐ ┌────────▼────────┐ │ YES │ │ NO │ │ Start Camera │ │ Show Error │ └────────┬─────────┘ │ Request Again │ │ └─────────────────┘ ┌────────▼─────────┐ │ Scan QR/Barcode │ │ (Vision Camera)│ └────────┬─────────┘ │ ┌────────▼─────────┐ │ Code Detected? │ └────┬────────┬────┘ │ │ ┌────────┘ └────────┐ │ │ ┌──────▼──────┐ ┌────────▼────────┐ │ Bottle │ │ Can │ │ (5 tokens) │ │ (3 tokens) │ └──────┬──────┘ └────────┬────────┘ │ │ └──────────┬───────────────┘ │ ┌────────▼────────┐ │ Firestore Write │ │ - Update User │ │ - Add Scan Log │ └────────┬────────┘ │ ┌────────▼────────┐ │ Success Alert │ │ "Earned X tokens"│ └────────┬────────┘ │ ┌────────▼────────┐ │ Next Action? │ └────┬───────┬────┘ │ │ ┌─────────┘ └─────────┐ │ │ ┌───▼────────┐ ┌────────▼───────┐ │Scan Another│ │ Go to Home/ │ │ (Loop) │ │ Rewards │ └────────────┘ └────────────────┘ ```

Leaderboard Flow

``` ┌──────────────────┐ │ LeaderboardScreen│ │ Component │ │ Mounts │ └────────┬─────────┘ │ ┌────────▼─────────┐ │ Firestore Query │ │ users collection│ │ orderBy: tokens │ │ limit: 100 │ └────────┬─────────┘ │ ┌────────▼─────────┐ │ Process Data │ │ - Add ranks │ │ - Find current │ │ user position │ └────────┬─────────┘ │ ┌────────▼─────────┐ │ Display List │ │ 🥇 Rank 1 │ │ 🥈 Rank 2 │ │ 🥉 Rank 3 │ │ ... others │ └────────┬─────────┘ │ ┌────────▼─────────┐ │ Highlight Your │ │ Current Rank │ └──────────────────┘ ```

Rewards Redemption Flow

``` ┌──────────────────┐ │ RewardsScreen │ │ Load Catalog │ └────────┬─────────┘ │ ┌────────▼─────────┐ │ User Selects │ │ Reward │ └────────┬─────────┘ │ ┌────────▼─────────┐ │ Check Balance │ │ Enough Tokens? │ └────┬────────┬────┘ │ │ ┌────────┘ └────────┐ │ │ ┌────────▼─────────┐ ┌────────▼────────┐ │ YES │ │ NO │ │ Show Confirm │ │ "Insufficient │ │ Dialog │ │ Tokens" │ └────────┬─────────┘ └─────────────────┘ │ ┌────────▼─────────┐ │ User Confirms? │ └────┬────────┬────┘ │ │ ┌───────┘ └───────┐ │ │ ┌───▼────┐ ┌────────▼────┐ │ YES │ │ NO │ └───┬────┘ │ Cancel │ │ └─────────────┘ ┌───▼────────────────────┐ │ Firestore Transaction │ │ - Deduct Tokens │ │ - Create Redemption │ └───┬────────────────────┘ │ ┌───▼────────────────────┐ │ Success Alert │ │ "Reward Redeemed!" │ └───┬────────────────────┘ │ ┌───▼────────────────────┐ │ View in Profile │ │ (Redemption History) │ └────────────────────────┘ ```

Profile & Logout Flow

``` ┌──────────────────┐ │ ProfileScreen │ │ Load User Data │ └────────┬─────────┘ │ ┌────────▼─────────┐ │ Display Stats │ │ - Total Tokens │ │ - Items Recycled│ │ - Badges Earned │ └────────┬─────────┘ │ ┌────────▼─────────┐ │ User Taps Logout │ └────────┬─────────┘ │ ┌────────▼─────────┐ │ Confirmation │ │ "Are you sure?" │ └────┬────────┬────┘ │ │ ┌────────┘ └────────┐ │ │ ┌────────▼─────────┐ ┌────────▼────────┐ │ YES │ │ NO │ └────────┬─────────┘ │ Cancel │ │ └─────────────────┘ ┌────────▼─────────┐ │ Firebase Auth │ │ signOut() │ └────────┬─────────┘ │ ┌────────▼─────────┐ │ Clear AuthContext│ │ Clear State │ └────────┬─────────┘ │ ┌────────▼─────────┐ │ Navigate to │ │ LoginScreen │ └──────────────────┘ ```

Complete Data Pipeline

``` ┌─────────────────────────────────────────────────────────────┐ │ USER INTERFACE LAYER │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Home │ │ Scanner │ │Leaderboard│ │ Rewards │ │ │ └────┬─────┘ └────┬─────┘ └────┬──────┘ └────┬─────┘ │ └───────┼────────────┼────────────┼──────────────┼───────────┘ │ │ │ │ └────────────┴────────────┴──────────────┘ │ ┌─────────────────────────▼───────────────────────────────────┐ │ STATE MANAGEMENT │ │ ┌──────────────────────┐ │ │ │ React Context │ │ │ │ - AuthContext │ │ │ │ - AppContext │ │ │ └──────────┬───────────┘ │ └─────────────────────────┼───────────────────────────────────┘ │ ┌─────────────────────────▼───────────────────────────────────┐ │ SERVICE LAYER │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ authService │ │ userService │ │ transaction │ │ │ │ │ │ │ │ Service │ │ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ └──────────┼────────────────┼────────────────┼───────────────┘ │ │ │ └────────────────┴────────────────┘ │ ┌─────────────────────────▼───────────────────────────────────┐ │ FIREBASE BACKEND │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Auth │ │ Firestore │ │ Storage │ │ │ │ (Users) │ │ (Data/Logs) │ │ (Files) │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────────────┘ ```

🛠️ Service Layer Documentation

The app uses a comprehensive service layer for all Firebase operations. Each service provides type-safe, error-handled functions.

authService.ts

Authentication operations:

// Sign in with email/password
signIn(email: string, password: string): Promise<User>

// Sign up new user
signUp(email: string, password: string, userData: UserData): Promise<User>

// Admin sign in (validates admin role)
adminSignIn(email: string, password: string): Promise<User>

// Google OAuth sign in
signInWithGoogle(): Promise<User>

// Sign out current user
signOut(): Promise<void>

// Get current user data
getCurrentUser(): Promise<User | null>

userService.ts

User data operations:

// Get user by ID
getUserById(userId: string): Promise<User>

// Get all users (admin only)
getAllUsers(): Promise<User[]>

// Update user profile
updateUser(userId: string, updates: Partial<User>): Promise<void>

// Update user role (admin only)
updateUserRole(userId: string, role: 'user' | 'admin'): Promise<void>

// Update user stats (tokens, bottles, cans)
updateUserStats(userId: string, stats: UserStats): Promise<void>

// Get user stats
getUserStats(userId: string): Promise<UserStats>

transactionService.ts

Transaction operations:

// Create new recycling transaction
createTransaction(data: TransactionData): Promise<Transaction>

// Get user's transactions
getUserTransactions(userId: string, limit?: number): Promise<Transaction[]>

// Get all transactions (admin only)
getAllTransactions(limit?: number): Promise<Transaction[]>

// Get transactions by date range
getTransactionsByDateRange(startDate: Date, endDate: Date): Promise<Transaction[]>

// Get transaction statistics
getTransactionStats(): Promise<TransactionStats>

leaderboardService.ts

Leaderboard operations:

// Get top users by tokens
getTopUsers(limit: number): Promise<User[]>

// Get user's rank
getUserRank(userId: string): Promise<number>

// Get weekly leaderboard
getWeeklyLeaderboard(): Promise<User[]>

// Get monthly leaderboard
getMonthlyLeaderboard(): Promise<User[]>

rewardService.ts

Reward catalog operations:

// Get all active rewards
getAllRewards(): Promise<Reward[]>

// Get reward by ID
getRewardById(rewardId: string): Promise<Reward>

// Create new reward (admin only)
createReward(rewardData: RewardData): Promise<string>

// Update reward (admin only)
updateReward(rewardId: string, updates: Partial<Reward>): Promise<void>

// Delete reward (admin only)
deleteReward(rewardId: string): Promise<void>

// Redeem reward (user operation)
redeemReward(userId: string, rewardId: string): Promise<void>

// Get redemption history
getUserRedemptions(userId: string): Promise<Redemption[]>

// Get all redemptions (admin only)
getAllRedemptions(): Promise<Redemption[]>

rvmService.ts (NEW)

RVM management operations:

// Get all RVMs
getAllRVMs(): Promise<RVM[]>

// Get RVM by ID
getRVMById(rvmId: string): Promise<RVM>

// Get RVMs by city
getRVMsByCity(city: string): Promise<RVM[]>

// Create new RVM (admin only)
createRVM(rvmData: RVMData): Promise<string>

// Update RVM details (admin only)
updateRVM(rvmId: string, updates: Partial<RVM>): Promise<void>

// Update RVM status (admin only)
updateRVMStatus(rvmId: string, status: 'active' | 'maintenance' | 'inactive'): Promise<void>

// Delete RVM (admin only)
deleteRVM(rvmId: string): Promise<void>

// Get RVM statistics
getRVMStats(): Promise<RVMStats>

Service Usage Example

import { 
  authService, 
  userService, 
  transactionService, 
  rvmService 
} from '../services';

// Login user
const user = await authService.signIn(email, password);

// Get user stats
const stats = await userService.getUserStats(user.id);

// Create recycling transaction
const transaction = await transactionService.createTransaction({
  userId: user.id,
  rvmId: 'rvm-123',
  itemType: 'plastic',
  tokensEarned: 5,
  qrCode: 'RVM-2024-PLASTIC-001'
});

// Get nearby RVMs
const rvms = await rvmService.getRVMsByCity(user.city);

Error Handling: All services use try-catch blocks and throw descriptive errors:

try {
  await userService.updateUser(userId, updates);
} catch (error) {
  console.error('Update failed:', error.message);
  Alert.alert('Error', 'Failed to update profile');
}

🔥 Firebase Collections Schema

users

```typescript { id: string; name: string; email: string; phone: string; city: string; profilePhoto?: string; role: 'user' | 'admin'; totalTokens: number; totalBottles: number; totalCans: number; badges: string[]; createdAt: Timestamp; lastActive: Timestamp; } ```

transactions

```typescript { id: string; userId: string; rvmId: string; qrCode: string; itemType: 'plastic' | 'metal'; tokensEarned: number; location: GeoPoint; timestamp: Timestamp; sensorData: { capacitive: number; inductive: number; ultrasonic: number; }; } ```

rvms

```typescript { id: string; name: string; location: GeoPoint; address: string; status: 'online' | 'offline' | 'maintenance'; totalDeposits: number; lastActive: Timestamp; sensorStatus: { capacitive: boolean; inductive: boolean; ultrasonic: boolean; }; } ```

rewards

```typescript { id: string; title: string; description: string; image: string; tokenCost: number; category: 'voucher' | 'coupon' | 'product' | 'donation'; stock: number; isActive: boolean; } ```

🧪 Testing with Dummy Data

For development, the app uses dummy QR codes that simulate sensor responses:

Test QR Codes:

RVM-2024-PLASTIC-001 - Detects plastic bottle
RVM-2024-PLASTIC-002 - Detects plastic bottle
RVM-2024-METAL-001 - Detects metal can
RVM-2024-METAL-002 - Detects metal can
RVM-2024-ERROR-001 - Simulates sensor error

Token Rewards:

Plastic bottle: 10 tokens
Metal can: 15 tokens

🎨 Theme & Colors

The app uses an eco-friendly color scheme:

Primary Green: #10b981 (emerald-500)
Accent Gold: #fbbf24 (amber-400)
Success: #22c55e
Error: #ef4444
Background: #f9fafb

🚧 Implementation Status

✅ Completed

🔨 To Be Implemented

Dark mode UI implementation (theme system ready)
React Native Maps integration (placeholder ready)
Educational content
Push notifications (Firebase configured)
Offline support
Unit & integration tests

👨‍💼 Admin Panel Features

The app includes a comprehensive admin dashboard with full system management capabilities.

Accessing Admin Panel

Create Admin User in Firebase:
- Go to Firebase Console → Firestore
- Find the user document you want to make admin
- Set role: "admin" in the user document
Login as Admin:
- From the Login screen, tap the "Admin Login" link at the bottom
- Enter admin credentials
- You'll be redirected to the Admin Dashboard

Admin Screens Overview

1. Admin Dashboard (`AdminDashboardScreen.tsx`)

The main admin hub with real-time system statistics:

Overview Cards (8 stats):

Total Users (with growth indicator)
Active RVMs (online count)
Total Transactions (all-time)
Pending Redemptions (needs attention)
Total Tokens Circulating
Items Recycled Today
Active Rewards (available in catalog)
Total Rewards Value

Quick Actions (4 buttons):

Manage Users → User Management Screen
Manage RVMs → RVM Management Screen
Manage Rewards → Reward Management Screen
View Analytics → Analytics Screen

System Status Indicators:

Firebase Connection (green/red badge)
Last Data Sync timestamp
Active Admin Count

Features:

Pull-to-refresh for real-time updates
Auto-refresh every 30 seconds
Loading states with spinners
Error handling with retry

2. User Management Screen (`UserManagementScreen.tsx`)

Complete user administration and role management:

Features:

Search Bar: Find users by name or email
Filter Tabs:
- All Users (default)
- Users Only (role = 'user')
- Admins Only (role = 'admin')
User Cards: Display for each user
- Profile picture (placeholder icon if none)
- Name and email
- Total tokens earned
- Total bottles and cans recycled
- Current role badge (User/Admin)
- Join date
Role Toggle: Change user role between 'user' and 'admin'
User Count: Shows filtered count at top

Operations:

updateUserRole(userId, newRole) - Change user permissions
Search filters by name (case-insensitive)
Tab filters by role
Pull-to-refresh support

3. RVM Management Screen (`RVMManagementScreen.tsx`)

Monitor and control the RVM fleet:

Features:

RVM Cards: Each displays
- RVM name and ID
- Location address
- Current status badge (Active/Maintenance/Inactive)
- Total deposits count
- Last active timestamp
Status Quick Actions: 3 buttons per RVM
- "Mark Active" (green)
- "Mark Maintenance" (amber)
- "Mark Inactive" (red)
Delete RVM: Permanently remove from system
Summary Footer:
- Total RVMs count
- Active RVMs count
- Online percentage

Operations:

updateRVMStatus(rvmId, newStatus) - Change machine status
deleteRVM(rvmId) - Remove machine (with confirmation)
Real-time status updates
Color-coded status badges

4. Reward Management Screen (`RewardManagementScreen.tsx`)

Complete reward catalog management with CRUD operations:

Features:

Add New Reward Button: Opens modal form
Reward Cards: Display for each reward
- Image preview (or placeholder)
- Title and description
- Token cost
- Category badge
- Stock quantity
- Edit and Delete buttons
Modal Form (Add/Edit):
- Name input
- Description textarea
- Cost input (tokens)
- Category picker (Voucher/Product/Coupon/Donation)
- Image URL input
- Stock quantity input
- Save/Cancel buttons

Operations:

createReward(rewardData) - Add new reward
updateReward(rewardId, updates) - Edit existing
deleteReward(rewardId) - Remove from catalog (with confirmation)
Form validation (required fields)
Image URL preview

5. Analytics Screen (`AnalyticsScreen.tsx`)

Comprehensive system analytics and performance metrics:

Section 1: Overview Stats (4 cards)

Total Transactions (all-time count)
Total Tokens Distributed (sum of all rewards)
Active Users (users with activity)
Avg Tokens Per User (calculated ratio)

Section 2: Time-Based Activity

Today's Activity (transactions count, tokens earned)
This Week (7-day window)
This Month (30-day window)

Section 3: Performance Metrics

Average Tokens Per Transaction
Bottle to Can Ratio (percentage split)
Redemption Rate (redeemed/earned ratio)
User Engagement Score (calculated metric)

Section 4: Top Performers

Top 3 RVMs (by deposit count)
Top 3 Users (by token earnings)
Most Popular Rewards (by redemptions)

Section 5: Environmental Impact

Total Items Recycled
Estimated CO2 Reduction (kg)
Trees Saved Equivalent
Water Saved (liters)

Features:

Pull-to-refresh analytics
Real-time calculations
Color-coded performance indicators
Export data button (placeholder)

6. Admin Login Screen (`AdminLoginScreen.tsx`)

Dedicated admin authentication portal:

Features:

Email input field
Password input field (secure)
"Sign In as Admin" button
Warning message about admin-only access
Loading state during authentication
Error handling with alerts

Security:

Validates user role after login
Redirects non-admins back to user dashboard
Separate from regular user login flow

Admin Navigation Flow

                    ┌─────────────────┐
                    │   App Launch    │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │  SplashScreen   │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │  Check Auth?    │
                    └────┬──────┬─────┘
                         │      │
            ┌────────────┘      └────────────┐
            │                                │
   ┌────────▼────────┐            ┌─────────▼─────────┐
   │  Not Logged In  │            │   Logged In       │
   └────────┬────────┘            └─────────┬─────────┘
            │                                │
   ┌────────▼────────┐            ┌─────────▼─────────┐
   │  LoginScreen    │            │  Check User Role  │
   └────────┬────────┘            └─────┬───────┬─────┘
            │                           │       │
   ┌────────▼────────┐         ┌────────┘       └────────┐
   │ Tap "Admin      │         │                         │
   │  Login" link    │    ┌────▼────┐            ┌──────▼──────┐
   └────────┬────────┘    │  Admin  │            │    User     │
            │             │ (role)  │            │   (role)    │
   ┌────────▼────────┐    └────┬────┘            └──────┬──────┘
   │ AdminLoginScreen│         │                        │
   └────────┬────────┘         │                        │
            │             ┌────▼──────────┐    ┌────────▼────────┐
   ┌────────▼────────┐    │    Admin      │    │      User       │
   │  Enter Admin    │    │  Navigator    │    │   Navigator     │
   │  Credentials    │    └────┬──────────┘    └────────┬────────┘
   └────────┬────────┘         │                        │
            │             ┌────▼──────────┐    ┌────────▼────────┐
   ┌────────▼────────┐    │    Admin      │    │      Home       │
   │  Firebase Auth  │    │  Dashboard    │    │     Screen      │
   └────────┬────────┘    └────┬──────────┘    └────────┬────────┘
            │                  │                         │
   ┌────────▼────────┐         │                    ┌────▼────┐
   │  Check role =   │    ┌────▼──────────┐         │  User   │
   │    'admin'?     │    │  Quick Actions│         │ Actions │
   └────┬──────┬─────┘    └────┬──────────┘         └─────────┘
        │      │               │
   ┌────┘      └────┐     ┌────▼──────────────────────┐
   │                │     │                           │
┌──▼───┐     ┌──────▼──┐  │  ┌─────────────────────┐ │
│ YES  │     │   NO    │  ├──│ User Management     │ │
└──┬───┘     │ Reject  │  │  └─────────────────────┘ │
   │         └─────────┘  │  ┌─────────────────────┐ │
┌──▼───────────────┐      ├──│ RVM Management      │ │
│ AdminNavigator   │      │  └─────────────────────┘ │
└──┬───────────────┘      │  ┌─────────────────────┐ │
   │                      ├──│ Reward Management   │ │
┌──▼───────────────┐      │  └─────────────────────┘ │
│ AdminDashboard   │      │  ┌─────────────────────┐ │
│ - 8 Stats Cards  │      └──│ Analytics Screen    │ │
│ - 4 Quick Actions│         └─────────────────────┘ │
│ - System Status  │                                  │
└──────────────────┘         ┌────────────────────┐  │
                             │    Logout Button   │  │
                             │ (Returns to Login) │◄─┘
                             └────────────────────┘

Admin Panel Access Control

Role-based routing in AppNavigator.tsx:

// After authentication, check user role
if (user.role === 'admin') {
  return <AdminNavigator />;  // 6 admin screens
} else {
  return <UserNavigator />;   // 5 user tabs + locations
}

Admin Login Flow:

User opens LoginScreen
Taps "Admin Login" link at bottom
Redirected to AdminLoginScreen
Enters admin email/password
System validates credentials
Checks if user.role === 'admin' in Firestore
If admin → AdminNavigator (dashboard)
If not admin → Alert + redirect to UserNavigator

🌙 Dark Mode Theme System

The app includes a complete dark mode theme system (UI implementation pending).

Theme Architecture

Files:

src/constants/theme.ts - Color palettes and theme functions
src/hooks/useTheme.ts - Theme context hook

Color Palettes:

Light Mode (COLORS):

{
  primary: '#10b981',     // Emerald green
  background: '#f9fafb',  // Light gray
  text: '#1f2937',        // Dark gray
  surface: '#ffffff',     // White
  // ... 20+ more colors
}

Dark Mode (DARK_COLORS):

{
  primary: '#10b981',     // Same emerald (brand)
  background: '#111827',  // Dark blue-gray
  text: '#f9fafb',        // Light gray (inverted)
  surface: '#1f2937',     // Dark surface
  // ... 20+ more colors (inverted)
}

Using Dark Mode

1. Get current theme colors:

import { useTheme } from '../hooks/useTheme';

const MyScreen = () => {
  const { colors, isDarkMode } = useTheme();
  
  return (
    <View style={{ backgroundColor: colors.background }}>
      <Text style={{ color: colors.text }}>Hello</Text>
    </View>
  );
};

2. Using getColors() function:

import { getColors } from '../constants/theme';

const colors = getColors(isDarkMode); // Returns appropriate palette

Implementation Status:

✅ Color palettes defined (Light + Dark)
✅ Theme hook created (useTheme)
✅ Theme switcher function (getColors)
⏳ UI screens need to use colors instead of COLORS
⏳ Dark mode toggle button in Profile screen

🗺️ RVM Locations & Maps

The app includes a location finder for nearby RVMs with map integration.

RVM Locations Screen

File: src/screens/user/RVMLocationsScreen.tsx

Features:

Map View (placeholder - requires react-native-maps)
- Interactive map showing RVM markers
- User's current location marker
- Tap markers to see RVM details
List View (fully functional)
- Scrollable list of all RVMs
- Location cards with:
  - RVM name and address
  - Status badge (Online/Offline/Maintenance)
  - Total deposits count
  - Distance from user (placeholder)
  - "Get Directions" button
- Selected RVM highlighted in green

Installing Maps:

# Install react-native-maps
npm install react-native-maps

# iOS only
cd ios
pod install
cd ..

Map Configuration: The code is ready in RVMLocationsScreen.tsx but commented out:

// Uncomment after installing react-native-maps:
// import MapView, { Marker } from 'react-native-maps';

Data Source:

Fetches RVMs from Firestore rvms collection
Uses rvmService.getAllRVMs() for data
Real-time updates with pull-to-refresh

📝 Development Notes

Current Phase: Production Ready

✅ All core features implemented (user + admin)
✅ Complete admin panel with 6 management screens
✅ Dark mode theme system ready
✅ RVM locations with map placeholder
Using mock sensor data for development
QR codes trigger simulated detection responses
Ready for real IoT sensor integration via Firebase Realtime Database

Known Issues & Discrepancies

Token Reward Values: There's currently a mismatch in token values across the codebase:

README.md states: Plastic bottle = 10 tokens, Metal can = 15 tokens
UI displays: Plastic bottle = 5 tokens, Metal can = 3 tokens
Location: Check src/constants/index.ts for authoritative values
Recommendation: Update README or constants to match desired token economy

Future IoT Integration

The architecture is designed to easily integrate with real RVM sensors:

Replace dummy sensor data with Firebase Realtime Database listeners
Update QR validation logic to verify with hardware
Implement real-time machine status monitoring
Add ML-based waste classification (optional)

🐛 Troubleshooting

Common Issues

1. Module not found errors ```bash

Clear cache and reinstall

rm -rf node_modules npm install npm start -- --reset-cache ```

2. iOS build fails ```bash cd ios pod deintegrate pod install cd .. ```

3. Android build fails

A. Java version issues: ```bash

Verify Java 17 is being used

java -version # Should show "17.0.13" or similar

If wrong version, ensure build-android.ps1 points to correct Java 17 path

```

B. Gradle cache issues: ```bash cd android .\gradlew clean .\gradlew cleanBuildCache cd .. ```

C. Missing resources or keystore: ```bash

Debug keystore is auto-generated if missing

Missing drawable/mipmap resources are copied from React Native templates automatically during build

```

D. ReactNativeFlipper errors: ```bash

ReactNativeFlipper is already disabled in MainApplication.java

If you see Flipper errors, ensure the initializeFlipper() call is commented out

```

📱 Installing the APK

After building the APK successfully, you can install it on your Android device or emulator:

Option 1: Install on Android Studio Emulator

Prerequisites:

Android Studio installed
Emulator already created and running

Installation Steps:

Start Android Studio Emulator:
- Open Android Studio → Device Manager (or AVD Manager)
- Click "Play" button on any emulator to start it
- Wait for emulator to fully boot up
Verify emulator is connected: ```bash adb devices ``` You should see your emulator listed (e.g., emulator-5554)
Install the APK to emulator: ```bash adb -e install android\app\build\outputs\apk\debug\app-debug.apk ```

Alternative method (drag & drop):
- Simply drag the APK file (android\app\build\outputs\apk\debug\app-debug.apk)
- Drop it onto the running emulator window
- Android will automatically install it
Launch the app:
- Open app drawer in emulator
- Find "REVENAC" app
- Tap to launch

Troubleshooting:

If adb devices shows no emulators, restart the emulator
If installation fails, try: adb uninstall com.revenac then reinstall
For "INSTALL_FAILED_UPDATE_INCOMPATIBLE", uninstall the old version first

Option 2: Install on Physical Android Device

Prerequisites:

Enable Developer Mode on your Android device
Enable USB Debugging in Developer Options
Install Android SDK Platform Tools (includes adb)

Installation Steps:

Connect your Android device via USB
Verify device connection: ```bash adb devices ```
Install the APK: ```bash adb install android\app\build\outputs\apk\debug\app-debug.apk ```
Launch the app from your device's app drawer

Option 3: Manual Installation (Without ADB)

Transfer the APK file (android\app\build\outputs\apk\debug\app-debug.apk) to your device
Open the file on your device to install (you may need to enable "Install from Unknown Sources")

🔧 Troubleshooting

4. Firebase authentication not working

Check if google-services.json (Android) and GoogleService-Info.plist (iOS) are in correct locations
Verify .env file has correct Firebase credentials
Ensure Firebase Authentication is enabled in console

5. Google Sign-In fails

Make sure you're using the Web Client ID (not Android/iOS client ID)
Check if Google Sign-In is enabled in Firebase Console
Verify SHA-1 fingerprint is added to Firebase project (Android)

📄 License

This project is created for educational purposes as part of a college project.

👥 Contributors

Your Name - Developer

ℹ️ Important Information for Repository Users

⚠️ Can This Project Run Automatically? NO

Answer: NO - This project CANNOT be cloned and run without manual setup.

Why?

🚫 Firebase credentials are not in the repository (security reasons)
🚫 google-services.json is not included (user-specific Firebase project)
🚫 Java 17 portable is not in git (191MB, too large for GitHub)
🚫 Firebase security rules must be manually configured
🚫 Admin user must be created in Firebase Console
🚫 Database must be seeded with initial data

For AI Agents/Automated Systems:

You cannot clone this repository and run it without human intervention
User must provide Firebase project credentials
User must download Java 17 separately
User must configure Firebase Console settings
Estimated setup time: 15-30 minutes

If you are an AI trying to run this project:

Ask the user to create a Firebase project and provide credentials
Ask the user to download Java 17 portable
Ask the user to complete the Firebase Console configuration
Only then can you proceed with npm install and build steps

Why Docker Is NOT Used

While Docker configuration files exist in this repository, Docker is NOT used for the APK build process. The Docker build was found to be extremely slow (1000+ seconds) and was replaced with a native Windows build using Java 17 portable and PowerShell scripts.

Current Build Approach:

✅ Native Windows build using build-android.ps1
✅ Java 17 portable (no system installation required)
✅ Direct Gradle execution
✅ Build time: ~5-10 minutes (vs 20+ minutes with Docker)

Key Technical Decisions

Java 17 Requirement: Java 21 causes jlink errors with current Gradle setup
AGP 7.4.2: Required for React Native 0.73.2 compatibility (AGP 8.x causes failures)
gesture-handler 2.14.0: Newer versions (2.29.1+) are incompatible with RN 0.73.2
vision-camera-code-scanner Disabled: Library has API incompatibilities
Stable Configuration: SDK 34, Gradle 8.7, Kotlin 1.8.0

What's Included

✅ All Firebase modules enabled (Analytics, Auth, Firestore, Storage, Messaging)
✅ TLS configuration for Windows + Google Maven
✅ Auto-generated debug keystore
✅ React Native templates for missing resources
✅ ReactNativeFlipper disabled (reduces build complexity)

Build Output

APK Location: android\app\build\outputs\apk\debug\app-debug.apk
APK Size: ~55MB
Build Success Rate: 100% with documented configuration

📞 Support

For issues and questions:

Email: support@revenac.com
GitHub Issues: [Create an issue]

🙏 Acknowledgments

Firebase for backend services
React Native community
All open-source libraries used in this project
Adoptium for OpenJDK builds

📊 Feature Comparison: User vs Admin

Feature	User Access	Admin Access
Authentication	Email/Password, Google OAuth	Dedicated Admin Login
Dashboard	Personal stats (tokens, recycling)	System-wide stats (8 cards)
Scanner	✅ Scan QR codes to recycle	❌ Not available
Leaderboard	✅ View rankings, badges	❌ Not available
Rewards	✅ Redeem tokens for rewards	✅ Full CRUD (add/edit/delete)
Profile	✅ Personal settings, history	❌ Not available
RVM Locations	✅ Find nearby RVMs, get directions	❌ View only
User Management	❌ View own profile only	✅ Full control (roles, search)
RVM Management	❌ Not available	✅ Status control, delete, stats
Analytics	❌ Not available	✅ System-wide analytics
Redemption Approval	❌ Not available	✅ Approve/reject (via dashboard)
Navigation	5 tabs (Home, Scanner, Leaderboard, Rewards, Profile)	5 screens (Dashboard, Users, RVMs, Rewards, Analytics)

🚀 Quick Start Summary

For Regular Users:

Download and install the app
Sign up with email or Google
Find nearby RVMs using the Locations screen
Scan QR codes to recycle items
Earn tokens (5 per bottle, 3 per can)
Redeem tokens in Rewards marketplace
Compete on the Leaderboard

For Administrators:

Get admin credentials from system admin
Tap "Admin Login" on the login screen
Access the Admin Dashboard
Manage users, RVMs, rewards, and view analytics
Monitor system health and performance
Approve pending redemptions

📈 Project Statistics

Total Screens: 16 screens
- 3 Auth screens (Login, SignUp, AdminLogin)
- 1 Splash screen
- 6 User screens (Home, Scanner, Leaderboard, Rewards, Profile, RVM Locations)
- 6 Admin screens (Dashboard, Users, RVMs, Rewards, Analytics)
Total Services: 6 Firebase services
- authService (authentication)
- userService (user CRUD)
- transactionService (recycling transactions)
- leaderboardService (rankings)
- rewardService (rewards CRUD)
- rvmService (RVM management)
Total Components: 10+ reusable UI components
Code Quality: TypeScript with strict typing, error handling, loading states
Theme Support: Light + Dark mode palettes
Navigation: 4 navigators (App, Auth, User, Admin)

🎯 Future Enhancements

Near-term (Ready to implement)

Dark Mode UI: Apply dark theme across all screens (theme system ready)
React Native Maps: Uncomment map code in RVMLocationsScreen
Push Notifications: Firebase Messaging configured, handlers pending
Offline Support: Queue transactions for sync when online
Image Uploads: Profile pictures, reward images (Storage ready)

Medium-term

Real-time Chat: Admin-user support chat
QR Code Generation: Generate unique RVM codes
Multi-language Support: i18n integration
Advanced Analytics: Charts with Victory Native
Social Sharing: Share achievements on social media

Long-term (Requires hardware)

IoT Integration: Connect to actual RVM sensors
ML Classification: AI-based waste type detection
Blockchain Tokens: NFT-based rewards
AR Features: AR-based recycling tutorials

Built with ♻️ by REVENAC Team

Name		Name	Last commit message	Last commit date
Latest commit History 46 Commits
.vscode		.vscode
android		android
docs		docs
ios		ios
release		release
scripts		scripts
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
App.tsx		App.tsx
Dockerfile.android		Dockerfile.android
app.json		app.json
babel.config.js		babel.config.js
build-android.ps1		build-android.ps1
docker-build.ps1		docker-build.ps1
index.js		index.js
metro.config.js		metro.config.js
package-lock.json		package-lock.json
package.json		package.json
react-native.config.js		react-native.config.js
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

REVENAC - Smart Reverse Vending Machine Platform

♻️ REVENAC

📱 Project Overview

Key Features

🛠️ Tech Stack

Frontend

Backend

Additional Tools

📋 Prerequisites

For Android Development:

For iOS Development (macOS only):

⚠️ IMPORTANT: Cannot Run Without Manual Setup

Required Manual Steps (No Automation Possible):

🚀 Getting Started

1. Clone the Repository

2. Install Dependencies

Install npm packages

Install iOS pods (macOS only)

3. Download Java 17 (Required for Android Build)

4. Firebase Configuration

Step 1: Create Firebase Project

Step 2: Add Android App

Step 3: Add iOS App (macOS only)

Step 4: Configure Environment Variables

Firebase Configuration (Get from Firebase Console → Project Settings)

Google Sign-In (Get from Firebase Console → Authentication → Sign-in method → Google → Web SDK configuration)

App Configuration

Step 5: Enable Google Sign-In

4. Firebase Security Rules

Firestore Rules

Storage Rules

5. Seed Initial Data

✅ Pre-Flight Checklist (Before Running)

📱 Running the App

Android

Option 1: Using Android Studio Emulator with Metro (Development)

Build APK with Java 17

Install on emulator

Launch the app

This command might fail if system Java is not 17

Option 2: Building Standalone APK (Production Build)

The build script automatically sets JAVA_HOME to java17-portable

iOS (macOS only)

Start Metro bundler

Run on iOS simulator (in new terminal)

📂 Project Structure

Key Directories Explained

🔄 Data Flow Architecture

Complete Application Data Flow

Firebase Data Sync Flow

Scanning & Recycling Flow

Leaderboard Flow

Rewards Redemption Flow

Profile & Logout Flow

Complete Data Pipeline

🛠️ Service Layer Documentation

authService.ts

userService.ts

transactionService.ts

leaderboardService.ts

rewardService.ts

rvmService.ts (NEW)

Service Usage Example

🔥 Firebase Collections Schema

users

transactions

rvms

rewards

🧪 Testing with Dummy Data

🎨 Theme & Colors

🚧 Implementation Status

✅ Completed

🔨 To Be Implemented

👨‍💼 Admin Panel Features

Accessing Admin Panel

Admin Screens Overview

1. Admin Dashboard (`AdminDashboardScreen.tsx`)

2. User Management Screen (`UserManagementScreen.tsx`)

3. RVM Management Screen (`RVMManagementScreen.tsx`)

4. Reward Management Screen (`RewardManagementScreen.tsx`)

5. Analytics Screen (`AnalyticsScreen.tsx`)

6. Admin Login Screen (`AdminLoginScreen.tsx`)

Packages