# ammaar-alam/doorunlocker architecture

> Architecture diagram of the GitHub repository ammaar-alam/doorunlocker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ammaar-alam/doorunlocker
- Repository: https://github.com/ammaar-alam/doorunlocker

## Overview

##### Main Components
- Hardware & IoT Device:
- Arduino Nano ESP32 Connect loaded with various Arduino sketches (e.g., ble_control.ino, doorOpener.ino, wifi-diagnosis.ino).
- Attached hardware components such as the L298N Motor Driver and 24V DC Motor.
- Integration with Arduino IoT Cloud for connectivity (both WiFi and BLE options).

- Backend Server:
- Built using Node.js and Express.js (evident both in the root server.mjs and the backend/proxyServer directory).
- Exposes RESTful API endpoints (/login, /command, /emergency-close, /status) for controlling and monitoring the door.

- Client Applications:
- iOS Application (“Ammaar’s Dorm Controls” folder), which uses Swift with a structured MVC-like pattern (with Views, ViewModels, Models, Services, and Assets).
- A web interface front-end coming from the “public” folder (HTML, CSS, JS) that supports door control features.

- Supporting Documentation & Configuration:
- Docs folder outlining API guides, troubleshooting, and user documentation.
- Environment configuration files such as .env.example and package.json for dependency management.

##### Interactions and Data Flow
- User Interaction:
- End users interact through either the iOS app or the web interface, which send API requests (via HTTP/REST) to the backend server.

- Backend Processing:
- The Node.js backend, upon receiving API requests, processes authentication (JWT authentication), door command logic, and status reports.
- A separate “proxyServer” may manage specific task routing, possibly acting as a relay between different segments.

- IoT Connectivity:
- The backend communicates with the Arduino IoT Cloud (or directly with the hardware, depending on configuration) to relay commands.
- The Arduino sketches on the ESP32 device then drive the physical motor through the motor driver.
- There is also support for BLE for local operations – think of it as an alternative flow that bypasses some internet layers for a quicker local control.

##### Important Architectural Patterns and Technologies
- Client-Server Architecture is central:
- Loose coupling between the frontend (iOS app and web UI) and backend REST API.
- Clear separation of concerns:
- iOS client has dedicated ViewModels, Views, and Services that abstract the REST interactions.
- The Node.js server manages business logic, API routing, and IoT connectivity.
- IoT Integration Pattern:
- The physical door control system (Arduino + motor driver) works as an edge device that receives commands through the cloud (Arduino IoT Cloud) and local BLE.
- Utilization of JWT for secure authentication in API calls.
- Use of standard configuration files (like .env and package.json) to orchestrate the system.

- Incorporate labels for important technologies (Node.js/Express.js, Arduino IoT Cloud, Swift, BLE).
- Provide annotations on API endpoints and additional notes on security and configuration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Applications"
        iOSClient["iOS App (Ammaar's Dorm Controls)"]:::client
        WebInterface["Web Interface"]:::client
    end

    subgraph "Backend Server"
        NodeServer["Node.js Server"]:::backend
        ProxyServer["Proxy Server"]:::backend
    end

    IoTCloud["Arduino IoT Cloud"]:::external

    subgraph "Hardware & IoT Device"
        ESP32["Arduino Nano ESP32 Connect"]:::hardware
        subgraph "Firmware"
            Firmware_BLE["ble_control.ino"]:::hardware
            Firmware_DoorOpener["doorOpener.ino"]:::hardware
            Firmware_Wifi["wifi-diagnosis.ino"]:::hardware
            Firmware_Sketch["sketch.json"]:::hardware
            Firmware_ThingProperties["thingproperties.h"]:::hardware
        end
        MotorDriver["L298N Motor Driver"]:::hardware
        DCMotor["24V DC Motor"]:::hardware
    end

    subgraph "Documentation & Configuration"
        Docs["Documentation"]:::config
        PkgRoot["package.json (Root)"]:::config
        PkgProxy["package.json (Proxy)"]:::config
        ArduinoSecrets["arduino_secrets.example"]:::config
    end

    iOSClient -->|"HTTP/REST"| NodeServer
    WebInterface -->|"HTTP/REST"| NodeServer
    NodeServer -->|"Routes"| ProxyServer
    NodeServer -->|"Sends_Command"| IoTCloud
    ProxyServer -->|"Relays_Command"| IoTCloud
    IoTCloud -->|"WiFi_Command"| ESP32
    ESP32 -->|"Drives"| MotorDriver
    MotorDriver -->|"Powers"| DCMotor
    iOSClient ---|"BLE"| ESP32

    click iOSClient "https://github.com/ammaar-alam/doorunlocker/tree/main/Ammaar's Dorm Controls/Ammaar's Dorm Controls"
    click WebInterface "https://github.com/ammaar-alam/doorunlocker/tree/main/public"
    click NodeServer "https://github.com/ammaar-alam/doorunlocker/blob/main/server.mjs"
    click ProxyServer "https://github.com/ammaar-alam/doorunlocker/blob/main/backend/proxyServer/proxyServer.mjs"
    click Firmware_BLE "https://github.com/ammaar-alam/doorunlocker/blob/main/backend/ble_control.ino"
    click Firmware_DoorOpener "https://github.com/ammaar-alam/doorunlocker/blob/main/backend/doorOpener.ino"
    click Firmware_Wifi "https://github.com/ammaar-alam/doorunlocker/blob/main/backend/wifi-diagnosis.ino"
    click Firmware_Sketch "https://github.com/ammaar-alam/doorunlocker/blob/main/backend/sketch.json"
    click Firmware_ThingProperties "https://github.com/ammaar-alam/doorunlocker/blob/main/backend/thingproperties.h"
    click Docs "https://github.com/ammaar-alam/doorunlocker/tree/main/docs"
    click PkgRoot "https://github.com/ammaar-alam/doorunlocker/blob/main/package.json"
    click PkgProxy "https://github.com/ammaar-alam/doorunlocker/blob/main/backend/proxyServer/package.json"
    click ArduinoSecrets "https://github.com/ammaar-alam/doorunlocker/blob/main/backend/arduino_secrets.example"

    classDef client fill:#f8cbe0,stroke:#f0508a,stroke-width:2px;
    classDef backend fill:#cdeac0,stroke:#77c156,stroke-width:2px;
    classDef hardware fill:#cfe2f3,stroke:#6c8ebf,stroke-width:2px;
    classDef config fill:#fff2cc,stroke:#e2c044,stroke-width:2px;
    classDef external fill:#d9ead3,stroke:#6aa84f,stroke-width:2px;
```
