# jayofelony/pwnagotchi architecture

> Architecture diagram of the GitHub repository jayofelony/pwnagotchi, 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/jayofelony/pwnagotchi
- Repository: https://github.com/jayofelony/pwnagotchi

## Overview

##### Overall Project Type and Purpose
- Pwnagotchi is a specialized, embedded application meant to run on powered Raspberry Pi devices. It leverages tools like bettercap to sniff Wi-Fi and capture WPA handshake data – with the goal of efficiently gathering crackable key materials.
- Although earlier versions experimented with AI, the current design removes AI components for stability. The project’s extensibility relies on a rich plugin system and specialized hardware interfaces for displays, mesh networking, and more.
- The README also highlights partnerships (such as PiSugar) and connections to external tools (hashcat, bettercap), which reflects its integration in the Wi-Fi security ecosystem.

##### Main Architectural Components
a. Core System/Agent:
– The heart of the application lives in modules such as pwnagotchi/agent.py, automata.py, and cli.py.
– This “agent” is responsible for orchestrating the overall workflow – from data capture to interaction with plugins and UI outputs.
b. Wi-Fi Capture and Integration:
– Modules like pwnagotchi/bettercap.py, pwnagotchi/fs, and voice.py manage the interaction with the Wi-Fi environment and store captured PCAP files.
– These components connect to external tools (bettercap) and eventually provide data that could be processed (or passed onto hashcat externally).
c. Plugin Framework:
– The pwnagotchi/plugins directory contains many scripts (auto-update, grid, gps, etc.) that extend functionality.
d. Mesh Networking:
– pwnagotchi/mesh contains modules (peer.py, wifi.py, utils.py) which let multiple Pwnagotchi devices “talk” to each other, sharing statuses and other environmental details.
e. User Interfaces:
– There is a hardware UI residing in pwnagotchi/ui and its hw subdirectory with numerous drivers for different display hardware (e.g., miniPITFT, inky, dfrobot, etc.).
– A web-based UI is implemented under pwnagotchi/ui/web (complete with static assets, templates, and server/handler scripts) for remote viewing or configuration.
f. Localization and Voice:
– The pwnagotchi/locale directory (and the voice module) provides internationalization support for voice output, mapping language files to the application.
g. External Integrations:
– Integration points with Google (pwnagotchi/google) and identity management (pwnagotchi/identity) should also be represented.
– The defaults file (pwnagotchi/defaults.toml) in the root keeps configuration parameters.
h. Utilities and Logging:
– Common utilities, logging (pwnagotchi/log.py), and helper scripts (pwnagotchi/utils.py) provide supporting infrastructure for other modules.

##### Relationships and Data Flow
- The Core Agent passes relevant data (handshakes, state updates) to:
– The Plugin Subsystem (shown as a collection of extendable modules supporting tasks such as auto-tuning, GPS, backups, etc.).
– The Mesh Module for advertising and inter-device communication.
– The UI Modules (both hardware and web), which display current status and allow user interactions.
- Configuration and localization modules feed into the Core Agent to adjust behavior and communication (e.g., language selection for voice).
- Optional modules (like Google Drive sync in pwnagotchi/google) function as integration points that feed or receive information to/from the core logic.

##### Important Architectural Patterns and Design Choices
– Modular and extensible design: The clear separation of functionality into core, plugins, UI, and mesh layers.
– Hardware Abstraction: The varied support for displays and sensors under pwnagotchi/ui/hw is a sign of a hardware abstraction layer.
– Communication Patterns: The mesh networking and inter-device “talking” illustrate a distributed, peer-to-peer communication model.
– Separation of concerns: The agent orchestrates functions while auxiliary services (logging, file system handling, configuration) are factored out.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Incoming modules to Core Agent
    WIFI["Wi-Fi Capture"]:::wifi
    CONFIG["Configuration"]:::config
    LOCALE["Localization & Voice"]:::locale
    UTIL["Utilities & Logging"]:::utilities

    %% Central Core Agent
    CORE["Core Agent"]:::core

    %% Outgoing modules from Core Agent
    PLUGIN["Plugin Framework"]:::plugin
    MESH["Mesh Networking"]:::mesh
    HWUI["Hardware UI"]:::ui
    WEBUI["Web UI"]:::ui
    EXT["External Integrations"]:::external

    %% Data Flow - feeding into Core Agent
    WIFI -->|"feeds"| CORE
    CONFIG -->|"configures"| CORE
    LOCALE -->|"localizes"| CORE
    UTIL -->|"supports"| CORE

    %% Data Flow - Core Agent communicating to other modules
    CORE -->|"invokes"| PLUGIN
    CORE -->|"communicates"| MESH
    CORE -->|"updates"| HWUI
    CORE -->|"updates"| WEBUI
    CORE -->|"integrates"| EXT

    %% Click Events for Core System/Agent
    click CORE "https://github.com/jayofelony/pwnagotchi/blob/noai/pwnagotchi/agent.py"
    click CORE "https://github.com/jayofelony/pwnagotchi/blob/noai/pwnagotchi/automata.py"
    click CORE "https://github.com/jayofelony/pwnagotchi/blob/noai/pwnagotchi/cli.py"

    %% Click Events for Wi‑Fi Capture and Integration
    click WIFI "https://github.com/jayofelony/pwnagotchi/blob/noai/pwnagotchi/bettercap.py"
    click WIFI "https://github.com/jayofelony/pwnagotchi/tree/noai/pwnagotchi/fs"

    %% Click Event for Plugin Framework
    click PLUGIN "https://github.com/jayofelony/pwnagotchi/tree/noai/pwnagotchi/plugins"

    %% Click Event for Mesh Networking
    click MESH "https://github.com/jayofelony/pwnagotchi/tree/noai/pwnagotchi/mesh"

    %% Click Events for User Interfaces
    click HWUI "https://github.com/jayofelony/pwnagotchi/tree/noai/pwnagotchi/ui"
    click WEBUI "https://github.com/jayofelony/pwnagotchi/tree/noai/pwnagotchi/ui/web"

    %% Click Events for Localization and Voice
    click LOCALE "https://github.com/jayofelony/pwnagotchi/tree/noai/pwnagotchi/locale"
    click LOCALE "https://github.com/jayofelony/pwnagotchi/blob/noai/pwnagotchi/voice.py"

    %% Click Events for External Integrations
    click EXT "https://github.com/jayofelony/pwnagotchi/tree/noai/pwnagotchi/google"
    click EXT "https://github.com/jayofelony/pwnagotchi/blob/noai/pwnagotchi/identity.py"

    %% Click Events for Utilities and Logging
    click UTIL "https://github.com/jayofelony/pwnagotchi/blob/noai/pwnagotchi/log.py"
    click UTIL "https://github.com/jayofelony/pwnagotchi/blob/noai/pwnagotchi/utils.py"

    %% Click Event for Configuration Module
    click CONFIG "https://github.com/jayofelony/pwnagotchi/blob/noai/pwnagotchi/defaults.toml"

    %% Styles
    classDef core fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef wifi fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef config fill:#ffffcc,stroke:#cccc00,stroke-width:2px;
    classDef locale fill:#cceeff,stroke:#0066cc,stroke-width:2px;
    classDef utilities fill:#f0f0f0,stroke:#999999,stroke-width:2px;
    classDef plugin fill:#fff0f5,stroke:#ff69b4,stroke-width:2px;
    classDef mesh fill:#e6e6fa,stroke:#8a2be2,stroke-width:2px;
    classDef ui fill:#d0f0fd,stroke:#007acc,stroke-width:2px;
    classDef external fill:#fdf5e6,stroke:#deb887,stroke-width:2px;
```
