# 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](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

3. **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](README_DEV.md)
- **Frontend**: [app/frontend/README.md](app/frontend/README.md)
- **UI/UX**: [UI_GUIDELINES.md](UI_GUIDELINES.md)
- **Setup**: [GETTING_STARTED.md](GETTING_STARTED.md)
- **Architecture**: [claude.md](claude.md)

---

## 🤝 Contributing

Want to add features? Follow these steps:

1. Read [claude.md](claude.md) for architecture overview
2. Check [UI_GUIDELINES.md](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
- [x] Working backend API
- [x] Working frontend UI
- [x] PM3 command execution
- [x] Session management
- [x] Real-time updates (WebSocket)
- [x] Comprehensive documentation

### Phase 2: Core Features (Implementation) ✅ COMPLETE
- [x] WiFi manager implementation
- [x] Update manager implementation
- [x] UPS monitoring implementation
- [x] BLE notifications implementation
- [x] Plugin framework implementation
- [x] Systemd services implementation
- [x] Pi-gen integration scripts
- [x] Port conflict resolution scripts
- [x] Local testing (all tests passing)

### Phase 3: MVP Deployment & Hardware Testing ✅ COMPLETE
- [x] Deploy to actual Raspberry Pi Zero 2 W
- [x] Test with real Proxmark3 hardware (Iceman firmware 2025-12-30)
- [x] Test UPS HAT integration (PiSugar 2 detected and working)
- [x] Test BLE on Pi hardware (advertising as DangerousPi)
- [x] Combined frontend/backend deployment
- [x] Build custom OS image with pi-gen
- [x] 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
- [x] HTTPS Settings UI (toggle, cert info, regenerate) - Done 2026-03-03
- [x] Plugin hook wiring (pm3_command, update_check) - Done 2026-03-03
- [x] 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](https://dangerousthings.com)**