# harnan01/e19-3yp-automated-grass-cutter architecture

> Architecture diagram of the GitHub repository harnan01/e19-3yp-automated-grass-cutter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harnan01/e19-3yp-automated-grass-cutter
- Repository: https://github.com/harnan01/e19-3yp-automated-grass-cutter

## Overview

##### Project type and purpose
- This is a full-stack IoT application for an Automated Grass Cutter.
- It consists of three major layers:
a. A mobile frontend (React Native) for user interaction
b. A Java Spring Boot backend (REST API, security, persistence, MQTT integration)
c. Embedded firmware on Arduino/ESP32 devices controlling the mower hardware

##### File structure to extract architectural components
- Top level directories:
- Frontend – React Native app (screens, API wrapper)
- Backend – Maven-based Spring Boot service (controllers, services, repositories, MQTT config, Cognito security)
- Hardware – Two PlatformIO projects (Arduino and ESP32 firmware)
- docs – Static site assets and instructions

- Key backend packages:
- com.example.grasscutter.MQTT – MQTTConfig for broker integration
- com.example.grasscutter.MobileApplication.User – AWS Cognito setup, controllers, DTOs, services, repositories
- com.example.grasscutter.MobileApplication.Device – device management REST endpoints, authentication, persistence

##### README for additional context
- High-level goal: fully automated lawn mowing
- Implied use of cloud services for user auth, message brokering, and data storage

##### Main components
a. Mobile App (React Native)
- Screens: Login/SignUp, AddDevice, Home, Manual/Auto control
- Connects over HTTPS to Backend REST API

b. Backend Service (Spring Boot)
- REST API Layer (DeviceController, UserController)
- Service Layer (UserService, DeviceAuthenticationService)
- Persistence Layer (UserRepository, DeviceRepository → relational DB)
- Security Module (AWS Cognito integration via SecurityConfig, CognitoConfig)
- Messaging Module (MQTTConfig → publishes commands, subscribes to telemetry)

c. Cloud Services
- AWS Cognito (user authentication & federation)
- MQTT Broker (e.g., Mosquitto or cloud-hosted EMQX)

d. Database
- Relational DB (PostgreSQL/MySQL/H2 – as configured in application.yml)

e. Hardware Devices
- ESP32 / Arduino microcontrollers
- Firmware subscribes to MQTT topics for commands, publishes sensor data/telemetry

f. Documentation Site
- Static docs (docs folder) served separately (e.g., GitHub Pages)

##### Relationships and interactions
1. User opens the Mobile App → authenticates via AWS Cognito (App ↔ Cognito).
2. Upon login, Mobile App calls Backend REST endpoints (HTTPS).
3. Backend validates JWT tokens issued by Cognito, loads user/device data from the DB.
4. For manual or scheduled cut commands, Backend publishes MQTT messages to device topics.
5. Devices (ESP32/Arduino) subscribed to those topics receive commands, actuate hardware, and send telemetry back on another MQTT topic.
6. Backend subscribes to telemetry topics, processes data (e.g., angle/distance readings), persists relevant events to the DB.
7. Mobile App may poll or receive push-style updates (via REST or a real-time channel) to display device status.

##### Architectural patterns and design principles
- Layered MVC in the backend (Controller → Service → Repository)
- Message broker pattern for decoupled communication between backend and devices
- Externalized configuration (application.yml, PlatformIO ini files)
- Single-page app structure in React Native (screens, API module)
- Clear separation of concerns: Auth, Device management, Messaging

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        MobileApp["Mobile App (React Native)"]:::frontend
        APIWrapper["API Wrapper"]:::frontend
        Screens["Screens\n(Login/SignUp, Home, AddDevice, Manual/Auto)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Service (Spring Boot)"
        direction TB
        subgraph "REST API Layer"
            direction TB
            UserController["UserController"]:::backend
            DeviceController["DeviceController"]:::backend
        end
        subgraph "Service Layer"
            direction TB
            UserService["UserService / UserServiceImpl"]:::backend
            DeviceAuthService["DeviceAuthenticationService"]:::backend
        end
        subgraph "Persistence Layer"
            direction TB
            UserRepo["UserRepository"]:::backend
            DeviceRepo["DeviceRepository"]:::backend
            DB["Relational DB\n(PostgreSQL/MySQL/H2)"]:::backend
        end
        subgraph "Security Module"
            direction TB
            CognitoConfig["CognitoConfig"]:::backend
            SecurityConfig["SecurityConfig"]:::backend
        end
        subgraph "Messaging Module"
            direction TB
            MQTTConfig["MQTTConfig"]:::backend
        end
        ConfigYML["application.yml"]:::backend
    end

    %% Hardware Layer
    subgraph "Hardware Devices"
        direction TB
        Arduino["Arduino Firmware"]:::hardware
        ESP32["ESP32 Firmware"]:::hardware
    end

    %% External Services
    Cognito["AWS Cognito"]:::external
    MQTTBroker["MQTT Broker"]:::external

    %% Documentation
    Docs["Documentation Site"]:::external

    %% Connections
    MobileApp -->|HTTPS/JSON\nAuthenticate| Cognito
    MobileApp -->|HTTPS/JSON\nREST API Calls| UserController
    MobileApp -->|HTTPS/JSON\nREST API Calls| DeviceController
    UserController -->|calls| UserService
    DeviceController -->|calls| DeviceAuthService
    UserService -->|queries| UserRepo
    DeviceAuthService -->|queries| DeviceRepo
    UserRepo -->|persists| DB
    DeviceRepo -->|persists| DB
    SecurityConfig -->|uses| CognitoConfig
    UserController -->|validates JWT| SecurityConfig
    DeviceController -->|validates JWT| SecurityConfig
    DeviceAuthService -->|publishes commands| MQTTBroker
    MQTTBroker -->|subscribes| MQTTConfig
    MQTTBroker -->|publishes telemetry| MQTTConfig
    MQTTConfig -->|stores telemetry| DeviceRepo
    Docs -->|serves| Index["index.html"]

    %% Click Events
    click MobileApp "https://github.com/harnan01/e19-3yp-automated-grass-cutter/tree/main/Frontend/"
    click APIWrapper "https://github.com/harnan01/e19-3yp-automated-grass-cutter/blob/main/Frontend/api/api.js"
    click Screens "https://github.com/harnan01/e19-3yp-automated-grass-cutter/blob/main/Frontend/screens/*.js"
    click UserController "https://github.com/harnan01/e19-3yp-automated-grass-cutter/blob/main/Backend/src/main/java/com/example/grasscutter/MobileApplication/User/UserController.java"
    click DeviceController "https://github.com/harnan01/e19-3yp-automated-grass-cutter/blob/main/Backend/src/main/java/com/example/grasscutter/MobileApplication/Device/DeviceController.java"
    click UserService "https://github.com/harnan01/e19-3yp-automated-grass-cutter/blob/main/Backend/src/main/java/com/example/grasscutter/MobileApplication/User/UserService.java"
    click DeviceAuthService "https://github.com/harnan01/e19-3yp-automated-grass-cutter/blob/main/Backend/src/main/java/com/example/grasscutter/MobileApplication/Device/DeviceAuthenticationService.java"
    click UserRepo "https://github.com/harnan01/e19-3yp-automated-grass-cutter/blob/main/Backend/src/main/java/com/example/grasscutter/MobileApplication/User/UserRepository.java"
    click DeviceRepo "https://github.com/harnan01/e19-3yp-automated-grass-cutter/blob/main/Backend/src/main/java/com/example/grasscutter/MobileApplication/Device/DeviceRepository.java"
    click CognitoConfig "https://github.com/harnan01/e19-3yp-automated-grass-cutter/blob/main/Backend/src/main/java/com/example/grasscutter/MobileApplication/User/CognitoConfig.java"
    click SecurityConfig "https://github.com/harnan01/e19-3yp-automated-grass-cutter/blob/main/Backend/src/main/java/com/example/grasscutter/MobileApplication/User/SecurityConfig.java"
    click MQTTConfig "https://github.com/harnan01/e19-3yp-automated-grass-cutter/blob/main/Backend/src/main/java/com/example/grasscutter/MQTT/MQTTConfig.java"
    click ConfigYML "https://github.com/harnan01/e19-3yp-automated-grass-cutter/blob/main/Backend/src/main/resources/application.yml"
    click Arduino "https://github.com/harnan01/e19-3yp-automated-grass-cutter/tree/main/Hardware/Arduino/"
    click ESP32 "https://github.com/harnan01/e19-3yp-automated-grass-cutter/tree/main/Hardware/ESP32/"
    click Docs "https://github.com/harnan01/e19-3yp-automated-grass-cutter/tree/main/docs/"

    %% Styles
    classDef frontend fill:#D0EBFF,stroke:#333,stroke-width:1px
    classDef backend fill:#DAF5D0,stroke:#333,stroke-width:1px
    classDef hardware fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
```
