PropertyViewerApp - 3D Utility Mapping Android App

A native Android application for viewing utility infrastructure on interactive maps with property management and tenant billing features.

Overview

PropertyViewerApp allows three types of users to interact with utility data:

• Admins - View all property managers and properties across the system
• Property Managers - View managed properties, tenants, and billing information
• Tenants - View utility usage, bills, and make payments

Features

✅ Implemented Features

• Multi-module Architecture - Clean Architecture + MVVM with Hilt DI
• Interactive Map - OSMdroid-powered map with property markers
• Role-Based Views - Different property visibility for Admin, PM, and Tenant roles
• Utility Infrastructure Stats - Detailed breakdown of water, gas, sewer, and electricity infrastructure
• Bill Management - View bills with detailed utility breakdowns
• Mock Payment Processing - Simulate bill payments with animated success feedback
• Material 3 Design - Modern UI with dynamic theming
• Mock API - Complete mock backend with 12 months of realistic data
• Offline Support - Room database for local caching

Planned Features

• 3D building rendering with MapLibre Native
• Real-time utility line visualization on map
• Property manager dashboard
• Tenant usage analytics and charts
• Real payment integration (Stripe)

Tech Stack

• Language: Kotlin
• UI: Jetpack Compose + Material 3
• Architecture: Clean Architecture + MVVM
• DI: Hilt (Dagger)
• Networking: Retrofit + OkHttp + Moshi
• Database: Room
• Maps: MapLibre Native + osmdroid
• Payment: Stripe Android SDK
• Async: Kotlin Coroutines + Flow

Project Structure

PropertyViewerApp/
├── app/                    # Main application module
├── feature/                # Feature modules
│   ├── auth/              # Authentication
│   ├── map/               # 3D mapping
│   ├── property/          # Property management
│   ├── tenant/            # Tenant features
│   └── payment/           # Payment processing
├── core/                   # Core modules
│   ├── common/            # Common utilities
│   ├── model/             # Domain models
│   ├── data/              # Repositories
│   ├── network/           # API & mock data
│   ├── database/          # Room database
│   └── designsystem/      # Material 3 theme
└── build-logic/            # Convention plugins (future)

Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

Required Software

• Android Studio: Hedgehog (2023.1.1) or later
  • Download from: https://developer.android.com/studio
• JDK: 17 or later
  • Verify with: java -version
  • Download from: https://adoptium.net/ (recommended)
• Git: For cloning the repository
  • Download from: https://git-scm.com/downloads

Android SDK Components

Install via Android Studio → Tools → SDK Manager:

• Android SDK Platform 34 (Android 14)
• Android SDK Build-Tools 34.0.0 or later
• Android Emulator (if not using a physical device)

System Requirements

• Min SDK: 26 (Android 8.0)
• Target SDK: 34 (Android 14)
• Compile SDK: 34
• Gradle: 8.5 (included in wrapper)
• Kotlin: 1.9.22

Setup Instructions

1. Clone the Repository

git clone https://github.com/stovie93/PropertyViewerApp.git
cd PropertyViewerApp

2. Open in Android Studio

1. Launch Android Studio
2. Click File → Open
3. Navigate to the cloned PropertyViewerApp directory
4. Click OK
5. Wait for Gradle sync to complete (this may take several minutes on first run)
6. If prompted, accept any SDK or Gradle plugin updates

3. Set Up an Emulator (Optional)

If you don't have a physical device:

1. Click Tools → Device Manager
2. Click Create Device
3. Select a device definition (recommended: Pixel 2)
4. Select API Level 29 (Android 10) or higher
5. Click Finish

4. Run the Application

1. Select your device/emulator from the device dropdown
2. Click Run ▶️ (or press Shift+F10)
3. Wait for the build to complete
4. The app will launch automatically

Build from Command Line

Windows

# Debug build
gradlew.bat assembleDebug

# Install on connected device
gradlew.bat installDebug

# Run tests
gradlew.bat test

# Run all checks
gradlew.bat check

macOS/Linux

# Debug build
./gradlew assembleDebug

# Install on connected device
./gradlew installDebug

# Run tests
./gradlew test

# Run all checks
./gradlew check

First Run - Testing the App

When you first launch the app, you'll see:

1. Map View - An interactive map centered on the United States
2. User Selector - A dropdown at the top to select different user roles
3. Loading State - The app will load 6 mock users

Testing Different User Roles

Select from the dropdown to test different perspectives:

Admin (admin001)

• Views all properties on the map
• Can access all property details

Property Managers (pm001, pm002, pm003)

• Each sees only their managed properties
• pm001: Utah properties
• pm002: Texas properties
• pm003: Nebraska properties

Tenants (tenant_utah_001, tenant_texas_001)

• Each sees only their assigned property
• Can view bills and make mock payments

Interacting with the Map

1. Pan/Zoom - Use standard touch gestures to navigate the map
2. Click Property Marker - Tap a marker to select a property
3. View Bills - Bills appear in a bottom sheet when a property is selected
4. View Utility Stats - Click the info button (ℹ️) in the top-right corner
5. Pay Bills - As a tenant, click the green "Pay Bill" button to simulate payment

Mock Data

The app uses comprehensive mock data for development and testing. See MOCK_DATA_SUMMARY.md for details.

Mock Users

The app includes 6 pre-configured users for testing:

User ID	Role	Name	Properties Managed/Assigned
admin001	Admin	Sarah Admin	All properties
pm001	Property Manager	John Utah PM	Utah properties
pm002	Property Manager	Mike Texas PM	Texas properties
pm003	Property Manager	Jane Nebraska PM	Nebraska properties
tenant_utah_001	Tenant	Emily Davis	Utah HQ - Suite 201
tenant_texas_001	Tenant	Michael Johnson	Texas Office - Unit 305

Note: No login is required - simply select a user from the dropdown to switch roles.

Mock Properties

Real PropertyViewer office locations:

• Utah HQ: 1600 W Towne Center Dr, South Jordan, UT
• Texas Office: 15851 Dallas Pkwy, Addison, TX
• Nebraska Office: 11837 Miracle Hills Dr, Omaha, NE

Mock Data Highlights

• ✅ 12 months of utility usage data (Jan-Dec 2025)
• ✅ Seasonal variations based on location (Utah/Texas/Nebraska)
• ✅ Abnormal spikes (AC failure, heat wave, cold snap)
• ✅ 4 utility types: Water, Gas, Sewer, Electricity
• ✅ Complete bills with taxes, fees, and payment status

Architecture

Clean Architecture Layers

┌─────────────────────────────────────┐
│         Presentation Layer          │
│   (Compose UI + ViewModels)         │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│          Domain Layer               │
│   (Use Cases + Domain Models)       │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│           Data Layer                │
│  (Repositories + Data Sources)      │
└─────────────────────────────────────┘

Module Dependencies

• app depends on all feature modules
• feature modules depend on core modules
• core modules are independent (except data → network + database)

Development

Code Style

• Follow official Kotlin style guide
• Use ktlint for formatting (configured in build)
• Maximum line length: 120 characters

Git Workflow

1. Create feature branch from master
2. Make changes with descriptive commits
3. Create Pull Request
4. Wait for review and CI checks
5. Merge to master

Testing

• Unit Tests: src/test/java/
• Integration Tests: src/test/java/
• UI Tests: src/androidTest/java/

Run specific test suites:

./gradlew :core:data:test           # Unit tests for data layer
./gradlew :feature:map:test         # Unit tests for map feature
./gradlew :app:connectedAndroidTest # UI tests on device

API Documentation

Mock API endpoints are documented in MOCK_DATA_SUMMARY.md.

Base URL (Mock): http://localhost:8080/api/v1/

Example Requests

// Get current user
GET /api/v1/auth/me

// Get all properties
GET /api/v1/properties

// Get tenant usage data
GET /api/v1/tenants/tenant_utah_001/usage

// Get tenant bills
GET /api/v1/tenants/tenant_utah_001/bills

Troubleshooting

Gradle Sync Issues

Problem: Gradle sync fails with "Could not resolve dependencies"

• Solution: Ensure you're using JDK 17 or later (java -version)
• Solution: Check gradle/wrapper/gradle-wrapper.properties shows Gradle 8.5+
• Solution: File → Invalidate Caches → Invalidate and Restart

Problem: "Unsupported Java version"

• Solution: Set Android Studio to use JDK 17:
  • File → Settings → Build, Execution, Deployment → Build Tools → Gradle
  • Set "Gradle JDK" to Java 17

Build Errors

Problem: "SDK location not found"

• Solution: Create local.properties with:

  sdk.dir=C\:\\Users\\YourUsername\\AppData\\Local\\Android\\Sdk
  

Problem: "Missing Android SDK Platform 34"

• Solution: Tools → SDK Manager → SDK Platforms → Check "Android 14.0 (API 34)" → Apply

Problem: Out of memory during build

• Solution: Increase heap size in gradle.properties:

  org.gradle.jvmargs=-Xmx4096m
  org.gradle.daemon=true
  

Problem: Kotlin compilation errors

• Solution: Build → Clean Project, then Build → Rebuild Project

Runtime Issues

Problem: App crashes immediately on startup

• Solution: Check Logcat for Hilt dependency injection errors
• Solution: Ensure emulator is API 26+ (Android 8.0 or higher)

Problem: Map tiles not loading (blank map)

• Solution: Verify device/emulator has internet connection
• Solution: OSMdroid requires internet to download map tiles on first run
• Solution: Check Logcat for network errors

Problem: "User dropdown is hidden" or no users loading

• Solution: Wait 5-10 seconds for mock data to load
• Solution: Check Logcat for "MapViewModel" logs showing user loading
• Solution: Restart the app

Problem: Properties not appearing on map

• Solution: Zoom in on the map (properties are in Utah, Texas, Nebraska)
• Solution: Select a different user from the dropdown
• Solution: Check that mock data is loading (see Logcat)

Problem: MockWebServer port conflict

• Solution: Check if port 8080 is already in use
• Solution: Close other applications using port 8080
• Solution: Restart the emulator/device

Problem: Utility stats show "No data available"

• Solution: This is expected for some properties without utility infrastructure
• Solution: Try selecting Utah HQ or Texas Office properties

Emulator Performance

Problem: Emulator is very slow

• Solution: Enable hardware acceleration:
  • Tools → SDK Manager → SDK Tools → Check "Intel x86 Emulator Accelerator (HAXM)"
  • Or use an ARM64 emulator with Apple Silicon Macs
• Solution: Allocate more RAM to the emulator in AVD Manager
• Solution: Use a physical device instead

Common Questions

Q: Do I need a real backend server? A: No, the app uses a built-in MockWebServer that runs automatically.

Q: Why don't I see a login screen? A: Authentication UI is not yet implemented. Use the user dropdown to switch roles.

Q: Can I test payments? A: Yes, but they're simulated. No real payment processing occurs.

Q: Where is the data stored? A: Mock data is generated in-memory. Room database caching is configured but not actively used yet.

Roadmap

✅ Phase 1: Foundation (Complete)

• Multi-module architecture with Clean Architecture + MVVM
• Hilt dependency injection setup
• Material 3 design system
• Mock API with MockWebServer
• Mock data generation (users, properties, bills, utilities)
• Room database configuration

✅ Phase 2: Map Integration (Complete)

• OSMdroid map integration
• Property markers on map
• User role-based property filtering
• Interactive map controls (pan, zoom)
• Property selection bottom sheet

✅ Phase 3: Utility Features (Complete)

• Utility infrastructure data models
• Utility stats dialog with detailed breakdowns
• Color-coded utility types (Water, Gas, Sewer, Electricity)
• Infrastructure placement stats (underground, above-ground)
• Line length calculations

✅ Phase 4: Billing & Payments (Complete)

• Bill viewing with utility breakdowns
• Mock payment processing
• Payment success animations
• Role-based payment access (tenants only)

🔄 Phase 5: Authentication (In Progress)

• Login screen with Compose
• Secure authentication flow
• Session persistence
• Logout functionality

📋 Phase 6: Property Manager Features

• Property manager dashboard
• Tenant management screens
• Property analytics
• Bill generation interface

📋 Phase 7: Tenant Features

• Usage tracking dashboard
• Usage charts and analytics
• Historical usage comparison
• Usage export functionality

📋 Phase 8: Advanced Mapping

• MapLibre Native integration for 3D buildings
• Real-time utility line visualization on map
• Interactive 3D infrastructure layers
• Underground vs above-ground rendering

📋 Phase 9: Payment Integration

• Stripe SDK integration
• Real payment processing
• Payment method management
• Transaction history

📋 Phase 10: Polish & Production

• Performance optimization
• Accessibility improvements
• Comprehensive test coverage
• CI/CD pipeline
• Production release preparation

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is proprietary software owned by PropertyViewer.

Contact

• Project Repository: https://github.com/stovie93/PropertyViewerApp
• Issues: https://github.com/stovie93/PropertyViewerApp/issues

Acknowledgments

• Built with Android Jetpack
• Maps powered by MapLibre
• Icons from Material Icons