# mdm-app

**Repository Path**: gotittogo/mdm-app

## Basic Information

- **Project Name**: mdm-app
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-18
- **Last Updated**: 2026-06-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MDM Android Client

Enterprise Mobile Device Management (MDM) client for Android devices.

## Status

✅ **Backend Complete** - Core MDM functionality implemented and building successfully  
🚧 **UI Pending** - User interface components ready for implementation

## Features

### ✅ Implemented

- **MQTT Communication** - Secure, persistent connection to MDM server
- **Command Processing** - Extensible command handler framework with 20+ command types
- **Device Owner Management** - Full Device Owner API integration for enterprise control
- **Kiosk Mode** - Lock device to specific apps with comprehensive restrictions
- **App Management** - Install, uninstall, enable, disable apps remotely
- **Location Tracking** - Background GPS tracking with batch upload
- **File Synchronization** - Download/upload files with rule-based sync
- **Health Monitoring** - Battery, storage, memory, network metrics
- **Policy Enforcement** - Remote policy application and management
- **Security** - TLS, certificate pinning, command signing, rate limiting
- **Offline Support** - Command queuing and retry with exponential backoff
- **Audit Logging** - Complete audit trail of all operations

### 🚧 To Be Implemented

- Enrollment UI (QR code, manual entry)
- Management dashboard
- Kiosk home screen and exit overlay
- Settings interface

## Quick Start

### Prerequisites

- Android Studio Hedgehog (2023.1.1) or later
- JDK 17
- Android device with API 28+ (Android 9+)
- Device Owner privileges (see [DEPLOYMENT.md](DEPLOYMENT.md))

### Build

```bash
# Optional: inject AMap key before building
echo "AMAP_API_KEY=your-amap-key" >> local.properties

# Debug build
./gradlew assembleDebug

# Release build
./gradlew assembleRelease

# Local device-owner / provisioning build
./gradlew assembleLocalDebug
```

### Install

```bash
# Install debug APK
./gradlew installDebug

# Or manually
adb install app/build/outputs/apk/debug/app-debug.apk
```

### Local LAN Debug Build

For local provisioning on a LAN without HTTPS, `mqtts`, or CA certificates, use the
dedicated `localDebug` variant:

```bash
./gradlew assembleLocalDebug
adb install -r app/build/outputs/apk/localDebug/app-localDebug.apk
```

This variant keeps the production package name and release signing, but only for local
debugging it allows:

- HTTP API access
- plaintext MQTT via `tcp://host:1883`
- insecure MQTT TLS fallback for temporary lab brokers

Regular `release` stays production-oriented.

### AMap Location Configuration

The app now uses AMap location instead of Google Play location services.

You can provide the AMap key with any one of these methods:

```bash
# Option 1: local.properties
echo "AMAP_API_KEY=your-amap-key" >> local.properties

# Option 2: gradle.properties
echo "AMAP_API_KEY=your-amap-key" >> gradle.properties

# Option 3: environment variable
export AMAP_API_KEY=your-amap-key
```

Resolution order:

1. `gradle.properties`
2. `local.properties`
3. environment variable `AMAP_API_KEY`

If no key is provided, the project can still compile, but runtime AMap positioning on device will not be reliable for acceptance testing.

### Set Device Owner

```bash
# Factory reset device first, then skip all setup steps
adb shell dpm set-device-owner com.company.mdm/com.company.mdm.admin.MdmDeviceAdminReceiver
```

## Architecture

Modern Android architecture following MVVM and Clean Architecture principles:

- **Kotlin** - 100% Kotlin codebase
- **Hilt** - Dependency injection
- **Room** - Local database
- **WorkManager** - Background tasks
- **Coroutines** - Asynchronous programming
- **MQTT (Paho)** - Server communication
- **Timber** - Structured logging

See [ARCHITECTURE.md](ARCHITECTURE.md) for detailed architecture documentation.

## Documentation

- [ARCHITECTURE.md](ARCHITECTURE.md) - Detailed architecture and component documentation
- [DEPLOYMENT.md](DEPLOYMENT.md) - Deployment guide, configuration, and troubleshooting

## Configuration

### MQTT Broker

```kotlin
// Configure in MqttConfig or via device provisioning
serverUrl = "mqtts://mqtt.yourserver.com:8883"
clientId = "device_${deviceId}"
username = "device_username"  // Optional
password = "device_password"  // Optional
```

### Topics

**Upstream (device → server):**
```
mdm/{tenant_id}/{device_id}/up/{topic}
```

**Downstream (server → device):**
```
mdm/{tenant_id}/{device_id}/down/{topic}
```

See [DEPLOYMENT.md](DEPLOYMENT.md) for complete topic list.

## Commands

The client supports 20+ command types:

**Device Information:**
- `GET_DEVICE_INFO` - Hardware, OS, identifiers
- `GET_INSTALLED_APPS` - App inventory

**App Management:**
- `INSTALL_APP` - Install from URL
- `UNINSTALL_APP` - Remove app
- `ENABLE_APP` - Enable disabled app
- `DISABLE_APP` - Disable app

**Kiosk Mode:**
- `KIOSK_ENABLE` - Enable kiosk mode
- `KIOSK_DISABLE` - Disable kiosk mode
- `STATUS_BAR_CONTROL` - Show/hide status bar
- `FOREGROUND_APP_PIN` - Pin app to foreground

**Location:**
- `GET_LOCATION` - Immediate location
- `LOCATION_TRACKING_START` - Start tracking
- `LOCATION_TRACKING_STOP` - Stop tracking

**Files:**
- `SYNC_FILES` - Synchronize files
- `DOWNLOAD_FILE` - Download single file

**System:**
- `REBOOT` - Restart device
- `FACTORY_RESET` - Wipe device
- `CLEAR_APP_DATA` - Reset app

**Policy:**
- `APPLY_POLICY` - Apply policy bundle

See command handlers in `com.company.mdm.command.handlers/`

## Security

- **TLS/SSL** - Encrypted MQTT connections (mqtts://)
- **Certificate Pinning** - Prevent MITM attacks
- **Command Signing** - Verify command authenticity
- **Rate Limiting** - Prevent command flooding
- **Audit Trail** - Complete operation logging

## Development

### Project Structure

```
app/src/main/java/com/company/mdm/
├── admin/              Device Owner management
├── audit/              Audit logging
├── command/            Command framework
├── data/               Data layer (Room, repositories)
├── device/             Device info collection
├── files/              File synchronization
├── health/             Health monitoring
├── kiosk/              Kiosk mode
├── location/           Location tracking
├── mqtt/               MQTT client
├── policy/             Policy management
├── security/           Security components
├── service/            Background services
├── singleappkiosk/     Standalone local single-app kiosk shell
└── worker/             WorkManager tasks
```

### Key Classes

- `MqttForegroundService` - Main service maintaining MQTT connection
- `MqttConnectionManager` - MQTT connection and messaging
- `CommandDispatcher` - Command routing and execution
- `DeviceOwnerManager` - Device Owner API wrapper
- `KioskPolicyEngine` - Kiosk mode implementation

Boundary notes:
- `admin/DeviceOwnerManager` is the only DevicePolicyManager wrapper for main MDM modules.
- `kiosk/` is the server-managed kiosk policy layer.
- `singleappkiosk/` is isolated local kiosk UI/runtime code and should not be imported by main MDM service, command, or policy modules.

### Logging

All logging uses Timber with automatic class/method tagging:

```kotlin
Timber.d("Debug message")
Timber.i("Info message")
Timber.w("Warning message")
Timber.e(exception, "Error message")
```

View logs:
```bash
adb logcat | grep com.company.mdm
```

### Database

Inspect local database:
```bash
adb shell run-as com.company.mdm
cd databases
sqlite3 mdm_database

# View tables
.tables

# View command queue
SELECT * FROM command_queue;
```

## Testing

```bash
# Unit tests
./gradlew testDebug

# Instrumented tests (requires device/emulator)
./gradlew connectedAndroidTest

# Lint
./gradlew lintDebug
```

## Troubleshooting

### Service not starting
```bash
adb shell am start-foreground-service com.company.mdm/.service.MqttForegroundService
adb logcat | grep MqttForegroundService
```

### MQTT connection issues
```bash
# Test connectivity
adb shell ping mqtt.yourserver.com

# View MQTT logs
adb logcat | grep -i mqtt
```

### Device Owner issues
```bash
# Check status
adb shell dumpsys device_policy | grep "Device Owner"

# Remove and reset
adb shell dpm remove-active-admin com.company.mdm/.admin.MdmDeviceAdminReceiver
```

See [DEPLOYMENT.md](DEPLOYMENT.md) for comprehensive troubleshooting.

## Requirements

- **Minimum SDK:** 28 (Android 9.0)
- **Target SDK:** 34 (Android 14)
- **Compile SDK:** 34
- **JDK:** 17
- **Gradle:** 8.0+
- **Device Owner privileges required** for full functionality

## Dependencies

Key dependencies:
- AndroidX Core, AppCompat, Lifecycle
- Hilt 2.50
- Room 2.6.1
- WorkManager 2.9.0
- Paho MQTT 1.2.5
- Gson 2.10.1
- Timber 5.0.1
- Google Play Services Location 21.1.0

See `app/build.gradle.kts` for complete dependency list.

## License

Proprietary - Internal use only

## Support

For issues:
1. Check logs: `adb logcat | grep com.company.mdm`
2. Review audit log in database
3. Verify Device Owner status
4. Check MQTT connectivity
5. Review [DEPLOYMENT.md](DEPLOYMENT.md) troubleshooting section

## Roadmap

**Phase 1: Backend** ✅ Complete
- Core MDM functionality
- MQTT communication
- Command processing
- Device Owner integration

**Phase 2: UI** 🚧 Next
- Enrollment flow
- Management interface
- Kiosk UI components

**Phase 3: Enhancement**
- Advanced policies
- Enhanced reporting
- Remote control features
- Multi-tenant support

---

Built with ❤️ for enterprise device management