DesktopBot - Modular Android Application

A sophisticated Android application built with strict modular architecture to demonstrate clean separation of concerns, scalability, and maintainability.

🎯 Project Overview

DesktopBot is an intelligent Android application that integrates multiple technologies:

• 📷 Camera - Real-time frame capture
• 🤖 Machine Learning - Face detection and head movement tracking
• 🧠 Large Language Model - Decision-making and command generation
• 📡 Bluetooth - BLE communication with external devices
• 😊 Facial Expressions - Emotion display based on AI decisions
• 🎨 User Interface - Interactive controls and status updates

🏗️ Architecture

This project follows a strictly enforced modular architecture where:

• Each module has a single, well-defined responsibility
• All inter-module communication flows through the AppCoordinator
• Direct module-to-module access is prohibited
• Each module owns its hardware, permissions, and domain logic

Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│                        APP MODULE                            │
│                    (AppCoordinator)                          │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                  Data Flows                          │  │
│  │                                                      │  │
│  │  Camera → ML → LLM → Face                           │  │
│  │  Bluetooth ↔ LLM                                    │  │
│  │  UI ↔ All Modules                                   │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Modules

Module	Responsibility
app	Entry point, coordination, module initialization
bluetooth	BLE operations, scanning, pairing, data transfer
camera	Camera access, frame capture, camera permissions
ml	ML models, face detection, head movement analysis
llm	LLM processing, decision logic, command generation
face	Facial expression display, emotion rendering
ui	User interface, user interactions, status display

📋 Requirements

• Android Studio: Arctic Fox or newer
• Minimum SDK: 28 (Android 9.0)
• Target SDK: 36
• Kotlin: 2.0.21
• Gradle: 8.13.2+

🚀 Getting Started

1. Clone the Repository

git clone https://github.com/yourusername/desktopbot.git
cd desktopbot

2. Open in Android Studio

• Open Android Studio
• Select "Open an Existing Project"
• Navigate to the desktopbot folder
• Wait for Gradle sync to complete

3. Build the Project

./gradlew build

Or use Android Studio's build menu.

4. Run the App

• Connect an Android device or start an emulator
• Click the "Run" button in Android Studio
• Grant necessary permissions when prompted

🔑 Permissions

The app requires the following permissions:

• Camera - For real-time frame capture
• Bluetooth - For BLE device communication
• Location (Android < 12) - Required for BLE scanning

Permissions are handled within their respective modules:

• Camera permissions → camera module
• Bluetooth permissions → bluetooth module

📚 Documentation

• ARCHITECTURE.md - Complete architecture documentation
• QUICK_REFERENCE.md - Quick reference guide for developers

🏛️ Architecture Rules

⚠️ GOLDEN RULES

1. NO direct module-to-module communication
2. ALL communication goes through AppCoordinator
3. Each module owns its hardware/permissions
4. No architecture breaks without approval

Data Flow

Camera → ML → LLM → Face
Bluetooth ↔ LLM
UI ↔ AppCoordinator ↔ All Modules

📁 Project Structure

desktopbot/
├── app/                          # Main entry module
│   └── src/main/java/com/ad/desktopbot/
│       ├── MainActivity.kt       # Entry point
│       └── core/
│           ├── ModuleInterfaces.kt   # All interfaces & data models
│           └── AppCoordinator.kt     # Central orchestrator
│
├── bluetooth/                    # Bluetooth module
│   └── src/main/java/com/ad/bluetooth/
│       ├── BluetoothRepository.kt
│       └── BluetoothControllerImpl.kt
│
├── camera/                       # Camera module
│   └── src/main/java/com/ad/camera/
│       ├── CameraRepository.kt
│       └── CameraControllerImpl.kt
│
├── ml/                          # ML module
│   └── src/main/java/com/ad/ml/
│       ├── MLRepository.kt
│       └── MLControllerImpl.kt
│
├── llm/                         # LLM module
│   └── src/main/java/com/ad/llm/
│       ├── LLMRepository.kt
│       └── LLMControllerImpl.kt
│
├── face/                        # Face expression module
│   └── src/main/java/com/ad/face/
│       ├── FaceRepository.kt
│       └── FaceControllerImpl.kt
│
└── ui/                          # UI module
    └── src/main/java/com/ad/ui/
        ├── UIRepository.kt
        └── UIControllerImpl.kt

🧩 Module Details

App Module

• Contains the AppCoordinator - the only component that orchestrates module communication
• Defines all module interfaces and data models
• Initializes all modules in MainActivity

Bluetooth Module

• Manages BLE scanning, connection, and data transfer
• Receives data from Bluetooth devices → sends to LLM
• Receives JSON commands from LLM → transmits to devices
• Handles all Bluetooth permissions

Camera Module

• Manages camera lifecycle and frame capture
• Uses CameraX for modern camera API
• Sends frames to ML module for processing
• Handles camera permissions

ML Module

• Loads and runs ML models
• Performs face detection and head movement analysis
• Sends results to LLM module
• TODO: Integrate actual ML models (TensorFlow Lite, ML Kit)

LLM Module

• Acts as the "brain" of the application
• Processes data from ML and Bluetooth modules
• Generates JSON commands for Bluetooth devices
• Generates emotion data for Face module
• TODO: Integrate actual LLM model

Face Module

• Displays facial expressions based on LLM emotion data
• TODO: Implement actual emotion rendering (UI animations, physical servos)

UI Module

• Manages all user interface elements
• Displays status updates and results
• Forwards user actions to other modules via AppCoordinator

🛠️ Development

Adding a New Feature

1. Identify the owning module - Which module should handle this?
2. Update the interface - Add method to the controller interface in ModuleInterfaces.kt
3. Implement in repository - Add implementation in the module's repository
4. Update controller - Update the controller implementation
5. Update AppCoordinator - If data flow changes are needed

Requesting Architecture Change

If a new feature doesn't fit the existing architecture:

1. Create a proposal with:

   • Reason for breaking existing architecture
   • Proposed module name and responsibilities
   • Communication requirements
   • Why existing modules can't handle it

2. Get approval before implementing

🧪 Testing

Unit Tests

Each module can be tested independently:

./gradlew test

Integration Tests

./gradlew connectedAndroidTest

Testing Strategy

• Unit test each module's repository independently
• Mock callbacks for testing
• Integration test data flows through AppCoordinator
• UI test user interactions

🐛 Debugging

Check Data Flow

1. Look at AppCoordinator callbacks
2. Verify module controller implementations
3. Check callback setup in setupDataFlows()
4. Check logcat with module TAGs:
   • AppCoordinator
   • BluetoothRepository
   • CameraRepository
   • MLRepository
   • LLMRepository
   • FaceRepository
   • UIRepository

📦 Dependencies

Core Dependencies

• AndroidX Core KTX
• AndroidX AppCompat
• Material Design Components
• AndroidX Activity
• AndroidX ConstraintLayout

Module-Specific Dependencies

• Camera: CameraX (Core, Camera2, Lifecycle, View)
• ML: TODO - TensorFlow Lite or ML Kit
• LLM: TODO - LLM integration

🔄 Future Enhancements

• Integrate actual ML models (TensorFlow Lite)
• Integrate actual LLM model
• Implement physical facial expression rendering
• Add voice recognition (new audio module)
• Add cloud synchronization
• Add comprehensive unit tests
• Add UI tests
• Add performance monitoring

🤝 Contributing

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

Note: All contributions must follow the modular architecture. Any architecture-breaking changes require approval.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Authors

• Your Name - Initial work

🙏 Acknowledgments

• Android Architecture Components
• CameraX
• Kotlin Coroutines
• Material Design

📞 Support

For questions or issues:

• Open an issue on GitHub
• Check the ARCHITECTURE.md documentation
• Refer to QUICK_REFERENCE.md

---

Remember: This architecture exists to keep the codebase clean, maintainable, and scalable. Follow the rules! 🚀