feat: initial project scaffold — server, client, Android APK

- FastAPI server with audio mixer (Windows + Voicemeeter), media tracking, notifications (progress + alerts), telemetry, and system tray .exe build - Test suite covering notifications, audio mixer, media, telemetry, and API - E-Ink web client (vanilla JS, DOM API, block meters, swipe gestures) - Android WebView APK for BOOX Go 7 Color Gen II (Android 13, Kotlin) - Design decision records in .pi/docs/design/ - PyInstaller build script for server .exe
2026-07-01 11:19:32 +00:00
commit 0b4f739d12
36 changed files with 3916 additions and 0 deletions
@@ -0,0 +1,153 @@
+# E-INK Dashboard Ecosystem ~ Paperdash
+
+A local network dashboard ecosystem designed for the **Onyx Boox Go 7 Color** (Android E-Ink display). It displays real-time Windows desktop states including media playback, audio mixer channels (Windows default output or Voicemeeter), system telemetry, and custom script notifications (progress bars and rich text alerts).
+
+**Copyright (c) Imrayya (2026)** — MIT License
+
+## Architecture
+
+Paperdash bypasses heavyweight native Android UIs in favor of a lightweight, asynchronous Python server communicating via low-overhead WebSockets to a highly optimized E-Ink web client.
+
+```mermaid
+flowchart TD
+    subgraph WindowsHost["WINDOWS HOST PC"]
+        subgraph Subsystems["Subsystems"]
+            Media["WinRT Media API"]
+            Audio["Windows Audio / Core Audio"]
+            VM["Voicemeeter API"]
+            HW["HWiNFO Shared Memory"]
+        end
+        Server["FastAPI Server"]
+        StateAgg["State Aggregator"]
+        Auth["Token Auth Engine"]
+    end
+
+    subgraph External["EXTERNAL CLIENTS"]
+        Script["Custom Script / CLI"]
+    end
+
+    subgraph Boox["ONYX BOOX GO 7 COLOR (Android 13)"]
+        APK["Android WebView APK
+        (Kotlin)"]
+        style APK fill:#000,color:#fff
+    end
+
+    Media --> Server
+    Audio --> Server
+    VM --> Server
+    HW --> Server
+    Server --> StateAgg
+    Server --> Auth
+    Script -->|Bearer Token| Auth
+    StateAgg -->|WebSocket| WebView
+    Auth -->|PIN Auth| WebView
+```
+
+**Client-side optimizations:** PIN-authenticated WebSocket connection, static DOM updates (no smooth scrolling/fades), full-screen CSS Grid layout with static tap-and-swipe gestures.
+
+## Tech Stack
+
+### Server (Python 3.11+, Windows)
+
+- **FastAPI + Uvicorn** — ASGI web framework with native async WebSocket handling
+- **winsdk** — Windows Media API for GSMTC (Global System Media Transport Controls)
+- **pysounddevice / pycaw** — Generic Windows Core Audio API for default output volume and mute
+- **voicemeeter-api** — Voicemeeter Remote API wrapper for per-strip mixer controls
+- **pyhwinfo** — Hardware telemetry via HWiNFO64 Shared Memory
+- **PyInstaller** — Compiles the server to a standalone `.exe` with system tray icon
+
+### Client (BOOX Go 7 Color, Android 13)
+
+- **Custom Android WebView APK** — Kotlin app wrapping the web client in a full-screen WebView
+- **Vanilla JavaScript (ES6+) + CSS** — configured for monochrome/high-contrast E-Ink palettes
+
+## Features
+
+- **Media Playback Tracking** — Song title, artist, playback percentage, and cover art via Windows GSMTC
+- **Audio Mixer Control** — Real-time volume and mute from Windows default output or Voicemeeter per-strip gains, mutes, and track states
+- **Hardware Telemetry** — CPU/GPU core temps, VRAM usage from HWiNFO64
+- **Custom Notifications** — External scripts can push progress bars or rich text alerts via `POST /api/v1/notify`
+- **E-Ink Optimized UI** — High-contrast styling, discrete zone gestures, minimal refresh
+- **System Tray .exe** — Runs unobtrusively in the Windows notification bar with a quit option
+
+## Authentication
+
+1. **Dashboard UI (Boox Tablet):** Shared PIN authentication via WebSocket handshake (`?pin=XXXX`)
+2. **External Scripts/CLI:** Static Bearer Token via `Authorization: Bearer <SECRET_TOKEN>` header
+
+## Project Structure
+
+```
+e-ink-dash/
+├── .pi/
+│   ├── docs/design/       # Design decision records
+│   └── paperdash_architecture_document.txt
+├── server/                # Python FastAPI server
+│   ├── main.py            # Application entry point
+│   ├── audio_mixer.py     # Audio mixer abstraction (Windows + Voicemeeter)
+│   ├── media.py           # Media playback tracking (GSMTC)
+│   ├── notifications.py   # Notification system (progress + alerts)
+│   ├── telemetry.py       # Hardware telemetry (HWiNFO)
+│   ├── tray_wrapper.py    # System tray .exe wrapper
+│   ├── build_exe.py       # PyInstaller build script
+│   ├── requirements.txt
+│   └── tests/             # Test suite
+├── client/                # E-Ink web client
+│   ├── index.html
+│   ├── style.css
+│   └── app.js
+├── README.md
+├── LICENSE
+└── .gitignore
+```
+
+## Getting Started
+
+### Server
+
+```bash
+cd server
+python -m venv venv
+venv\Scripts\activate  # Windows
+pip install -r requirements.txt
+python -m uvicorn main:app --host 0.0.0.0 --port 8921
+```
+
+Set environment variables:
+
+- `DASHBOARD_PIN` — 4-digit PIN for the E-Ink client
+- `API_TOKEN` — Bearer token for external scripts
+
+### Build .exe
+
+```bash
+cd server
+python build_exe.py
+# Output: server/dist/PaperDash.exe
+```
+
+### Client (Android APK)
+
+The web client is bundled into an Android APK. Open Android Studio, sync Gradle, and run on the BOOX Go 7 Color.
+
+```bash
+cd android
+./gradlew assembleDebug
+# APK at: app/build/outputs/apk/debug/app-debug.apk
+```
+
+Install via ADB:
+
+```bash
+adb install app/build/outputs/apk/debug/app-debug.apk
+```
+
+The WebView loads `file:///android_asset/index.html` and connects to the server via WebSocket at `ws://<pc-ip>:8921/ws`.
+
+### Design Decisions
+
+See `.pi/docs/design/` for detailed design decision records covering architecture, audio mixer, notifications, and the .exe build.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.