BhuMitra (Frontend) 🌾 — Land Area Measurement App

BhuMitra is a professional, high-precision land measurement application built for farmers, surveyors, and land professionals. BhuMitra enables users to easily measure plots, collaborate in real-time, generate PDF reports, and sync measurements offline.

---

📖 Table of Contents

1. What is BhuMitra? (Beginner Friendly)
2. How It Works Under the Hood
3. Key Features & How They Work
   • 1. Manual Map Boundary Marking
   • 2. GPS Walking Mode
   • 3. Real-Time Collaborative Team Survey
   • 4. Offline Mode & Auto-Sync Caching
   • 5. BhuMitra Pro & Payment Verification
   • 6. Device & API Shield (Google Play Integrity)
4. Tech Stack & Architecture
5. Getting Started (Beginner Friendly Setup)
6. Project Structure

---

🌾 What is BhuMitra? (Beginner Friendly)

Historically, measuring agricultural fields required physically pulling chains across boundary lines or hiring expensive professional surveyors.

BhuMitra makes land measurement as simple as using your phone:

• Draw on a Map: Tap the corners of your field on your screen to instantly calculate its area.
• Walk the Boundary: Put your phone in your pocket, walk along the boundary of your field, and BhuMitra will automatically draw the boundary using your phone's GPS.
• Work Together (Team Survey): If a field is too large to walk alone, you and your partners can walk different boundaries at the same time. BhuMitra combines your paths live on the map.
• Works Without Internet: If you are in a remote farm with no network, you can still measure. The app saves everything locally and uploads it when you return to town.

---

⚙️ How It Works Under the Hood

BhuMitra works as a client-server application:

graph TD
    A[BhuMitra Flutter App] <-->|HTTPS API / JSON| B[Nginx Proxy]
    A <-->|WebSockets| C[NestJS Gateway]
    B <--> D[NestJS API Server]
    D <--> E[(PostgreSQL Database)]
    D <--> F[(Redis Cache)]

Loading

1. The Client (Flutter App): The user interface where you view maps, drop pins, and trigger GPS tracking.
2. The Server (NestJS Backend on AWS): Stores your measurements securely, manages collaborative rooms, and verifies payments.
3. Local Database (Hive): Stores data on your phone so the app works offline.
4. Cloud Database (PostgreSQL): Stores user profiles and saved plot information permanently.

---

✨ Key Features & How They Work

1. Manual Map Boundary Marking

• What it is: A tool that allows you to calculate area by selecting points on a satellite map.
• How it works:
  1. The app renders a map (Google Maps or OpenStreetMap) using the device GPS to focus on your location.
  2. You tap on each corner of your plot.
  3. Every tap drops a visual marker (pin) and draws a line to the previous pin, forming a polygon.
  4. The coordinate points ($Latitude, Longitude$) are computed using the Shoelace Algorithm to calculate the precise area inside the boundary.
  5. Distances between points are computed instantly using the Haversine Formula (which takes the Earth's curvature into account).

2. GPS Walking Mode

• What it is: A mode where you walk around the field to map it.
• How it works:
  1. When you press Start Measuring, the app requests high-accuracy GPS permission.
  2. As you walk, a background listener records your GPS coordinates at set time/distance intervals (e.g., every 2 seconds or every 3 meters).
  3. It filters out weak or drifting GPS signals using a custom threshold (ignoring locations with accuracy worse than 10 meters) to keep boundaries smooth.
  4. Once you complete the loop and press Stop, BhuMitra joins the final point back to your starting point and computes the total area.

3. Real-Time Collaborative Team Survey

• What it is: Multiple people walking different sides of a large plot to measure it together.
• How it works:
  1. Room Creation: One user (the leader) creates a Team Survey Room. The server generates a unique 6-digit code.
  2. Joining: Other team members enter this code in their app to connect.
  3. Live Sync (WebSockets): The app opens a persistent connection (WebSocket) to our server. As each member walks, their phone streams their GPS position to the server.
  4. Dynamic Plot Rendering: The server broadcasts these positions to everyone else in the room. The app draws different colored paths for each person on the screen in real-time.
  5. Merging Paths: Once everyone stops, the app merges the individual segments into a single boundary and calculates the combined area.

4. Offline Mode & Auto-Sync Caching

• What it is: Measuring land with no internet coverage and having it sync automatically later.
• How it works:
  1. The app utilizes Hive (a fast, local database) to save all your plot measurements immediately.
  2. When you save a plot offline, it is marked as syncPending: true.
  3. A background provider detects when the phone regains internet access.
  4. It automatically grabs all pending plots from Hive, posts them to the backend API, updates the database, and switches the status to syncPending: false.
  5. The Home Screen count card automatically listens to this state and updates dynamically.

5. BhuMitra Pro & Payment Verification

• What it is: Premium membership that removes ads and grants unlimited Team Survey rooms.
• How it works:
  1. The user purchases BhuMitra PRO using the in-app subscription flow (via Razorpay / Google Play Billing).
  2. Instead of unlocking the features directly on the phone (which can be bypassed), the app sends the transaction ID to the NestJS backend.
  3. The backend validates the payment directly against the Google Play / Razorpay API.
  4. Once verified, the server flags the user's account as isPro = true in the PostgreSQL database, and the client UI unlocks the features.

6. Device & API Shield (Google Play Integrity)

• What it is: Security checks that prevent hackers from cloning the app or accessing our APIs without authorization.
• How it works:
  1. Security Handshake: Every network request from the app contains a unique encrypted signature header (x-app-id). The server rejects any request missing this signature.
  2. Play Integrity API: During startup, the app requests a cryptographic challenge (nonce) from the backend, asks the Google Play Store to verify the device health, receives an integrity token, and sends it back to the server for verification. If the app is cracked, modified, or running on an unsecure simulator, it shuts down.

---

🛠️ Tech Stack & Architecture

BhuMitra's frontend is structured using clean, modular code:

• Framework: Flutter (Dart)
• State Management: Riverpod (Uses code generation with @riverpod for clean state caching and automatic dependency tracking)
• HTTP Client: Dio (Configured with custom interceptors for JWT token rotation and x-app-id signature injection)
• Local Storage: Hive (for measurements) and FlutterSecureStorage (for user passwords and JWT keys)
• Geospatial Tools: latlong2 (for calculations) and flutter_map (for OpenStreetMap tile rendering)

---

🚀 Getting Started (Beginner Friendly Setup)

Follow these steps to run BhuMitra locally on your computer:

1. Install Flutter

Install the Flutter SDK on your machine. Follow the official Flutter installation guide.

2. Configure Environment Variables

Create a file named .env in the root of the bhumitra-clean folder and configure the API endpoint URL:

# Backend Base URL (Use localhost if running backend locally, or the AWS domain)
BASE_URL=http://localhost:3000/api

# Security Handshake Key (Must match the APP_ID in the backend .env)
APP_ID=BhuMitra_Secure_Alpha_2026_X9z7Pq2Km

3. Fetch Packages & Run

Open your terminal inside the bhumitra-clean folder and run:

# Get dependencies
flutter pub get

# Run on a connected emulator or physical device
flutter run

To build a production package (.aab bundle) for Google Play:

flutter build appbundle --release --obfuscate --split-debug-info=build/debug-info

---

📂 Project Structure

lib/
├── core/                   # Global components, network layers, and services
│   ├── api_service.dart    # Dio HTTP configuration
│   ├── auth_service.dart   # Token management & authentication
│   └── integrity_service.dart # Google Play Integrity verification
│
├── features/               # Independent application features
│   ├── auth/               # Splash screen, Login, Register views
│   ├── home/               # Dashboard, Quick Actions, stats
│   ├── map/                # Core measurement map interface
│   ├── team_survey/        # WebSockets collaborative room interface
│   └── profile/            # User account settings
│
└── main.dart               # App entrypoint & initializations

---

Built with ❤️ for BhuMitra Land Surveyors.