4f35df1781
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
300 lines
6.7 KiB
Markdown
300 lines
6.7 KiB
Markdown
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
|