# cherryshine/project-wifi-autologin architecture

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

- Interactive diagram: https://gitdiagram.com/cherryshine/project-wifi-autologin
- Repository: https://github.com/cherryshine/project-wifi-autologin

## Overview

##### Project type and purpose
- This is a lightweight, macOS-only Hammerspoon automation script (init.lua) that auto-logs into a captive-portal Wi-Fi (`KBU_PUBLIC`).
- Purpose: Detect when macOS connects to `KBU_PUBLIC`, extract dynamic tokens from the portal page, submit credentials, verify internet connectivity, and display status via menu-bar alerts.

##### File structure
- Top-level files only:
- README.md – project description, setup, usage, logs
- init.lua – the entire automation logic
- No subdirectories, no build scripts, no external services inside the repo.

##### Key insights from README
- Relies on Hammerspoon’s Lua API (`hs.wifi`, `hs.http`, `hs.timer`, `hs.alert`).
- Workflow: Wi-Fi state change → captive-portal detection → HTTP GET/POST → token parsing → login confirmation → user alert.
- Dependencies: macOS, Hammerspoon, plain text credentials.

##### Main components
a. Hammerspoon host (macOS runtime)
b. Network subsystem (macOS Wi-Fi driver / Captive Portal)
c. Script modules inside init.lua:
- Wi-Fi Watcher (hs.wifi callback)
- HTTP Client (hs.http.request)
- Token Extractor (pattern matching in HTML)
- Login Manager (POST credentials + token)
- Connectivity Checker (simple GET to known site)
- Notifier (hs.alert for menu-bar notifications)
d. External systems:
- Captive Portal Web Server (login page endpoint)
- Internet (target site for connectivity test)

##### Architectural patterns and principles
- Event-driven: trigger on network state changes
- Modular separation: each logical concern (watching, HTTP, parsing, notifications) lives in its own function or block
- Single-process, single-threaded automation
- Resilience: retry logic on failure, idempotent login attempts

##### Technologies, frameworks, libraries
- Hammerspoon’s Lua environment
- `hs.wifi`, `hs.http`, `hs.timer`, `hs.alert` modules
- Standard Lua string matching for token extraction

## Diagram (Mermaid)

```mermaid
flowchart TD
    HS["Hammerspoon Host (macOS Runtime)"]:::host
    README["README.md"]:::doc

    subgraph "Automation Script (init.lua)"
        WF["Wi-Fi Watcher"]:::internal
        HC["HTTP Client"]:::internal
        TE["Token Extractor"]:::internal
        LM["Login Manager"]:::internal
        CC["Connectivity Checker"]:::internal
        NT["Notifier"]:::internal
    end

    Web["Captive Portal Web Server"]:::external
    Int["Internet (Connectivity Test)"]:::external

    HS -->|"Network Change (SSID KBU_PUBLIC)"| WF
    WF -->|"Detect captive portal / HTTP GET"| HC
    HC -->|"HTML Response"| TE
    TE -->|"Parsed Token"| LM
    LM -->|"POST credentials+token"| Web
    Web -->|"200 OK + cookies"| LM
    LM -->|"Verify Internet"| CC
    CC -->|"GET known site"| Int
    CC -->|"Success/Failure"| NT

    click README "https://github.com/cherryshine/project-wifi-autologin/blob/main/README.md"
    click WF "https://github.com/cherryshine/project-wifi-autologin/blob/main/init.lua"
    click HC "https://github.com/cherryshine/project-wifi-autologin/blob/main/init.lua"
    click TE "https://github.com/cherryshine/project-wifi-autologin/blob/main/init.lua"
    click LM "https://github.com/cherryshine/project-wifi-autologin/blob/main/init.lua"
    click CC "https://github.com/cherryshine/project-wifi-autologin/blob/main/init.lua"
    click NT "https://github.com/cherryshine/project-wifi-autologin/blob/main/init.lua"

    classDef host fill:#f9f,stroke:#333,stroke-width:1px
    classDef internal fill:#bbf,stroke:#333,stroke-width:1px
    classDef external fill:#ccc,stroke:#333,stroke-width:1px
    classDef doc fill:#afa,stroke:#333,stroke-width:1px

    linkStyle 8 stroke:#0a0,stroke-width:2px
```
