Site Surveyor Compass

Flutter field utility app for GPS workflows, compass/bearing tools, waypoint management, offline storage, and on-site reporting.

Repository: bhedanikhilkumar-code/site-surveyor-compass

---

Recruiter Snapshot

Site Surveyor Compass is a mobile-first field utility for survey-style workflows. It shows Flutter capability beyond basic screens: GPS, sensors, map tools, local models, reports, QR sharing, voice notes, photos, offline maps, and practical measurement utilities.

Signal	Details
Product domain	Field surveying, waypoint capture, GPS tools, distance/area calculations, reporting
Mobile stack	Flutter, Dart, Provider, Hive, Geolocator, Sensors Plus, Flutter Map, Firebase
Best review angle	Device-aware engineering: location, compass, permissions, local persistence, exports, media capture
Package name	geocompass_pro
Status	Feature-rich local mobile app; screenshots/demo GIF and release build hardening are roadmap items

What the App Covers

Area	What is implemented or represented
GPS + compass tools	Compass provider, GPS service, bearing line, stakeout, GPS strength, Bluetooth GPS, and navigation screens
Survey calculations	Distance measure, area measurement, slope calculator, height measure, coordinate converter, and COGO tools
Waypoint/project workflows	Project manager, waypoint manager, saved locations, track recording, map view, geofencing, and terrain viewer
Field documentation	Camera GPS tagging, voice notes, survey forms, PDF reports, Excel export, QR scanner/share, and import/export screens
Offline/local data	Hive models for projects, waypoints, tracks, tagged photos, and voice notes
Cloud-ready layer	Firebase auth/messaging/firestore dependencies and data sync/cloud backup screens for future production sync

Architecture at a Glance

flowchart LR
    FieldUser[Field User] --> Screens[Flutter Screens]
    Screens --> Providers[Provider State]
    Providers --> Services[GPS, Project, Track, Waypoint, Firebase Services]
    Services --> DeviceApis[Location, Sensors, Camera, Mic, Files]
    Services --> Hive[(Hive Local Storage)]
    Services --> Exports[PDF, Excel, QR, Share]

Loading

Core Workflow

sequenceDiagram
    participant U as Surveyor
    participant UI as Flutter UI
    participant GPS as GPS / Sensor Layer
    participant Store as Hive Storage
    participant Export as Report Export
    U->>UI: Open field tool or project
    UI->>GPS: Request location, bearing, or measurement input
    GPS-->>UI: Return coordinates / sensor state
    UI->>Store: Save waypoint, track, photo, or note
    Store-->>UI: Update project state
    UI->>Export: Generate report, QR, PDF, or Excel output

Loading

Local Setup

1. Install dependencies

git clone https://github.com/bhedanikhilkumar-code/site-surveyor-compass.git
cd site-surveyor-compass
flutter pub get

2. Run on device or emulator

flutter run

Recommended for best review:

• Use a physical Android device for GPS, compass, camera, microphone, vibration, and permission flows.
• Grant location permission when prompted.
• For Firebase-backed flows, add your own Firebase configuration files before testing cloud sync/auth features.

3. Generate local model code when models change

dart run build_runner build --delete-conflicting-outputs

Quality Checks

flutter analyze
flutter test

Current quality status:

Check	Status
Static analysis	Uses analysis_options.yaml and Flutter lints
Tests	Includes test/geo_utils_test.dart and test/widget_test.dart
Local models	Hive model adapters are present for project, waypoint, track, photo, and voice-note data
Repository health workflow	Runs on push through GitHub Actions

Project Structure

site-surveyor-compass/
├── lib/
│   ├── models/        # Hive-backed project, waypoint, track, photo, voice-note models
│   ├── providers/     # Auth, compass, and theme state
│   ├── screens/       # GPS, map, survey, measurement, export, auth, settings screens
│   ├── services/      # GPS, waypoint, project, track, Firebase, and integration services
│   ├── utils/         # Geo calculations and app constants
│   └── widgets/       # Compass dial, premium UI, settings, auth wrapper, reusable UI
├── assets/images/     # App icon and image assets
├── test/              # Geo utility and widget tests
├── docs/              # Architecture, case study, quality, roadmap, review docs
├── scripts/           # Icon generation and helper scripts
└── pubspec.yaml       # Flutter package configuration

Product Strengths

• Real field utility direction: The feature set maps to actual survey/site tasks instead of a generic demo app.
• Device-aware implementation: GPS, sensors, photos, voice, QR, vibration, maps, permissions, and file exports are all represented.
• Offline-first thinking: Hive storage and local models make the app usable for field work where connectivity can be unreliable.
• Review-friendly organization: Models, providers, services, screens, widgets, and tests are separated clearly for code review.

Roadmap

• Add a short screenshot strip or GIF showing compass → waypoint → report export
• Harden Firebase setup docs and safe demo configuration
• Add release build notes for Android APK generation
• Expand tests around coordinate conversion, area measurement, and report generation
• Reduce existing Flutter analyzer lint backlog before release packaging
• Improve accessibility labels and large-screen/tablet layouts
• Add a sample field project dataset for faster recruiter review

Documentation Hub

Document	Purpose
Architecture	System layers, workflow, data/state model, and extension points.
Case Study	Product framing, decisions, tradeoffs, and portfolio story.
Roadmap	Practical next steps for turning the project into a stronger product.
Quality Standard	Repository health checks, review standards, and quality gates.
Review Checklist	Final share/recruiter review checklist for a stronger GitHub impression.
Contributing	Branching, commit, review, and quality guidelines.
Security	Responsible disclosure and safe configuration notes.
Support	How to ask for help or report issues clearly.
Code of Conduct	Collaboration expectations for respectful project activity.

Security Note

Do not commit Firebase service files, API keys, signing keys, keystores, or production environment credentials. Use local configuration and platform-specific secret management for deployment builds.

License

Add a license file before accepting outside contributions or reuse. If this stays portfolio-only, document that clearly in the repository settings and project docs.