Dangerous Pi — Architecture & Dev Plan (Updated)
1. Overview

Dangerous Pi extends the existing pi-pm3
 project with:

Modern web UI (Remix optional, Python + SSE preferred for efficiency)

Single-user session management with web terminal fallback

Automatic application updates via GitHub Releases

Proxmark3 client rebuild on boot

UPS / safe power management

Wi-Fi / AP management (auto / captive portal / dual Wi-Fi detection)

Optional authentication

Backup plugin scaffolding

BLE notifications using built-in Pi Zero 2 W Bluetooth

Target hardware: Raspberry Pi Zero 2 W

2. Hardware Architecture
Component	Purpose	Notes
Pi Zero 2 W	Main controller	Runs backend & web UI; includes built-in Bluetooth 4.2 (BLE)
UPS HAT	Safe shutdown / battery monitoring	Expose battery % via I2C or API
PNP transistor	Programmatically “press” proxmark button	50–100ms pulse to emulate press
2x Slide switches	Hardware mode switches	One: On/Off → safe shutdown, Two: Wi-Fi → Auto/AP
Optional USB Wi-Fi dongle	Enables dual Wi-Fi mode	Detected dynamically; allows client + AP mode
Proxmark3	NFC/LF hardware	Interfaced via Python wrapper (client/proxmark3.py)
3. Backend Architecture
3.1 Stack

Language: Python 3.11+

Framework: FastAPI (async, SSE support)

Database: SQLite (for config, crash reports, session info)

Job Queue: Async queue for Proxmark commands + rebuild tasks

System services: Systemd units for:

Backend FastAPI server

Rebuild on boot / auto-update

UPS monitoring daemon

3.2 Components

API Layer

REST endpoints for:

Triggering proxmark commands

Changing Wi-Fi mode (auto/AP/client/dual)

Initiating backup

Updating auth config

SSE endpoints for:

Notifications (update available, backup complete, PM3 rebuild required)

Command completion messages

Proxmark Worker

Python async task runner

Uses client/proxmark3.py wrapper

Fire-and-wait commands (no live streaming)

Handles one active session at a time

Arbitrates web terminal vs web UI commands

Update Manager

Polls GitHub Releases API

Downloads latest release archive

Overwrites Dangerous Pi app code + rebuilds proxmark client

Restarts backend

SSE notifies user of:

Available update

Download progress

Rebuild pending restart

Option to restart immediately

Backup Plugin Scaffold

Default: periodic full application directory backup (config + logs + scripts)

Optional: full SD image backup

User notified via SSE & BLE

Plugin can optionally push backups to file storage service

Session Manager

Only one session allowed at a time

Force takeover option in web UI

Graceful disconnect handling (releases lock)

Optional session idle timeout (default: 5min) - releases PM3 lock after inactivity

BLE Manager

Uses built-in Pi Zero 2 W Bluetooth

Detects BLE functionality at runtime

Handles notifications for:

Updates available

Backups completed

PM3 rebuild pending

UPS low battery

Wi-Fi Detection

On boot, backend detects available network interfaces:

Built-in Wi-Fi → client / AP / auto mode

USB Wi-Fi → enables dual Wi-Fi (client + AP) mode

Web UI only exposes viable modes depending on detected hardware

4. Frontend Architecture
4.1 Stack

Framework: Remix (preferred) or minimal SPA

Transport:

SSE for server → client notifications

REST for client → server commands

Components:

Dashboard: status, UPS %, Wi-Fi mode, battery, logs, available updates

Scan: antenna placement overlay (SVG)

Clone: step-by-step wizard (MIFARE Classic, LF → T5577)

Terminal: xterm.js-based web terminal

Settings: auth, BLE pairing, backup options, SSL toggle

Wi-Fi Settings: dynamically show only available modes (auto, AP, client, client+AP if second module detected)

4.2 Design Patterns

SSR (server-side rendering) where possible to reduce Pi load

Islands/hydration only for dynamic components (terminal, wizards, notifications)

Minimal external JS libraries to keep bundles small

5. Networking / Wi-Fi
Mode	Description
AP (captive portal)	Forced by hardware switch; default IP: 10.3.141.1; simple portal page
Auto	UI chooses mode: client / dual (if second Wi-Fi detected) / BLE / client+BLE / off
Client + BLE	Only available if BLE dongle is present
Authentication	Optional; user can enable password in web UI

Optional HTTPS: self-signed certificate generated at first boot if enabled

6. UPS / Power Management

UPS daemon monitors battery, triggers safe shutdown

Web UI shows battery %, UPS health, charge status

Hardware On/Off switch triggers systemd shutdown sequence

Optional PNP transistor to safely trigger proxmark button

7. Update & Rebuild Flow

On boot:

Backend service starts

Update manager checks GitHub Releases

If new release available, download + overwrite app code

Rebuild proxmark3 client using native compiler

SSE notifies user: “PM client rebuild will occur on restart”

User can choose “restart now” or defer

On update failure:

Rollback to previous working directory (retain backups)

SSE alert to user

8. Backup & Recovery

Periodic: full application directory backup by default

Optional: full SD image backup

User notifications: web UI + BLE

Restore:

UI button triggers restoration from last backup

Optional plugin can extend cloud storage

Installer: full custom OS image preconfigured for appliance mode

9. OS / Installer Layout
/dangerous-pi/
├─ /boot/                 # Raspberry Pi boot partition
│   └─ config.txt
├─ /root/                 # OS root
│   ├─ /app/
│   │   ├─ backend/       # FastAPI + proxmark worker
│   │   ├─ frontend/      # Remix or SPA bundle
│   │   ├─ plugins/       # backup, optional future extensions
│   │   └─ scripts/       # PM3 rebuild, installer helpers
│   ├─ /data/
│   │   ├─ sqlite.db      # config, crash logs, session lock
│   │   └─ backups/
│   └─ /logs/             # application logs
├─ systemd/
│   ├─ dangerous-pi.service
│   └─ dangerous-pi-backup.service
└─ installer.sh           # Optional installer for existing Pi OS

10. Security

Local network only (LAN)

Optional password authentication

Optional HTTPS (self-signed cert)

Backend and worker run as non-root user

Crash/error reports opt-in

11. Development / Performance Notes

FastAPI async endpoints to minimize Pi Zero 2 W CPU load

SSR for static pages, dynamic islands for interactive features

SQLite chosen for small-footprint persistence

xterm.js terminal uses a single PTY; session management prevents concurrent conflicts

Minimal JS and CSS bundles to preserve performance

PM3 commands handled asynchronously, sequentially, single-threaded

BLE automatically enabled if built-in Bluetooth functional

Dual Wi-Fi UI dynamically reflects detected hardware

12. Optional Future Plugins

Cloud backup / restore

BLE remote control

Advanced telemetry

External API integration