pi-pm3/PROJECT_STATUS.md

Dangerous Pi - Project Status

Last Updated: 2026-03-03

✅ Phase 3 Complete - Hardware Testing Passed

All MVP features tested on actual hardware:

• Raspberry Pi Zero 2 W with Proxmark3 Easy
• PiSugar 2 UPS (auto-detected via I2C)
• Bluetooth LE advertising working
• WiFi AP mode active (192.168.4.1)

---

📊 Feature Evaluation Summary (2026-03-03)

Feature	Completion	Backend	Frontend	Notes
HTTPS	✅ 100%	✅ Complete	✅ Toggle + info	Done 2026-03-03
Authentication	40%	✅ Basic + WS tokens	✅ Login prompt	WebSocket protected
Plugin System	85%	✅ Complete + hooks wired	✅ Complete	Remote install missing

🔐 Security Gaps (Remaining)

1. Single User Only: Basic HTTP auth with hardcoded username, no multi-user support
2. No Logout: Active sessions cannot be revoked
3. No JWT: Still using Basic Auth for REST endpoints (tokens only for WS)

✅ HTTPS (100% Complete - Done 2026-03-03)

Implemented:

• SSL API endpoints fully working (/api/system/ssl/info, /api/system/ssl/regenerate)
• Certificate generation script with EC P-256 keys, 10-year validity (scripts/generate-ssl-cert.sh)
• nginx HTTPS config with TLS 1.2/1.3, HSTS, modern ciphers (nginx/dangerous-pi-https.conf)
• Captive portal detection for Android, iOS, Windows, macOS, Firefox, Kindle
• Systemd services for auto-generation (dangerous-pi-ssl-gen.service)
• nginx config switching script (scripts/configure-nginx.sh)
• Pi-gen integration (stage 05-https-support)
• Frontend displays HTTPS status badge in Settings
• Subject Alternative Names: 192.168.4.1, dangerous-pi.local, localhost
• ✅ Frontend Enable/Disable toggle (POST /api/system/ssl/toggle)
• ✅ Certificate regeneration button in UI
• ✅ SSL info display (expiration, SANs, SHA256 fingerprint)

🔑 Authentication (40% Complete)

Implemented:

• Basic HTTP authentication (app/backend/api/auth.py)
• AUTH_ENABLED environment variable toggle (default: false)
• Single username/password via env vars
• Conditional router protection when enabled
• ✅ WebSocket token-based auth (app/backend/api/token_store.py) - Done 2026-03-03
• ✅ POST /api/auth/token - exchange Basic Auth for WS token (24h TTL)
• ✅ GET /api/auth/status - public endpoint for auth status check
• ✅ WebSocket validates token query param, rejects with close code 4401
• ✅ Frontend LoginPrompt modal (app/frontend/app/components/LoginPrompt.tsx)
• ✅ WebSocket manager handles auth flow (token fetch, retry, auth_required state)

Missing:

• JWT token-based auth for REST endpoints
• Multi-user support
• User management
• Role-based access control (RBAC)
• Logout functionality
• Session revocation

Estimated to Complete: ~2-3 weeks (full system, JWT + multi-user + RBAC)

🔌 Plugin System (85% Complete)

Implemented:

• Plugin Manager: 804 lines, full lifecycle (load/enable/disable/unload)
• Hook system: register_hook() and trigger_hook() methods implemented
• Header widget system: severity levels (INFO/WARNING/ERROR/SUCCESS), dismissible, actions, expiration
• Hardware access layer: GPIO, I2C, SPI, Serial with permission enforcement
• 7 API endpoints: discover, list, info, enable, disable, load, unload
• Frontend UI: discovery button, plugin listing, enable/disable toggles, permission badges
• Hello World example plugin with registered hooks
• WebSocket broadcasting capability for plugins (requires websocket permission)
• ✅ Hook triggers wired in PM3 service (pm3_command hook) - Done 2026-03-03
• ✅ Hook triggers wired in Update manager (update_check hook) - Done 2026-03-03

Missing:

• Remote plugin installation (from GitHub releases)
• pip dependency management
• Permission consent dialog before enabling

Estimated to Complete:

• Remote installation: ~1-2 weeks

---

✅ Completed Features

Backend (Python + FastAPI)

Core Infrastructure:

• ✅ FastAPI application with async support
• ✅ SQLite database (sessions, config, command history, crash reports)
• ✅ Configuration management via environment variables
• ✅ Comprehensive error handling

API Endpoints:

• ✅ Health check (/api/health)
• ✅ System info (/api/system/info)
• ✅ PM3 status (/api/pm3/status)
• ✅ PM3 command execution (/api/pm3/command)
• ✅ PM3 device management (/api/pm3/devices/*)
• ✅ Session management (/api/system/session/*)
• ✅ WebSocket events (/ws/events)

Core Components:

• ✅ PM3 Worker - Uses built-in pm3 Python module (SWIG bindings)
• ✅ PM3 Device Manager - Multi-device support with unique device IDs
• ✅ Session Manager - Per-device sessions with takeover support
• ✅ WebSocket Manager - Real-time event broadcasting to all clients
• ✅ Service Container - Dependency injection for services

WiFi Manager (Complete):

• ✅ Interface detection (USB vs built-in)
• ✅ Network scanning with signal strength
• ✅ Full mode switching (AP/Client/Dual/Auto/Off)
• ✅ Network connection with password support
• ✅ Hidden SSID support
• ✅ Saved networks management
• ✅ Static IP configuration
• ✅ DHCP management
• ✅ 10 WiFi API endpoints

Update Manager (Complete):

• ✅ GitHub releases API integration
• ✅ Automatic periodic update checks
• ✅ Version comparison (semantic versioning)
• ✅ Update download with progress tracking
• ✅ Checksum verification (SHA256)
• ✅ Automatic installation with backup
• ✅ PM3 client rebuild after updates
• ✅ Rollback on installation failure
• ✅ 6 Update API endpoints

UPS Manager (Complete):

• ✅ I2C battery monitoring (MAX17040-compatible)
• ✅ Battery percentage, voltage, current tracking
• ✅ Power source detection (AC/Battery)
• ✅ Safe shutdown triggers at configurable thresholds
• ✅ Battery status (Charging, Discharging, Full, Critical)
• ✅ Event callbacks for battery warnings
• ✅ WebSocket and BLE notification integration
• ✅ 3 UPS API endpoints
• ✅ Power Management Policy (NEW - 2025-11-26)
  • Assumes AC power when UPS not detected (no restrictions)
  • Battery-level restrictions when on UPS battery
  • Power restrictions API endpoint for firmware flashing
  • Safe defaults: all operations allowed without UPS

BLE Manager (Complete - MVP):

• ✅ Bluetooth Low Energy notification support
• ✅ Auto-detects BLE capability
• ✅ Configurable device name
• ✅ Multiple notification types (updates, battery, shutdown, etc.)
• ✅ BLE advertising management
• ✅ Device connection tracking
• ✅ Notification queueing
• ✅ 4 BLE API endpoints
• 🚧 Planned Enhancement: Full web client feature parity via BLE
  • Command execution via BLE
  • Status queries via BLE
  • Guided workflow triggers via BLE
  • For React Native mobile app integration

Plugin Framework (85% Complete - See Feature Evaluation):

• ✅ Dynamic plugin loading/unloading (804-line plugin manager)
• ✅ Plugin lifecycle management (load, enable, disable, unload)
• ✅ Hook system: register_hook() and trigger_hook() fully implemented
• ✅ Hook triggers wired in PM3 service and Update manager
• ✅ Header widget system with severity levels, actions, expiration
• ✅ Hardware access layer: GPIO, I2C, SPI, Serial with permission checks
• ✅ JSON-based metadata with permissions and dependencies
• ✅ Plugin discovery from directory
• ✅ Enable/disable individual plugins
• ✅ Example "Hello World" plugin with registered hooks
• ✅ 7 Plugin API endpoints (discover, list, info, enable, disable, load, unload)
• ✅ Frontend UI with discovery, listing, toggle controls, permission badges
• ❌ Remote plugin installation not implemented
• ❌ pip dependency management not implemented

Proxmark3 Firmware Enhancements (Complete - 2025-12-02):

• ✅ Two-channel hardware PWM LED brightness control
  • LED A (Green, PA0/PWM0): 0-100% brightness
  • LED B (Blue, PA2/PWM2): 0-100% brightness
  • LED C/D: Basic on/off/toggle
• ✅ New hw led command with full LED control
• ✅ PWM channel reallocation (timing moved PWM0→PWM1)
• ✅ Backward compatible protocol (CMD_LED_CONTROL 0x011A)
• ✅ Multi-device identification via brightness levels
• ✅ Zero performance impact on RF operations
• ✅ Tested and flashed to Proxmark3 Easy
• 📄 Documentation: LED_PWM_IMPLEMENTATION.md

System Integration (Complete):

• ✅ Systemd service units with security hardening
• ✅ Automated install/uninstall scripts
• ✅ Environment configuration template
• ✅ Hardware access groups (i2c, bluetooth, gpio, dialout)
• ✅ Pi-gen stage integration for OS image building
• ✅ Port conflict resolution with ttyd-bash
• ✅ I2C interface auto-enable for UPS HAT

Testing:

• ✅ Component tests (test_backend.py)
• ✅ UPS manager test (test_ups.py)
• ✅ BLE manager test (test_ble.py)
• ✅ Plugin manager test (test_plugins.py)
• ✅ All tests passing

Frontend (Remix.js + React)

Design System:

• ✅ Cyberpunk theme (Dangerous Things aesthetic)
• ✅ Dark mode default, light mode available
• ✅ Auto theme detection (system preference)
• ✅ Lightweight CSS (~15KB)
• ✅ System fonts only (zero download)
• ✅ Mobile-first responsive design

Pages:

• ✅ Dashboard (/)

  • System status (CPU, memory, disk)
  • PM3 connection status with multi-device support
  • Quick actions
  • Real-time WebSocket notifications

• ✅ Commands (/commands)

  • Command input with history (↑/↓ navigation)
  • Quick command buttons
  • Terminal-style output
  • Session management

• ✅ Settings (/settings)

  • General settings (auth, HTTPS)
  • Wi-Fi configuration (full UI with scanning, mode switching)
  • Update management
  • Advanced options
  • System actions (restart, shutdown)

• ✅ Logs (/logs)

  • Command history table
  • Success/failure status
  • Timestamp formatting

Components:

• ✅ Responsive navigation (mobile bottom bar, desktop top)
• ✅ Theme toggle button
• ✅ Status badges with pulse animation
• ✅ Toast notifications
• ✅ Loading states
• ✅ Form validation
• ✅ DeviceSelector - Multi-PM3 device selection with LED identification
• ✅ PowerWidget - Real-time UPS/battery status in header
• ✅ ConnectDialog - PM3 connection management
• ✅ QRScanner - HTML5-based QR code scanning
• ✅ LoginPrompt - Modal login form for WebSocket auth

Hooks:

• ✅ useWebSocket - Singleton WebSocket manager with event subscriptions and token auth

Performance:

• ✅ Server-side rendering (SSR)
• ✅ Code splitting by route
• ✅ Progressive enhancement
• ✅ Bundle size < 150KB (target - with room for Victory charts)

Visualization (Planned):

• 📋 Victory Charts - Cross-platform charting library
  • Mobile-first design with touch gestures
  • Shared components across Web/Mobile/Desktop
  • Real-time data visualization
  • ~50KB bundle impact (within budget via code splitting)
• 📋 Guided Workflows - Multi-step wizards for common tasks
  • ID Transponder
  • Clone MIFARE Classic 1K
  • Clone to T5577
  • HF/LF/HW Tune with live charts
  • Sniffing utility

Documentation

• ✅ claude.md - AI development guide (updated with Victory)
• ✅ README_DEV.md - Developer quick start
• ✅ UI_GUIDELINES.md - Design system and UX principles (mobile-first)
• ✅ GETTING_STARTED.md - Complete setup guide
• ✅ WIFI_MANAGER.md - WiFi management guide
• ✅ UPDATE_MANAGER.md - Update system guide
• ✅ PORT_CONFLICT.md - Port conflict resolution guide
• ✅ MVP_COMPLETE.md - MVP completion summary
• ✅ BUILD_GUIDE.md - Pi-gen image building guide
• ✅ QUICK_BUILD.md - Quick build reference
• ✅ VISUALIZATION_PLAN.md - Charting and guided workflows plan
• ✅ systemd/README.md - Service management documentation
• ✅ pi-gen/stageDTPM3/04-dangerous-pi/README.md - Build integration docs
• ✅ app/frontend/README.md - Frontend documentation
• ✅ README.md - Updated main readme

---

🚧 Future Enhancements (Post-MVP)

High Priority (Next Phase)

1. Data Visualization & Guided Workflows 🎯 IN PLANNING

   • Victory charts integration (~50KB bundle)
   • PM3 output parser layer (text → structured JSON)
   • Real-time tuning visualizations (HF/LF/HW tune)
   • Guided workflow framework (multi-step wizards)
   • Touch-optimized interactive charts
   • Mobile-first UI components
   • Target: 4-6 weeks implementation
   • Dependencies: Victory, PM3 output parsers

2. Cross-Platform Apps 🎯 PLANNED

   • React Native Mobile App (iOS/Android)
     • Shared Victory chart components with web
     • Full BLE integration for offline operation
     • Native performance and UX
     • Share ~90% codebase with web app
   • Electron Desktop App (Windows/Mac/Linux)
     • Same codebase as web + React Native
     • Native system integration
     • Offline-first capabilities
   • Target: Post-visualization implementation

3. Enhanced BLE Manager 🎯 PLANNED

   • Full web client feature parity via BLE
   • Command execution over BLE (for mobile app)
   • Bidirectional communication (GATT server)
   • Status queries and responses
   • Guided workflow triggers
   • Notification improvements
   • Target: Concurrent with React Native app

4. Frontend Build Integration

   • Serve frontend from backend in production
   • Build script for combined deployment
   • Asset optimization
   • Service worker for offline support

5. Backup System

   • Application directory backup
   • Optional SD card image backup
   • Scheduled backups
   • Restore functionality
   • Cloud storage plugin (optional)

Medium Priority

6. Authentication (40% Complete - See Feature Evaluation)

   • ✅ Basic HTTP auth (backend)
   • ✅ WebSocket token auth with LoginPrompt
   • ❌ JWT tokens needed for REST
   • ❌ Multi-user support needed
   • ❌ RBAC needed

7. HTTPS Support ✅ COMPLETE

   • ✅ Self-signed certificate generation
   • ✅ Automatic cert creation on first boot
   • ✅ Frontend toggle and cert info display

8. Advanced PM3 Features

   • Waveform viewer with pan/zoom
   • Protocol trace analyzer
   • Antenna tuning dashboard
   • Command templates
   • Favorite commands

Low Priority

6. Plugin Ecosystem

   • Plugin marketplace/appstore
   • Plugin signing and verification
   • Plugin dependency resolution
   • Community plugin repository

7. Enhanced BLE

   • Full GATT server implementation
   • Bi-directional communication
   • Mobile app integration

8. Additional UPS Support

   • Temperature monitoring
   • Battery health reporting

---

📊 Project Metrics

Backend

• Lines of Code: ~7,000+
• Files: 40+
• API Endpoints: 54+ (PM3 10+, System 18+, WiFi 10, Updates 6, Plugins 7, Auth 3)
• Managers: 7 (PM3Device, Session, WiFi, Update, UPS, BLE, Plugin)
• Services: 4 (PM3, System, WiFi, Update) + ServiceContainer
• Dependencies: 11 packages
• Test Coverage: All managers tested

Frontend

• Lines of Code: ~2,500+
• Files: 13+
• Pages: 5 (Dashboard, Commands, Settings, Logs, Updates)
• Components: 5 (DeviceSelector, PowerWidget, ConnectDialog, QRScanner, LoginPrompt)
• Hooks: 1 (useWebSocket)
• CSS: 15KB (uncompressed)
• Bundle Size: ~120KB (estimated, gzipped)

System Integration

• Systemd Services: 1
• Installation Scripts: 2 (install, uninstall)
• Port Resolution Scripts: 1
• Pi-gen Stages: 1 (with 3 scripts)

Documentation

• Guides: 12 files
• Total Documentation: ~10,000+ lines
• API Documentation: Auto-generated (FastAPI)

---

🎯 Next Steps

Immediate

1. ✅ Power Management Policy (COMPLETE - 2025-11-26)

   • Power restrictions API implemented
   • UPS-aware power management
   • Safe defaults for systems without UPS
   • Ready for hardware deployment

2. Hardware Testing (NEXT - Blocked until pi-gen build complete)

   • Test on actual Raspberry Pi Zero 2 W
   • Test with real UPS HAT (optional hardware)
   • Test BLE notifications with mobile device
   • Performance optimization for Pi hardware

3. Pi-gen Build Testing (READY)

   • Run ./build-image.sh quick to test PM3 client build
   • Verify Python bindings compilation
   • Test full image build
   • Deploy to Pi hardware

4. Frontend Build Integration

   • Create production build script
   • Serve frontend from backend
   • Single-server deployment

5. OS Image Creation

   • Build custom image with pi-gen
   • Test image on Pi Zero 2 W
   • Verify all services start correctly
   • Document installation process

Short Term

1. Additional Example Plugins

   • Create 2-3 more example plugins
   • Document plugin development
   • Plugin best practices guide

2. Frontend Enhancements

   • Add UPS status to dashboard
   • Add BLE status indicator
   • Add plugin management UI
   • Update management UI improvements

3. Testing & QA

   • Integration testing on hardware
   • Load testing
   • Security review
   • Documentation review

Medium Term

1. Backup System

   • Implement backup functionality
   • Schedule backups
   • Cloud storage plugins

2. Advanced Features

   • Authentication system
   • HTTPS support
   • Advanced PM3 wizards
   • Command templates

Long Term

1. Plugin Ecosystem

   • Plugin marketplace/appstore
   • Community plugins
   • Plugin repository

2. Public Release

   • Beta testing program
   • User documentation
   • Release to community

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                    Browser (User)                        │
└───────────────────────┬─────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        │               │               │
    REST API       WebSocket       Static Assets
        │               │               │
┌───────▼───────────────▼───────────────▼─────────────────┐
│              Remix.js Frontend (React)                   │
│                                                          │
│  • Dashboard     • Commands     • Settings     • Logs   │
│  • Cyberpunk Theme     • Mobile-First     • SSR         │
│  • useWebSocket hook   • DeviceSelector   • PowerWidget │
└───────────────────────┬─────────────────────────────────┘
                        │
                    Proxy to
                        │
┌───────────────────────▼─────────────────────────────────┐
│              FastAPI Backend (Python)                    │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  API Layer   │  │  WebSocket   │  │   Services   │  │
│  │              │  │              │  │              │  │
│  │ • Health     │  │ • PM3 Status │  │ • PM3Service │  │
│  │ • System     │  │ • Devices    │  │ • System     │  │
│  │ • PM3        │  │ • UPS/Battery│  │ • WiFi       │  │
│  │ • WiFi       │  │ • Updates    │  │ • Update     │  │
│  │ • Updates    │  │              │  │              │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  Managers    │  │   Workers    │  │   Database   │  │
│  │              │  │              │  │              │  │
│  │ • PM3Device  │  │ • PM3 Worker │  │   SQLite     │  │
│  │ • Session    │  │   (SWIG)     │  │              │  │
│  │ • WiFi       │  │              │  │ • Sessions   │  │
│  │ • Updates    │  └──────────────┘  │ • Config     │  │
│  │ • UPS        │                    │ • History    │  │
│  │ • BLE        │  ServiceContainer  │ • Crashes    │  │
│  │ • Plugin     │  (DI)              │              │  │
│  └──────────────┘                    └──────────────┘  │
└─────────────────────────────────────────────────────────┘
                        │
              pm3 Python module (SWIG)
                        │
┌───────────────────────▼─────────────────────────────────┐
│              Proxmark3 Hardware (Multi-device)           │
│         /dev/ttyACM0, /dev/ttyACM1, ...                  │
└─────────────────────────────────────────────────────────┘

---

🛠️ Technology Stack

Backend

• Language: Python 3.11+
• Framework: FastAPI
• Database: SQLite (aiosqlite)
• Server: Uvicorn
• PM3 Integration: Official Python bindings (SWIG)

Frontend

• Framework: Remix v2 (React Router)
• Language: TypeScript
• Build: Vite
• Styling: Vanilla CSS (no framework)
• Transport: Fetch API + WebSocket

Infrastructure

• OS: Raspberry Pi OS (Debian Trixie)
• Hardware: Raspberry Pi Zero 2 W
• Networking: RaspAP (existing)
• Services: Systemd (planned)

---

📁 File Structure

dangerous-pi/
├── app/
│   ├── backend/                    # FastAPI backend
│   │   ├── api/                    # REST endpoints
│   │   │   ├── health.py           # Health checks
│   │   │   ├── pm3.py              # PM3 commands + devices
│   │   │   ├── system.py           # System + UPS + BLE + CPU
│   │   │   ├── wifi.py             # WiFi management
│   │   │   ├── updates.py          # Update management
│   │   │   ├── plugins.py          # Plugin management
│   │   │   ├── auth.py             # Authentication + token endpoints
│   │   │   └── token_store.py      # In-memory WS auth tokens
│   │   ├── websocket/              # WebSocket real-time events
│   │   │   ├── manager.py          # Connection manager
│   │   │   ├── routes.py           # WebSocket endpoint
│   │   │   └── notifications.py    # Event broadcasting helpers
│   │   ├── services/               # Business logic layer
│   │   │   ├── container.py        # Dependency injection
│   │   │   ├── pm3_service.py      # PM3 operations
│   │   │   ├── system_service.py   # System operations
│   │   │   ├── wifi_service.py     # WiFi operations
│   │   │   └── update_service.py   # Update operations
│   │   ├── workers/                # Background workers
│   │   │   └── pm3_worker.py       # PM3 command executor (SWIG)
│   │   ├── managers/               # State management
│   │   │   ├── pm3_device_manager.py # Multi-device PM3 management
│   │   │   ├── session_manager.py  # Per-device sessions
│   │   │   ├── wifi_manager.py     # WiFi management
│   │   │   ├── update_manager.py   # Update system
│   │   │   ├── ups_manager.py      # UPS monitoring
│   │   │   ├── ups_drivers/        # UPS driver implementations
│   │   │   │   ├── base.py         # Abstract base driver
│   │   │   │   ├── i2c_driver.py   # Generic I2C fuel gauge
│   │   │   │   ├── pisugar_driver.py     # PiSugar TCP driver
│   │   │   │   └── pisugar_i2c_driver.py # PiSugar I2C driver
│   │   │   ├── ble_manager.py      # BLE notifications
│   │   │   └── plugin_manager.py   # Plugin framework
│   │   ├── ble/                    # BLE GATT implementation
│   │   │   ├── gatt_server.py      # GATT server
│   │   │   ├── characteristics.py  # GATT characteristics
│   │   │   └── bluez_adapter.py    # BlueZ D-Bus adapter
│   │   ├── models/                 # Database models
│   │   │   └── database.py         # SQLite schema
│   │   ├── config.py               # Configuration
│   │   └── main.py                 # FastAPI app
│   ├── frontend/                   # Remix.js frontend
│   │   ├── app/
│   │   │   ├── routes/             # Page routes
│   │   │   │   ├── _index.tsx      # Dashboard
│   │   │   │   ├── commands.tsx    # Command interface
│   │   │   │   ├── settings.tsx    # Settings + WiFi + Updates
│   │   │   │   ├── updates.tsx     # Update management
│   │   │   │   └── logs.tsx        # Command logs
│   │   │   ├── components/         # React components
│   │   │   │   ├── DeviceSelector.tsx  # Multi-device selection
│   │   │   │   ├── PowerWidget.tsx     # UPS/battery status
│   │   │   │   ├── ConnectDialog.tsx   # Connection management
│   │   │   │   ├── QRScanner.tsx       # QR code scanning
│   │   │   │   └── LoginPrompt.tsx     # WS auth login modal
│   │   │   ├── hooks/              # Custom React hooks
│   │   │   │   └── useWebSocket.ts # WebSocket singleton manager
│   │   │   ├── root.tsx            # Root layout
│   │   │   ├── styles.css          # Cyberpunk theme
│   │   │   ├── entry.client.tsx    # Client entry
│   │   │   └── entry.server.tsx    # Server entry
│   │   ├── vite.config.ts          # Vite configuration
│   │   ├── tsconfig.json           # TypeScript config
│   │   └── package.json            # Dependencies
│   └── plugins/                    # Plugin directory
│       └── hello_world/            # Example plugin
│           ├── plugin.json         # Plugin metadata
│           └── main.py             # Plugin implementation
├── systemd/                        # Service configuration
│   ├── dangerous-pi.service        # Systemd unit file
│   ├── dangerous-pi.env.example    # Environment template
│   ├── install-service.sh          # Installation script
│   ├── uninstall-service.sh        # Uninstallation script
│   └── README.md                   # Service documentation
├── scripts/                        # Helper scripts
│   └── resolve-port-conflict.sh    # Port conflict resolution
├── pi-gen/                         # OS image builder
│   └── stageDTPM3/                 # Custom stage
│       └── 04-dangerous-pi/        # Dangerous Pi stage
│           ├── 00-run.sh           # Pre-chroot prep
│           ├── 00-run-chroot.sh    # Installation
│           ├── 01-run-chroot.sh    # Port conflict handling
│           └── README.md           # Build documentation
├── data/                           # Runtime data
│   └── dangerous_pi.db             # SQLite database
├── logs/                           # Application logs
├── requirements.txt                # Python dependencies
├── test_backend.py                 # Backend tests
├── test_ups.py                     # UPS manager tests
├── test_ble.py                     # BLE manager tests
├── test_plugins.py                 # Plugin manager tests
├── .env.example                    # Environment template
├── .gitignore                      # Git ignore rules
├── claude.md                       # AI dev guide
├── UI_GUIDELINES.md                # Design system
├── WIFI_MANAGER.md                 # WiFi guide
├── UPDATE_MANAGER.md               # Update guide
├── PORT_CONFLICT.md                # Port conflict guide
├── MVP_COMPLETE.md                 # MVP summary
├── README.md                       # Main readme
├── README_DEV.md                   # Dev quick start
├── GETTING_STARTED.md              # Setup guide
└── PROJECT_STATUS.md               # This file

---

🎨 Design Highlights

Cyberpunk Aesthetic

• Primary: Cyan (#00ffff) - Neon glow effect
• Secondary: Magenta (#ff00ff)
• Accent: Green (#00ff88)
• Background: Dark blue (#0a0e1a)
• Monospace: Terminal feel for code blocks

Performance Optimizations

• Server-side rendering (fast First Contentful Paint)
• System fonts only (zero web font download)
• Minimal CSS (15KB, no framework)
• Code splitting by route
• CSS-only animations

Accessibility

• WCAG 2.1 AA compliant
• Keyboard navigation
• 44x44px touch targets
• High contrast colors
• ARIA labels

---

🚀 Deployment Path

Development (Current)

Backend: python -m app.backend.main
Frontend: npm run dev (separate server)

Production (Planned)

1. Build frontend: npm run build
2. Backend serves static files from build/
3. Single server on port 8000
4. Systemd service for auto-start
5. Integrated into pi-gen image

---

📈 Performance Targets

Backend

• Response time: < 100ms (health checks)
• Command execution: < 1s (most PM3 commands)
• WebSocket latency: < 50ms (event delivery)
• Memory usage: < 100MB

Frontend

• First Contentful Paint: < 1.5s ✅
• Time to Interactive: < 3s ✅
• Bundle size: < 150KB gzipped ✅
• Lighthouse score: > 90 (all categories)

---

🎓 Learning Resources

For contributors and maintainers:

• Backend: README_DEV.md
• Frontend: app/frontend/README.md
• UI/UX: UI_GUIDELINES.md
• Setup: GETTING_STARTED.md
• Architecture: claude.md

---

🤝 Contributing

Want to add features? Follow these steps:

1. Read claude.md for architecture overview
2. Check UI_GUIDELINES.md for design principles
3. Add backend endpoints in app/backend/api/
4. Add frontend pages in app/frontend/app/routes/
5. Test with test_backend.py and manual testing
6. Update documentation

---

📝 Changelog

v1.0.0-dev (2025-11-26) - MVP Implementation

Implementation Complete (Not Yet Tested on Hardware):

• WiFi Manager with full functionality (10 endpoints)
• Update Manager with GitHub integration (6 endpoints)
• UPS Manager with I2C battery monitoring (3 endpoints)
• BLE Manager with notification support (4 endpoints)
• Plugin Framework with example plugin (7 endpoints)
• Systemd service integration with security hardening
• Pi-gen build integration (stage 04)
• Port conflict resolution tools
• 3 new test scripts (UPS, BLE, plugins)
• 8 new documentation files

Technical:

• ~5,000+ lines of code
• 40+ API endpoints
• 6 managers (Session, WiFi, Update, UPS, BLE, Plugin)
• 12 documentation files
• 4 test suites

v0.1.0 (2025-11-25) - Foundation Release

Added:

• Complete FastAPI backend with PM3 integration
• Remix.js frontend with cyberpunk theme
• Dashboard with system status
• Command execution interface
• Settings page with WiFi UI
• Command logs
• Session management
• Real-time notifications (migrated to WebSocket in v1.0.0)
• Comprehensive documentation

Technical:

• ~2,700 lines of code
• 22 files
• 6 documentation files
• 4 web pages
• 10 API endpoints

---

🎯 Success Criteria

Phase 1: Foundation ✅ COMPLETE

• Working backend API
• Working frontend UI
• PM3 command execution
• Session management
• Real-time updates (WebSocket)
• Comprehensive documentation

Phase 2: Core Features (Implementation) ✅ COMPLETE

• WiFi manager implementation
• Update manager implementation
• UPS monitoring implementation
• BLE notifications implementation
• Plugin framework implementation
• Systemd services implementation
• Pi-gen integration scripts
• Port conflict resolution scripts
• Local testing (all tests passing)

Phase 3: MVP Deployment & Hardware Testing ✅ COMPLETE

• Deploy to actual Raspberry Pi Zero 2 W
• Test with real Proxmark3 hardware (Iceman firmware 2025-12-30)
• Test UPS HAT integration (PiSugar 2 detected and working)
• Test BLE on Pi hardware (advertising as DangerousPi)
• Combined frontend/backend deployment
• Build custom OS image with pi-gen
• Fix any hardware-specific issues (PATH fix for iw command)
• Performance optimization on Pi Zero 2 W (ongoing)
• WiFi mode detection fix (reports "client" when in AP mode)

Phase 4: Enhancement 🚧 IN PROGRESS

• Backup system
• HTTPS Settings UI (toggle, cert info, regenerate) - Done 2026-03-03
• Plugin hook wiring (pm3_command, update_check) - Done 2026-03-03
• WebSocket authentication (token-based) - Done 2026-03-03
• Full authentication (JWT, multi-user, RBAC)
• Additional plugins
• Advanced PM3 features

Phase 5: Release 📋 PLANNED

• Beta testing program
• Public release
• User testing
• Community feedback
• Plugin marketplace

---

💬 Notes

Why this architecture?

• FastAPI: Async support, auto-docs, fast
• Remix: SSR performance, progressive enhancement
• SQLite: Simple, no external database needed
• WebSocket: Bidirectional real-time communication, better reconnection handling
• Service Layer: Clean separation of concerns, dependency injection for testability

Why cyberpunk theme?

• Matches Dangerous Things brand aesthetic
• High contrast works well on small screens
• Dark mode saves battery on mobile devices
• Monospace fonts create terminal feel

Why no CSS framework?

• Frameworks add 50-200KB overhead
• Custom CSS is faster to load
• More control over design
• Easier to maintain

---

Built with ❤️ by Dangerous Things