docs: update documentation for consolidated Python project structure

- Update README files to reference bongo_cat_app instead of app/
- Add resource_path helper to tray.py for PyInstaller compatibility
- Update API reference with new project structure
- Add development and setup guides
- Include requirements_app.txt for dependencies

Author: dentity007

README.md

@@ -75,18 +75,21 @@ git clone https://github.com/dentity007/bongo_cat_monitor_remix.git
 cd bongo_cat_monitor_remix
 ```
 
-### 2. Python Environment
+## Run (Python desktop app)
 ```bash
-# Create virtual environment
-python3 -m venv venv
-source venv/bin/activate  # On Windows: venv\Scripts\activate
-
-# Install dependencies
-cd app
-pip install -r requirements.txt
+# from repo root
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -r requirements_app.txt  # or: pip install -e .
+python bongo_cat_app/main.py
 ```
 
-### 3. Imgflip Setup (Optional)
+Project layout
+
+- `bongo_cat_app/` – Canonical Python desktop app (Tk/pystray)
+- `bongo-cat-electron/` – Optional Electron UI (not required to run the Python app)
+
+### 2. Imgflip Setup (Optional)
 The app works without any API configuration, but for dynamic triggers:
 
 1. **No authentication required!** - Imgflip API is free and doesn't need credentials
@@ -103,17 +106,17 @@ The app works without any API configuration, but for dynamic triggers:
 - "anakin" → Anakin Padme 4 Panel meme
 - And 13 more trending memes updated daily at midnight!
 
-### 4. ESP32 Setup
+### 3. ESP32 Setup
 1. Open `firmware/bongo_cat_monitor.ino` in Arduino IDE
 2. Install required libraries (TFT_eSPI, LVGL)
 3. Upload to your ESP32 board
 
-### 5. Hardware Monitoring Setup (Optional - Windows Only)
+### 4. Hardware Monitoring Setup (Optional - Windows Only)
 For advanced CPU/GPU temperature monitoring with privacy protection and API resilience:
 
 1. **Install Python dependencies**:
    ```bash
-   pip install -r bongo_cat_app/requirements_app.txt
+   pip install -r bongo_cat_app/requirements_hardware.txt
    ```
 
 2. **Enable in settings** (requires explicit consent):
@@ -149,7 +152,7 @@ For advanced CPU/GPU temperature monitoring with privacy protection and API resi
 - CPU monitoring requires admin rights on Windows
 - Check logs for circuit breaker state and cache hit/miss ratios
 
-### 6. API Resilience Features
+### 5. API Resilience Features
 The application includes enterprise-grade resilience patterns to ensure reliable operation:
 
 **Circuit Breaker Pattern**:
@@ -172,13 +175,7 @@ The application includes enterprise-grade resilience patterns to ensure reliable
 - Circuit breaker state monitoring
 - Debug logging for troubleshooting
 
-### 7. Run the App
-```bash
-cd app
-python main.py --mode normal
-```
-
-### 8. Test Triggers
+### 6. Test Triggers
 - Type "bullet" → Top Gun reference!
 - Type "drake" → Drake Hotline Bling meme
 - Type "bernie" → Bernie Sanders meme
@@ -222,17 +219,20 @@ bongo_cat_monitor_remix/
 └── 📄 LICENSE.txt                   # MIT License
 ```
 
+## Electron UI (optional)
+The Electron app lives in `bongo-cat-electron/` and provides an alternative user interface. It is not required for running or packaging the Python desktop app, and we keep it separate so Python-focused CI remains fast and focused.
+
 ## 🎮 Usage Guide
 
 ### Basic Operation
-1. **Start the app**: `python main.py --mode normal`
+1. **Start the app**: `python bongo_cat_app/main.py --mode normal`
 2. **Type normally**: Cat responds to your typing speed
 3. **Trigger memes**: Type special words for reactions
 4. **Monitor activity**: Cat shows system stats and animations
 
 ### Command Line Options
 ```bash
-python main.py [options]
+python bongo_cat_app/main.py [options]
 
 Options:
   --mode {normal,messenger,tutor}  Operation mode (default: normal)
@@ -270,7 +270,7 @@ Triggers are stored in JSON format with support for static and dynamic types:
 ```
 
 ### Environment Variables
-**No environment variables required!** The Imgflip API works without authentication. However, you can still create `app/.env` for future extensibility:
+**No environment variables required!** The Imgflip API works without authentication. However, you can still create `bongo_cat_app/.env` for future extensibility:
 
 ```env
 # Optional: For future API integrations
@@ -310,9 +310,9 @@ Type these words to trigger viral memes:
 ## 🛠️ Development
 
 ### Adding New Triggers
-1. Edit `app/triggers.json`
-2. Add trigger object with `trigger`, `response`, and `animation` fields
-3. Restart the app or it will auto-reload on next cycle
+1. Update `_local_fallback()` inside `bongo_cat_app/triggers_external.py` with your custom templates, or point the helper at your own API.
+2. Add trigger metadata (IDs, names, URLs) that match what the firmware expects.
+3. Restart the app or let the daily cache refresh pick up the new data.
 
 ### Custom Animations
 1. Add animation files to `animations/` directory
@@ -408,7 +408,7 @@ No ports found—plug in ESP32!
 ```
 ModuleNotFoundError: No module named 'praw'
 ```
-**Solution**: Run `pip install -r requirements.txt` in activated virtual environment
+**Solution**: Run `pip install -e .` in your activated virtual environment
 
 **Virtual Environment Issues**
 ```
@@ -442,5 +442,3 @@ python3: command not found
 **Made with ❤️ for the Bongo Cat community**
 
 ![Demo](https://via.placeholder.com/400x200?text=CatJAM+Demo)
-
-

bongo_cat_app/README.md

@@ -84,8 +84,7 @@ pip install -r requirements_app.txt
 
 ### Running from Source
 ```bash
-cd bongo_cat_app
-python main.py
+python bongo_cat_app/main.py
 ```
 
 ### Building Executable
@@ -203,4 +202,4 @@ Contributions welcome! Areas for improvement:
 
 ---
 
-*Keep your Bongo Cat happy with real-time data!* 🐱💻 
+*Keep your Bongo Cat happy with real-time data!* 🐱💻 

bongo_cat_app/tray.py

@@ -12,6 +12,12 @@
 import os
 from typing import Optional, Callable
 
+
+def resource_path(rel_path: str) -> str:
+    """Return an absolute path for bundled resources (PyInstaller-safe)."""
+    base = getattr(sys, "_MEIPASS", os.path.abspath(os.path.dirname(__file__)))
+    return os.path.join(base, rel_path)
+
 class BongoCatSystemTray:
     """System tray integration for Bongo Cat application"""
 
@@ -52,24 +58,13 @@ def start_detached(self):
     def create_icon(self):
         """Create the system tray icon"""
         try:
-            # Try to load icon from file first - check multiple formats
-            # Support both development and exe paths
-            import sys
-            if getattr(sys, 'frozen', False):
-                # Running as exe - assets are in the same directory
-                base_path = sys._MEIPASS if hasattr(sys, '_MEIPASS') else os.path.dirname(sys.executable)
-            else:
-                # Running as script - look in bongo_cat_app/assets
-                base_path = os.path.dirname(__file__)
-            
             possible_paths = [
-                os.path.join(base_path, "assets", "tray_icon.ico"),
-                os.path.join(base_path, "assets", "tray_icon.png"),
-                os.path.join(base_path, "assets", "tray_icon.jpg"),
-                os.path.join(base_path, "assets", "tray_icon.jpeg"),
-                # Fallback paths for development
-                "assets/tray_icon.png",
-                "bongo_cat_app/assets/tray_icon.png"
+                resource_path(os.path.join("assets", "tray_icon.ico")),
+                resource_path(os.path.join("assets", "tray_icon.png")),
+                resource_path(os.path.join("assets", "tray_icon.jpg")),
+                resource_path(os.path.join("assets", "tray_icon.jpeg")),
+                os.path.join("assets", "tray_icon.png"),
+                os.path.join("bongo_cat_app", "assets", "tray_icon.png"),
             ]
 
             icon_image = None
@@ -440,4 +435,4 @@ def main():
     print("✅ System tray test completed")
 
 if __name__ == "__main__":
-    main() 
+    main()

docs/api_reference.md

@@ -14,7 +14,7 @@ Main application orchestrator with resilient initialization.
 
 **Command Line Arguments:**
 ```bash
-python main.py [options]
+python bongo_cat_app/main.py [options]
 
 Options:
   --mode {normal,messenger,tutor}  Operation mode (default: normal)
@@ -461,4 +461,4 @@ DISPLAY_HEIGHT=320
 
 ---
 
-*API Version: 1.1.0 | Last Updated: September 17, 2025*
+*API Version: 1.1.0 | Last Updated: September 17, 2025*

docs/development_guide.md

@@ -136,9 +136,9 @@ git checkout -b feature/your-feature-name
 
 3. **Setup Python Environment**
 ```bash
-python3 -m venv venv
-source venv/bin/activate
-cd app && pip install -r requirements.txt
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements_app.txt  # or: pip install -e .
 ```
 
 4. **Install Development Dependencies**
@@ -296,7 +296,7 @@ debugPrint("Processing command: " + command);
 screen /dev/ttyUSB0 115200
 
 # Monitor Python app output
-python main.py --mode normal 2>&1 | tee debug.log
+python bongo_cat_app/main.py --mode normal 2>&1 | tee debug.log
 ```
 
 ### Performance Optimization
@@ -318,11 +318,10 @@ python main.py --mode normal 2>&1 | tee debug.log
 #### Python Application
 ```bash
 # Create distribution
-cd app
-pyinstaller --onefile --name catjam main.py
+pyinstaller packaging/app.spec --noconfirm
 
-# Install system-wide
-sudo cp dist/catjam /usr/local/bin/
+# Install system-wide (optional Linux example)
+sudo cp dist/BongoCatMonitor /usr/local/bin/BongoCatMonitor
 ```
 
 #### ESP32 Firmware
@@ -366,4 +365,4 @@ arduino-cli upload --fqbn esp32:esp32:esp32 --port /dev/ttyUSB0 firmware/
 
 ---
 
-*Development Guide Version: 1.0.0 | Last Updated: September 17, 2025*
+*Development Guide Version: 1.0.0 | Last Updated: September 17, 2025*

docs/setup_guide.md

@@ -32,16 +32,15 @@ cd bongo_cat_monitor_remix
 ### Step 2: Python Environment Setup
 ```bash
 # Create virtual environment
-python3 -m venv venv
+python3 -m venv .venv
 
 # Activate virtual environment
-source venv/bin/activate  # macOS/Linux
+source .venv/bin/activate  # macOS/Linux
 # OR
-venv\Scripts\activate     # Windows
+.venv\Scripts\activate     # Windows
 
 # Install dependencies
-cd app
-pip install -r requirements.txt
+pip install -r requirements_app.txt  # or: pip install -e .
 ```
 
 ### Step 3: ESP32 Firmware Setup
@@ -108,14 +107,14 @@ Once running, you'll have access to **20 trending memes** that update **daily at
 
 #### Test Python Environment
 ```bash
-cd app
+# from repo root
 python --version  # Should show Python 3.9+
 python -c "import requests, pynput, serial; print('✅ All imports successful')"
 ```
 
 #### Test ESP32 Connection
 ```bash
-python main.py --mode normal
+python bongo_cat_app/main.py --mode normal
 # Should show "Running in normal mode. Type away!"
 # If ESP32 not connected: "No ports found—plug in ESP32!"
 ```
@@ -132,27 +131,14 @@ python main.py --mode normal
 ## Configuration Options
 
 ### Trigger Configuration
-Edit `app/triggers.json` to customize triggers:
-
-```json
-{
-  "static": [
-    {
-      "trigger": "your_word",
-      "response": "Your custom response",
-      "animation": "meme_surprise"
-    }
-  ],
-  "dynamic": []
-}
-```
+Update the fallback templates in `_local_fallback()` inside `bongo_cat_app/triggers_external.py`, or point that helper at your own API endpoint. Restart the desktop app (or let the daily cache refresh) to pick up new templates.
 
 ### Serial Port Configuration
 If auto-detection fails, specify port manually:
 ```bash
-python main.py --port /dev/ttyUSB0  # Linux
-python main.py --port COM3          # Windows
-python main.py --port /dev/tty.usbserial-0001  # macOS
+python bongo_cat_app/main.py --port /dev/ttyUSB0  # Linux
+python bongo_cat_app/main.py --port COM3          # Windows
+python bongo_cat_app/main.py --port /dev/tty.usbserial-0001  # macOS
 ```
 
 ## Troubleshooting
@@ -229,7 +215,7 @@ pip install -r requirements.txt
 ### Getting Help
 - Check [Issues](https://github.com/dentity007/bongo_cat_monitor_remix/issues) for common problems
 - Review [README.md](README.md) for detailed documentation
-- Test with `python main.py --mode normal` to verify Imgflip integration
+- Test with `python bongo_cat_app/main.py --mode normal` to verify Imgflip integration
 
 ## Next Steps
 1. **Customize Triggers**: Add your favorite meme triggers
@@ -239,4 +225,4 @@ pip install -r requirements.txt
 
 ---
 
-*Last updated: September 17, 2025*
+*Last updated: September 17, 2025*