Files/ComputerAssignments/CA2/code/Structure.md

📱 Android App: Clean MVVM Architecture

📁 Recommended Project Structure

app/
├── src/main/java/com/airmouse/
│   ├── di/                           # Dependency Injection (Hilt)
│   │   ├── AppModule.kt
│   │   ├── NetworkModule.kt
│   │   └── SensorModule.kt
│   ├── domain/                       # Clean Architecture: Domain Layer
│   │   ├── model/                    # Business models (pure Kotlin)
│   │   │   ├── MouseEvent.kt
│   │   │   ├── Gesture.kt
│   │   │   └── ConnectionConfig.kt
│   │   ├── repository/               # Interfaces for data operations
│   │   │   ├── IMouseRepository.kt
│   │   │   ├── IGestureRepository.kt
│   │   │   └── IConnectionRepository.kt
│   │   └── usecase/                  # Business logic (interactors)
│   │       ├── SendMovementUseCase.kt
│   │       ├── DetectGestureUseCase.kt
│   │       └── ConnectToServerUseCase.kt
│   ├── data/                         # Data Layer
│   │   ├── repository/               # Implementations of repository interfaces
│   │   │   ├── MouseRepositoryImpl.kt
│   │   │   └── ConnectionRepositoryImpl.kt
│   │   ├── datasource/               # Local & remote data sources
│   │   │   ├── local/                # Room database, DataStore
│   │   │   │   ├── PreferencesDao.kt
│   │   │   │   └── AppDatabase.kt
│   │   │   └── remote/               # WebSocket, Bluetooth, USB
│   │   │       ├── WebSocketDataSource.kt
│   │   │       ├── BluetoothDataSource.kt
│   │   │       └── UsbDataSource.kt
│   │   └── model/                    # Data models (DTOs)
│   │       ├── NetworkMessage.kt
│   │       └── SensorData.kt
│   ├── presentation/                 # Presentation Layer
│   │   ├── ui/                       # Jetpack Compose Screens
│   │   │   ├── home/
│   │   │   │   ├── HomeScreen.kt
│   │   │   │   ├── HomeViewModel.kt
│   │   │   │   └── HomeState.kt
│   │   │   ├── calibration/
│   │   │   │   ├── CalibrationScreen.kt
│   │   │   │   ├── CalibrationViewModel.kt
│   │   │   │   └── CalibrationState.kt
│   │   │   ├── gesture/
│   │   │   │   ├── GestureStudioScreen.kt
│   │   │   │   ├── GestureStudioViewModel.kt
│   │   │   │   └── GestureStudioState.kt
│   │   │   ├── settings/
│   │   │   │   ├── SettingsScreen.kt
│   │   │   │   ├── SettingsViewModel.kt
│   │   │   │   └── SettingsState.kt
│   │   │   └── components/           # Reusable Compose components
│   │   │       ├── ConnectionCard.kt
│   │   │       ├── SensorDataCard.kt
│   │   │       └── GestureChart.kt
│   │   ├── theme/                    # Material 3 theming
│   │   │   ├── Color.kt
│   │   │   ├── Theme.kt
│   │   │   └── Type.kt
│   │   └── navigation/               # Compose Navigation
│   │       ├── NavGraph.kt
│   │       └── Destinations.kt
│   ├── service/                      # Android Services
│   │   ├── SensorService.kt          # Foreground service for sensor collection
│   │   ├── GestureInferenceService.kt
│   │   ├── ProximityService.kt
│   │   ├── VoiceCommandService.kt
│   │   └── BluetoothHidService.kt
│   ├── utils/                        # Utility classes
│   │   ├── Extensions.kt
│   │   ├── Constants.kt
│   │   └── MathUtils.kt
│   └── AirMouseApplication.kt        # Application class
└── src/main/res/                     # Resources (icons, themes, etc.)

🧱 Core Principles

1. Clean Architecture (Onion): The architecture follows concentric layers: UI → Domain → Data. Dependencies point inward, so the Domain layer (containing your business logic) remains independent of frameworks. For an Air Mouse app, this means the core logic for interpreting gestures and sending mouse commands is completely separate from Android‑specific code.

2. MVVM with Jetpack Compose: The presentation layer uses ViewModel to hold UI state (exposed as StateFlow) and handle user events. The View (Compose UI) observes this state via collectAsState(). This ensures the UI only displays data and sends events, while the ViewModel contains the presentation logic.

3. Repository Pattern: The repository interfaces in the Domain layer are implemented in the Data layer. This abstracts the source of data (network, Bluetooth, USB, local storage). For example, an IMovementRepository can have a WebSocketMovementDataSource and a BluetoothMovementDataSource, both interchangeable without changing the business logic.

4. Dependency Injection (Hilt): All dependencies (repositories, use cases, data sources, services) are injected via Hilt. This makes the code testable and reduces boilerplate.

5. Kotlin Flows for Asynchronous Data: Use StateFlow for UI state, SharedFlow for one‑time events (e.g., showToast), and Flow for continuous data streams (sensor data, incoming WebSocket messages). This integrates seamlessly with Compose.

🔌 Communication Protocols (Choice Matrix)

Select the protocol based on your specific requirements (Wi‑Fi reliability, latency tolerance, security needs, etc.):

Protocol	Overhead	Latency	Pros	Cons	Best for
WebSocket (TCP)	2–14 bytes	Low (stable)	Reliable, ordered, firewall‑friendly, simple API	Head‑of‑line blocking, TCP’s reliability can add jitter	General use on good Wi‑Fi (your primary choice)
UDP + custom ACK	8 bytes	Very low	Lowest latency, no retransmission overhead	Unreliable, packets may arrive out of order	Gaming / ultra‑low‑latency requirements
QUIC	Low (similar to TCP‑TLS)	Lower than TCP	Combines reliability and low latency, 0‑RTT handshake	Emerging, library support varies	Remote connections over the internet
USB HID	<10 bytes	Extremely low	Direct cable, no network issues	Wired only, requires OTG adapter	Professional / stationary use
Bluetooth (HID/GATT)	5–10 bytes	Low (5‑20 ms)	Wireless, standardised HID profile	Range limited, pairing required	Casual / mobile use

For most cases, WebSocket over TCP is the best balance of simplicity and performance. If you later need to support weak networks, QUIC is a great upgrade because it avoids head‑of‑line blocking and allows 0‑RTT connection resumption. USB and Bluetooth HID modes are excellent for local, direct connections.

📡 Message Protocol (Binary for Performance)

Strong recommendation: Use Protocol Buffers (protobuf) or MessagePack instead of JSON. These binary formats are significantly more compact and faster to parse, which is crucial for real‑time applications. Here is a minimal protobuf schema:

syntax = "proto3";

message Movement {
    float dx = 1;
    float dy = 2;
}

message Click {
    string button = 1;
}

message Scroll {
    int32 delta = 1;
}

message Command {
    oneof command_type {
        Movement move = 1;
        Click click = 2;
        DoubleClick double_click = 3;
        Scroll scroll = 4;
        Hello hello = 5;
    }
}

This reduces packet size by 30–50% compared to JSON, lowering latency and saving battery on the phone.

🔐 Security & Data Persistence

• Authentication: Use a short‑lived JWT token generated by the server and exchanged via a QR code. The token is included in the WebSocket upgrade request (ws://server:8080/ws?token=...). This prevents unauthorised clients from controlling the mouse.
• Encryption: On the local network, you may skip TLS for performance, but for any remote connection you must use WSS (WebSocket over TLS) or QUIC (which has built‑in TLS 1.3).
• Local Storage (Room): Store user preferences (sensitivity, thresholds), saved gestures (as templates), and calibration data in a local Room database.
• DataStore: Use Preferences DataStore for simple key‑value settings (e.g., last used IP, theme).

🤖 Sensor Data Collection & Gesture Recognition

• Foreground Service + SensorManager: Use a foreground service (with a persistent notification) to collect gyroscope and accelerometer data, even when the app is in the background. The service registers listeners with SensorManager at the fastest possible rate (SENSOR_DELAY_FASTEST).
• Gesture Recognition Pipeline:
  1. Data Buffer: Maintain a sliding window of the last N sensor events (e.g., 50 samples).
  2. Feature Extraction: Compute angular velocity (gyro), linear acceleration, and orientation (using SensorManager.getRotationMatrixFromVector).
  3. Classification: Feed the features into a TensorFlow Lite model (trained on‑device) that outputs a gesture label and confidence.
  4. Post‑processing: Apply a confidence threshold (≥0.7) and a cooldown (500 ms) to avoid duplicate triggers.
• Optimisation: To reduce battery drain, lower the sensor sampling rate (SENSOR_DELAY_UI) when the phone is idle (detected via accelerometer variance).

💡 Additional Considerations

• Testing: Use the test source set with JUnit, MockK, and Robolectric. Mock external dependencies (WebSocket, Bluetooth) to test the use cases in isolation.
• Error Handling: Use Either or a sealed class (Result<T>) to represent failures (network errors, sensor unavailable). Propagate these to the UI layer.
• Multi‑Module Setup: Separate features into independent modules for better build times and team scalability: :core:domain, :core:data, :feature:home, :feature:calibration, etc.

The Android app is now designed to be scalable, testable, and maintainable while delivering a smooth real‑time mouse control experience.

---

🖥️ Go Server: Clean Architecture with Modular Design

📁 Recommended Project Structure

airmouse-go/
├── cmd/
│   └── airmouse-server/
│       └── main.go                 # Entry point, DI container
├── internal/
│   ├── domain/                     # Domain Layer (pure business logic)
│   │   ├── entity/                 # Core business objects
│   │   │   ├── mouse.go
│   │   │   ├── gesture.go
│   │   │   └── client.go
│   │   ├── repository/             # Repository interfaces (for data access)
│   │   │   ├── mouse_repository.go
│   │   │   ├── gesture_repository.go
│   │   │   └── client_repository.go
│   │   └── service/                # Business logic / Use Cases
│   │       ├── mouse_service.go
│   │       ├── gesture_service.go
│   │       └── connection_service.go
│   ├── repository/                 # Data Layer
│   │   ├── mouse_repository_impl.go
│   │   ├── gesture_repository_impl.go
│   │   ├── client_repository_impl.go
│   │   └── config/                 # Configuration (JSON, env)
│   │       └── config.go
│   ├── handler/                    # Delivery Layer (HTTP, WebSocket)
│   │   ├── websocket/
│   │   │   ├── handler.go
│   │   │   ├── client.go
│   │   │   └── hub.go
│   │   ├── http/
│   │   │   ├── router.go
│   │   │   └── middleware.go
│   │   └── dto/                    # Data Transfer Objects
│   │       ├── message.go
│   │       └── response.go
│   ├── infra/                      # Infrastructure (external dependencies)
│   │   ├── mouse/                  # Platform‑specific mouse control
│   │   │   ├── mouse.go            # Interface
│   │   │   ├── windows.go
│   │   │   ├── darwin.go
│   │   │   └── linux.go
│   │   ├── bluetooth/              # BLE, HID
│   │   │   └── manager.go
│   │   ├── usb/                    # USB gadget mode
│   │   │   └── gadget.go
│   │   └── logger/                 # Structured logging
│   │       └── logger.go
│   └── pkg/                        # Shared utilities
│       ├── errors/                 # Custom error types
│       ├── utils/                  # Helper functions
│       └── config/                 # Configuration loader
├── pkg/                            # Public packages (if any)
├── go.mod
├── go.sum
└── Makefile

🏗️ Core Principles (Clean Architecture)

• Layered Design: The architecture is divided into domain (business rules), repository (data access), handler (delivery), and infra (external dependencies). Dependencies point inward, so the domain layer knows nothing about WebSockets, databases, or OS‑specific mouse code.
• Dependency Injection: In main.go, you manually wire all dependencies. The infra implementations are passed to the constructors of the repository and service layers. This makes the code testable (mock implementations can be substituted).
• Concurrency: Use goroutines and channels for handling multiple clients. The WebSocket hub pattern (from gorilla/websocket) is perfect for broadcasting messages to all connected clients.
• Configuration: Use a config.go that reads from a JSON file and environment variables. All config values are passed to the services at startup.

🧭 Communication Protocol Recommendations (Go Server)

The server is designed to support multiple protocols simultaneously, allowing the client to choose the best one. The recommended primary protocol is WebSocket over TCP because of its simplicity and reliability.

Protocol	Library	Use Case
WebSocket	github.com/gorilla/websocket	Primary protocol (Wi‑Fi, internet)
QUIC	github.com/quic-go/quic-go	Upgrade for low‑latency remote connections
UDP	net	Custom UDP + lightweight ACK
TCP	net	Plain TCP fallback
Bluetooth	github.com/go-ble/ble	BLE GATT service (discovery, not for data)
USB	github.com/karalabe/hid	USB gadget mode (emulate HID device)

You can implement a Transport interface and register all active transports in a central Hub. Each transport receives incoming messages, decodes them, and forwards them to the appropriate use case (e.g., MouseService.Move). Responses are sent back through the same transport.

📦 Message Processing Pipeline

1. WebSocket Handler: Upgrades HTTP connection, reads messages as binary (protobuf), and passes them to a MessageProcessor.
2. MessageProcessor: Decodes the protobuf message and determines the type (move, click, hello). It then invokes the appropriate use case (e.g., mouseService.Move).
3. Use Case (Service): Contains the business logic (e.g., apply sensitivity, filtering, gesture detection). It may call a repository (e.g., to store statistics).
4. Repository: Accesses infrastructure (e.g., in‑memory storage for statistics, configuration).
5. Response: The use case returns a result, which the MessageProcessor encodes back to protobuf and sends to the WebSocket client.

🔧 Infrastructure Implementations

• Mouse Control: Platform‑specific files (mouse_windows.go, mouse_darwin.go, mouse_linux.go) implement the Mouse interface using native APIs (Win32 API, CoreGraphics, uinput).
• Bluetooth: The bluetooth package implements GATT services for discovery and pairing. It does not stream cursor data (use WebSocket for that).
• USB Gadget Mode: The usb package uses linux/configfs (on supported devices) to emulate a USB HID mouse without any client software on the PC.
• Logging: Structured logging with slog (Go 1.21+) or a third‑party library like zerolog. Each log entry includes a correlation ID to trace a request across multiple services.

🤖 AI and Personalization

• ONNX Runtime: Use github.com/yalue/onnxruntime_go to load and execute the LSTM model for trajectory prediction. The inference runs in a separate goroutine (using a worker pool).
• Data Collector: The personalization package collects movement samples (position, velocity, timestamp) and stores them in a circular buffer. When enough samples are collected, it triggers a HTTP call to a Python fine‑tuning service (running on localhost:5001). The updated model is then loaded via ONNX Runtime.

🧪 Testing & Observability

• Unit Tests: Write tests for each use case using the testing package and mocks for repositories.
• Integration Tests: Test the WebSocket handler with a real client.
• Metrics: Expose Prometheus metrics (requests per second, active connections, latency) on an /metrics endpoint.
• Health Check: Provide a /health endpoint that returns 200 OK when the server is ready.

The Go server is now designed to be modular, highly performant, and horizontally scalable. Each layer is decoupled, allowing you to replace any component (e.g., switch from WebSocket to QUIC) without affecting the business logic. This architecture supports high‑concurrency (thousands of simultaneous clients) while maintaining sub‑20ms latency for cursor movement.

---

🤝 Cross-Project Synchronisation

To keep the Android app and Go server in sync, follow these guidelines:

• Shared Protocol Buffer Schema: Maintain a single airmouse.proto file in a separate repository. Both projects generate code from this file (using the protobuf compiler). This ensures that message structures never become misaligned.
• API Versioning: Prefix your WebSocket endpoint with a version, e.g., /ws/v1/. This allows you to introduce breaking changes later.
• Continuous Integration: Set up a CI pipeline that, on any change to the .proto file, automatically regenerates the code for both projects and runs the full test suite.
• Version Tags: Tag releases with semantic versioning (e.g., v1.2.3) and update the Android app’s build script to require a minimum server version.