# abtonmoy/wally architecture

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

- Interactive diagram: https://gitdiagram.com/abtonmoy/wally
- Repository: https://github.com/abtonmoy/wally

## Overview

##### Project Type and Purpose
- WALLY is a modular robotics platform combining embedded firmware (Arduino), on-board compute (Jetson Nano running Python), sensor interfaces, navigation algorithms, and security (face recognition).
- It’s neither a typical web app nor a pure library—it’s an embedded full-stack system: hardware + firmware + application software + simulation/test harness.

##### File-Structure Analysis
- Top-level components:
- arduino/: Firmware for Arduino Mega (motor control, sensor interfacing).
- authentication/: Python-based face-recognition and lock system.
- devices/: Python wrappers for hardware sensors (camera, GPS, LiDAR, ultrasonic, compass).
- navigation/: Core navigation algorithms (FTG, hybrid, vision-enhanced, waypoint).
- simulation/: Virtual testing of navigation.
- test_applications/: Client/server demos for remote control and calibration.
- main.py: “Mission Control” entry point that ties modules together.
- Supporting files: requirements.txt for dependencies, LICENSE, README, PDF report.

##### README Insights
- Hardware stack: Jetson Nano (compute), Arduino Mega (motor/sensor I/O), Polulu motors, LiDAR, GPS, camera, ultrasonic, compass, battery.
- Software stack: Python 3.7+, OpenCV, face-recognition (LBPH), FTG, hybrid nav, logging, remote client/server.
- Architecture:
- Jetson Nano runs high-level logic (navigation, authentication, data logging).
- Arduino handles low-level motor control and reads raw sensors.
- Communication via USB serial.
- Simulation layer for offline testing.

a. Main Components (Containers)
1. Hardware Layer
- Arduino Mega (firmware)
- On-board Sensors: LiDAR, GPS module, ultrasonic, digital compass, webcam
- Actuators: Polulu motors
- Power supply
2. Jetson Nano (Software Host)
- Devices module (sensor wrappers)
- Navigation module (FTG, hybrid, vision)
- Authentication module (face detection, recognition, lock system)
- Main application (mission control)
- Data storage (local logs, face templates)
3. External Interfaces
- Remote client/server (test_applications)
- User/operator (via CLI or future mobile/web UI)
- Simulation environment
b. Relationships and Interactions
- Serial link (USB) between Jetson Nano ↔ Arduino Mega
- Devices module reads sensor data → feeds navigation and authentication
- Navigation outputs motion commands → sent to Arduino → drives motors
- Authentication monitors camera feed → grants/revokes access → lock_system ops
- Logging subsystem records events (navigation state, auth attempts) to local storage
- Remote client communicates with main.py over network for telemetry/control
- Simulation harness replaces real sensors with virtual streams, interacts with navigation module
c. Architectural Patterns & Principles
- Layered architecture: Hardware interface → Devices abstraction → Domain logic (navigation/auth) → Orchestration (main.py) → External interfaces (remote, simulation)
- Modularity: Each concern (navigation, authentication, sensor I/O) is a separate Python package
- Dependency injection: high-level modules depend on abstracted device interfaces
- Separation of concerns: embedded firmware vs high-level AI/vision logic
d. Key Technologies
- Python 3.x, OpenCV, RPLidar library, serial communication (pySerial), LBPHFaceRecognizer
- Arduino C++ (Robot.ino, motor.h, bot.h)
- Jetson Nano platform

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        ArduinoMega["Arduino Mega Firmware"]:::hardware
        subgraph "Sensors"
            direction TB
            LiDAR["LiDAR"]:::hardware
            GPS["GPS Module"]:::hardware
            Ultrasonic["Ultrasonic Sensor"]:::hardware
            Compass["Digital Compass"]:::hardware
            Camera["Webcam"]:::hardware
        end
        PololuMotors["Pololu Motors"]:::hardware
        PowerSupply["Power Supply"]:::hardware
    end

    %% Software Host
    subgraph "Jetson Nano (Software Host)"
        direction TB
        subgraph "Devices Module"
            direction TB
            CameraDrv["camera.py"]:::software
            CompassDrv["compass.py"]:::software
            GPSDrv["gps.py"]:::software
            LidarDrv["lidar.py"]:::software
            UltrasonicDrv["ultrasonic.py"]:::software
        end
        subgraph "Navigation Module"
            direction TB
            FTG["ftg.py"]:::software
            Hybrid["hybrid.py"]:::software
            VisionNav["navigation_vision_enhanced.py"]:::software
            VideoCP["nav_video_w_cp.py"]:::software
            Vision["vision.py"]:::software
            Waypoint["waypoint.py"]:::software
            NavMain["main_navigation.py"]:::software
        end
        subgraph "Authentication Module"
            direction TB
            AuthMain["main.py"]:::software
            FaceRec["operations/face_recognition.py"]:::software
            LockSys["operations/lock_system.py"]:::software
            DataMgmt["operations/data_management.py"]:::software
            AuthReq["requirements.txt"]:::software
        end
        MissionControl["Main Application (mission_control)"]:::software
        DataStorage["Local Logs & Face Templates"]:::datastore
    end

    %% External Interfaces
    subgraph "External Interfaces"
        direction TB
        subgraph "Test Applications"
            direction TB
            Client["client.py"]:::external
            Server["server.py"]:::external
            TestGPS["gps.py"]:::external
        end
        RemoteClient["Remote Client"]:::external
        UserOperator["User/Operator"]:::external
        SimulationEnv["Simulation Environment"]:::simulation
    end

    %% Connections
    LiDAR -->|"data"| CameraDrv
    GPS -->|"data"| GPSDrv
    Ultrasonic -->|"data"| UltrasonicDrv
    Compass -->|"data"| CompassDrv
    Camera -->|"video"| CameraDrv

    CameraDrv -->|feeds| FTG
    CompassDrv -->|feeds| Hybrid
    GPSDrv -->|feeds| Waypoint
    LidarDrv -->|feeds| VisionNav
    UltrasonicDrv -->|feeds| Hybrid

    FTG -->|nav data| NavMain
    Hybrid -->|nav data| NavMain
    VisionNav -->|nav data| NavMain
    VideoCP -->|video cp| NavMain
    Vision -->|vision| NavMain
    Waypoint -->|waypoint| NavMain

    NavMain -->|commands| MissionControl
    AuthMain -->|auth results| MissionControl

    MissionControl -->|USB-Serial| ArduinoMega
    MissionControl -->|logs| DataStorage
    NavMain -->|logs| DataStorage
    AuthMain -->|logs| DataStorage

    Client -->|TCP/IP| MissionControl
    Server -->|TCP/IP| MissionControl
    SimulationEnv -->|virtual sensors| CameraDrv
    SimulationEnv -->|virtual sensors| GPSDrv
    SimulationEnv -->|virtual sensors| LidarDrv
    SimulationEnv -->|controls| MissionControl

    %% Click Events
    click ArduinoMega "https://github.com/abtonmoy/wally/blob/main/arduino/Robot.ino"
    click ArduinoMega "https://github.com/abtonmoy/wally/blob/main/arduino/bot.h"
    click ArduinoMega "https://github.com/abtonmoy/wally/blob/main/arduino/motor.h"
    click AuthMain "https://github.com/abtonmoy/wally/blob/main/authentication/main.py"
    click FaceRec "https://github.com/abtonmoy/wally/blob/main/authentication/operations/face_recognition.py"
    click LockSys "https://github.com/abtonmoy/wally/blob/main/authentication/operations/lock_system.py"
    click DataMgmt "https://github.com/abtonmoy/wally/blob/main/authentication/operations/data_management.py"
    click AuthReq "https://github.com/abtonmoy/wally/blob/main/authentication/requirements.txt"
    click CameraDrv "https://github.com/abtonmoy/wally/blob/main/devices/camera.py"
    click CompassDrv "https://github.com/abtonmoy/wally/blob/main/devices/compass.py"
    click GPSDrv "https://github.com/abtonmoy/wally/blob/main/devices/gps.py"
    click LidarDrv "https://github.com/abtonmoy/wally/blob/main/devices/lidar.py"
    click UltrasonicDrv "https://github.com/abtonmoy/wally/blob/main/devices/ultrasonic.py"
    click FTG "https://github.com/abtonmoy/wally/blob/main/navigation/ftg.py"
    click Hybrid "https://github.com/abtonmoy/wally/blob/main/navigation/hybrid.py"
    click VisionNav "https://github.com/abtonmoy/wally/blob/main/navigation/navigation_vision_enhanced.py"
    click VideoCP "https://github.com/abtonmoy/wally/blob/main/navigation/nav_video_w_cp.py"
    click Vision "https://github.com/abtonmoy/wally/blob/main/navigation/vision.py"
    click Waypoint "https://github.com/abtonmoy/wally/blob/main/navigation/waypoint.py"
    click NavMain "https://github.com/abtonmoy/wally/blob/main/navigation/main_navigation.py"
    click SimulationEnv "https://github.com/abtonmoy/wally/blob/main/simulation/nav_demo.py"
    click SimulationEnv "https://github.com/abtonmoy/wally/blob/main/simulation/utils.py"
    click Client "https://github.com/abtonmoy/wally/blob/main/test_applications/client.py"
    click Server "https://github.com/abtonmoy/wally/blob/main/test_applications/server.py"
    click TestGPS "https://github.com/abtonmoy/wally/blob/main/test_applications/gps.py"
    click MissionControl "https://github.com/abtonmoy/wally/blob/main/main.py"
    click DataStorage "https://github.com/abtonmoy/wally/blob/main/requirements.txt"
    click DataStorage "https://github.com/abtonmoy/wally/blob/main/README.md"
    click DataStorage "https://github.com/abtonmoy/wally/tree/main/LICENSE"
    click DataStorage "https://github.com/abtonmoy/wally/blob/main/Report_Wally.pdf"

    %% Styles
    classDef hardware fill:#f9d5a2,stroke:#e8853f
    classDef software fill:#a2d5f9,stroke:#3395e0
    classDef datastore fill:#a2f9a2,stroke:#3eba46
    classDef simulation fill:#d3d3d3,stroke:#888
    classDef external fill:#c2f9a2,stroke:#6a994e
```
