# evilsocket/pwnagotchi architecture

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

- Interactive diagram: https://gitdiagram.com/evilsocket/pwnagotchi
- Repository: https://github.com/evilsocket/pwnagotchi

## Overview

##### Main Components
- AI/Agent & Learning Core
– Located under the “pwnagotchi/ai” directory with modules such as epoch.py, featurizer.py, train.py, etc.
– Contains the policy network implementation (using an LSTM-MLP architecture) and adapts key parameters over time.
- Core Engine & Orchestration
– Modules like agent.py, automata.py, and grid.py coordinate the operation of the tool.
– The main “pwnagotchi” package encapsulates configuration (defaults.toml), logging (log.py), and identity handling.
- Plugins
– Found in “pwnagotchi/plugins”, these extend or modify core functionality (for example, web configuration, system monitoring, auto-update, etc.).
- Hardware/Display Integration
– Located in “pwnagotchi/ui/hw” and associated “libs” directories for various hardware types (Adafruit, DFRobot, Waveshare, etc).
– This layer supports the various display configurations and peripheral controls.
- Web and UI Interface
– Under “pwnagotchi/ui” there are components for display and a web interface (e.g., “web/server.py”, “web/templates”).
– This includes both portable UI hardware as well as a browser-based "status" or configuration panel.
- Mesh Networking
– Found under “pwnagotchi/mesh”, handling peer discovery and communication between multiple units.
- Build/Deployment & Scripts
– The “builder” folder contains configuration files, systemd service definitions, and network settings.
– The “scripts” and “bin” folders manage deployment and auxiliary operations (e.g., backups, connection shares).

##### Relationships and Interactions
- The AI/Agent module interacts with:
– The learning infrastructure (e.g., training routines, parameter adjustments) to tune its “pwning” algorithm.
– The mesh/networking modules to share information with nearby units.
– The plugins to add or override behaviors.
- The Core Engine calls on the hardware layer to display status information and control the interface – for example, sending output to LCDs or OLED displays.
- The Web UI module integrates with the core engine to provide remote status viewing and configuration, utilizing its built-in web server and static assets.
- The builder and system configuration files ensure that on startup (via systemd services defined in the builder/data/etc/systemd), the tool initializes with the correct network, hardware, and AI configurations.

##### Architectural Patterns and Design Principles
- Modular design: The project is organized into separate logical areas (agent, AI, plugins, UI, networking) so that components can be developed, tested, and maintained nearly independently.
- Plugin architecture: The plugins directory signifies an extensibility point, allowing additional functionality to be integrated without changing the core system.
- Separation of Concerns: There is a distinct split between learning logic (AI), hardware integration (UI/hw and supporting libs), and I/O/communication (mesh and web modules).
- Use of configuration and initialization files (e.g., defaults.toml, pwnagotchi.yml) to abstract runtime parameters from code.

##### Relevant Technologies, Frameworks, and External Tools
- Reinforcement Learning and AI: Uses an A2C-based agent with an LSTM and MLP policy network.
- Networking: Integrates with bettercap for WiFi interactions and likely uses standard Linux networking for interface modification (see builder/data/etc/network).
- System Deployment: Contains Makefile, setup.py, and systemd unit files to facilitate installation and service management.
- Hardware libraries: Supports various peripheral hardware via interfacing libraries, many of which are included in the “ui/hw/libs” directory.
- Web technologies: HTML templates, CSS, and JavaScript for status and remote management interfaces.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Build/Deployment & Scripts"]:::deployment
    E["Core Engine & Orchestration"]:::engine
    AIA["AI/Agent & Learning Core"]:::ai
    P["Plugins"]:::plugins
    M["Mesh Networking"]:::mesh
    H["Hardware/Display Integration"]:::hardware
    W["Web and UI Interface"]:::web

    %% Flow connections
    A -->|"initializes"| E
    E -->|"runs"| AIA
    E -->|"controls"| H
    AIA -->|"extendedBy"| P
    P -->|"communicatesWith"| M
    H -->|"providesStatusTo"| W
    E -->|"feedsConfigTo"| W
    AIA -->|"sendsOutputTo"| H

    %% Click Events
    click A "https://github.com/evilsocket/pwnagotchi/tree/master/builder"
    click A "https://github.com/evilsocket/pwnagotchi/tree/master/scripts"
    click E "https://github.com/evilsocket/pwnagotchi/blob/master/pwnagotchi/automata.py"
    click E "https://github.com/evilsocket/pwnagotchi/blob/master/pwnagotchi/grid.py"
    click E "https://github.com/evilsocket/pwnagotchi/blob/master/pwnagotchi/log.py"
    click E "https://github.com/evilsocket/pwnagotchi/blob/master/pwnagotchi/identity.py"
    click E "https://github.com/evilsocket/pwnagotchi/blob/master/pwnagotchi/defaults.toml"
    click AIA "https://github.com/evilsocket/pwnagotchi/tree/master/pwnagotchi/ai"
    click AIA "https://github.com/evilsocket/pwnagotchi/blob/master/pwnagotchi/agent.py"
    click P "https://github.com/evilsocket/pwnagotchi/tree/master/pwnagotchi/plugins"
    click H "https://github.com/evilsocket/pwnagotchi/tree/master/pwnagotchi/ui/hw"
    click H "https://github.com/evilsocket/pwnagotchi/tree/master/pwnagotchi/ui/hw/libs"
    click W "https://github.com/evilsocket/pwnagotchi/tree/master/pwnagotchi/ui/web"
    click M "https://github.com/evilsocket/pwnagotchi/tree/master/pwnagotchi/mesh"

    %% Styles
    classDef deployment fill:#cccccc,stroke:#000000,stroke-width:2px;
    classDef engine fill:#caffbf,stroke:#000000,stroke-width:2px;
    classDef ai fill:#9bf6ff,stroke:#000000,stroke-width:2px;
    classDef plugins fill:#ffadad,stroke:#000000,stroke-width:2px;
    classDef mesh fill:#ffd6a5,stroke:#000000,stroke-width:2px;
    classDef hardware fill:#fdffb6,stroke:#000000,stroke-width:2px;
    classDef web fill:#d0f4de,stroke:#000000,stroke-width:2px;
```
