# gitbls/autoap architecture

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

- Interactive diagram: https://gitdiagram.com/gitbls/autoap
- Repository: https://github.com/gitbls/autoap

## Overview

##### Project Type and Purpose
- autoAP is a lightweight utility for Raspberry Pi devices. Its aim is to monitor the WiFi connection (using wpa_supplicant) and, if connectivity fails, automatically reconfigure the system – switching from client mode to Access Point mode.
- The README clearly explains installation, required systemd service configuration, network file management, and runtime behavior. It also describes integration points with systemd-networkd and wpa_supplicant through custom scripts.

##### File Structure
- The file tree only lists the LICENSE, README.md, and three scripts (autoAP.sh, install-autoAP, and rpi-networkconfig). Though minimal, these files are central to the tool:
◦ install-autoAP: a script that handles installation details, sets up network configuration files (like 11-wlan0.network, 12-wlan0AP.network, and 10-eth0.network for Ethernet by rpi-networkconfig), and installs systemd service files.
◦ autoAP.sh: the operational script triggered by the systemd service when transitions in WiFi state occur.
◦ rpi-networkconfig: used to reconfigure the Pi’s network management (especially with systemd-networkd).
- Notice that documentation in the README also refers to additional files that are placed in system directories (for example, autoap-local.sh and autoAP.conf) and systemd service definitions (like wpa-autoap@wlan0.service and wpa-autoap-restore.service). These become part of the overall architecture even though they’re created during installation.

##### Main Components
- WiFi Interface (wlan0): Represent the hardware element that can operate in either client mode (to connect to an existing WiFi) or in Access Point mode.
- wpa_supplicant: The standard background process for handling WiFi connections. It is responsible for monitoring the connection status.
- Systemd Services:
- wpa-autoap@wlan0.service: A service that monitors WiFi connection events (using wpa_cli interactions) and calls the autoAP.sh script.
- wpa-autoap-restore.service: A service ensuring the network configuration gets restored on boot or after reboots.
- autoAP.sh: The core script that handles the switch between AP and normal mode. It is triggered by the systemd service based on events from wpa_supplicant.
- autoap-local.sh: A user-modifiable hook script that allows additional processing or triggering of other custom applications when the mode changes.
- Configuration Files:
- /usr/local/bin/autoAP.conf: Contains parameters such as enablewait and disconnectwait.
- Network configuration files under /etc/systemd/network (11-wlan0.network & 12-wlan0AP.network for WiFi, 10-eth0.network for Ethernet).
- rpi-networkconfig: A script that adjusts the OS’s networking.conf so that systemd-networkd manages the network interfaces correctly.

##### Relationships and Data Flow
- At system startup, wpa_supplicant (for wlan0) is started along with its corresponding systemd unit.
- If the Pi fails to connect to the pre-configured WiFi (e.g., due to being away from the home network or router downtime), wpa_supplicant detects a timeout.
- Using wpa_cli, an event is sent that triggers wpa-autoap@wlan0, which in turn calls autoAP.sh.
- autoAP.sh executes the logic to modify the network configuration – switching between the wireless client configuration (11-wlan0.network) and the Access Point configuration (12-wlan0AP.network).
- It then calls autoap-local.sh for any additional custom handling (like starting or stopping custom processes).
- The changes involve restarting systemd-networkd so that the new settings take effect.
- When clients connect/disconnect from the Access Point, parameters like disconnectwait manage how long autoAP waits before trying to re-establish the WiFi connection.
- The installation script install-autoAP is responsible for laying out these configuration files and scripts, ensuring the proper renaming of any existing wpa_supplicant files (to avoid conflicts).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Hardware/Network Layer
    subgraph "Hardware/Network Layer"
        wlan0["wlan0 (WiFi Adapter)"]:::hardware
        eth0["eth0 (Ethernet Adapter)"]:::hardware
    end

    %% Control Layer
    subgraph "Control Layer"
        wpa_supplicant["wpa_supplicant"]:::service
        serviceAP["wpa-autoap@wlan0 service"]:::service
        restoreService["wpa-autoap-restore service"]:::service
        autoAP["autoAP.sh"]:::script
        networkConfig["rpi-networkconfig"]:::script
        systemdNetwork["systemd-networkd"]:::service
        autoapLocal["autoap-local.sh"]:::script
    end

    %% Configuration/Hook Layer
    subgraph "Configuration/Hook Layer"
        autoAPconf["autoAP.conf"]:::config
        netConfigFiles["Network Config Files"]:::config
        installScript["Installation Script"]:::script
    end

    %% Connections between Layers
    wlan0 -->|"interface"| wpa_supplicant
    wpa_supplicant -->|"timeout_event"| serviceAP
    serviceAP -->|"triggers"| autoAP
    autoAP -->|"invokes"| networkConfig
    networkConfig -->|"reconfigures"| systemdNetwork
    autoAP -->|"calls"| autoapLocal
    restoreService -->|"restores"| networkConfig

    installScript -->|"deploys"| netConfigFiles
    installScript -->|"deploys"| autoAPconf
    installScript -->|"installs"| serviceAP
    installScript -->|"installs"| restoreService

    %% Click Events
    click autoAP "https://github.com/gitbls/autoap/blob/master/./autoAP.sh"
    click installScript "https://github.com/gitbls/autoap/tree/master/./install-autoAP"
    click networkConfig "https://github.com/gitbls/autoap/tree/master/./rpi-networkconfig"

    %% Styles
    classDef hardware fill:#a8d5e2,stroke:#333,stroke-width:2px;
    classDef service fill:#f9d6ac,stroke:#333,stroke-width:2px;
    classDef script fill:#d5a6bd,stroke:#333,stroke-width:2px;
    classDef config fill:#cfe2f3,stroke:#333,stroke-width:2px;
```
