refactor: Implement 2-container architecture to solve USB stability issues

BREAKING CHANGE: Switched from single-container to multi-container setup

This commit introduces a meshcore-bridge service that isolates USB device
access from the main application, resolving persistent USB timeout and
deadlock issues in Docker + VM environments.

Changes:
- Add meshcore-bridge/ - Lightweight HTTP API wrapper for meshcli
  - Flask server exposes /cli endpoint (port 5001, internal only)
  - Exclusive USB device access via --device flag
  - Health check endpoint at /health

- Refactor app/meshcore/cli.py
  - Replace subprocess calls with HTTP requests to bridge
  - Add requests library dependency
  - Better error handling for bridge communication

- Update docker-compose.yml
  - Define meshcore-bridge and mc-webui services
  - Create meshcore-net Docker network
  - Add depends_on with health check condition
  - Bridge gets USB device, main app uses HTTP only

- Modify Dockerfile
  - Remove meshcore-cli installation from main app
  - Lighter image without gcc dependencies

- Update config.py
  - Add MC_BRIDGE_URL environment variable
  - Remove meshcli_command property (no longer needed)

- Update documentation (README.md, .claude/instructions.md)
  - Document 2-container architecture
  - Add troubleshooting section for bridge
  - Update prerequisites (no host meshcore-cli needed)
  - Add architecture diagram in project structure

Benefits:
✅ Solves USB device locking after container restarts
✅ Restartable main app without USB reset
✅ Better separation of concerns
✅ Easier debugging (isolated meshcli logs)
✅ No manual USB recovery scripts needed

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

docker-compose.yml

@@ -1,6 +1,29 @@
 version: '3.8'
 
 services:
+  # MeshCore Bridge - Handles USB communication with meshcli
+  meshcore-bridge:
+    build:
+      context: ./meshcore-bridge
+      dockerfile: Dockerfile
+    container_name: meshcore-bridge
+    restart: unless-stopped
+    devices:
+      - "${MC_SERIAL_PORT}:${MC_SERIAL_PORT}"
+    volumes:
+      - "${MC_CONFIG_DIR}:/root/.config/meshcore:rw"
+    environment:
+      - MC_SERIAL_PORT=${MC_SERIAL_PORT}
+    networks:
+      - meshcore-net
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:5001/health')"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 10s
+
+  # Main Web UI - Communicates with bridge via HTTP
   mc-webui:
     build:
       context: .
@@ -9,13 +32,11 @@ services:
     restart: unless-stopped
     ports:
       - "${FLASK_PORT:-5000}:5000"
-    devices:
-      - "${MC_SERIAL_PORT}:${MC_SERIAL_PORT}"
     volumes:
       - "${MC_CONFIG_DIR}:/root/.config/meshcore:rw"
       - "${MC_ARCHIVE_DIR:-./archive}:/root/.archive/meshcore:rw"
     environment:
-      - MC_SERIAL_PORT=${MC_SERIAL_PORT}
+      - MC_BRIDGE_URL=http://meshcore-bridge:5001/cli
       - MC_DEVICE_NAME=${MC_DEVICE_NAME}
       - MC_CONFIG_DIR=/root/.config/meshcore
       - MC_REFRESH_INTERVAL=${MC_REFRESH_INTERVAL:-60}
@@ -28,9 +49,18 @@ services:
       - FLASK_DEBUG=${FLASK_DEBUG:-false}
     env_file:
       - .env
+    depends_on:
+      meshcore-bridge:
+        condition: service_healthy
+    networks:
+      - meshcore-net
     healthcheck:
       test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:5000/api/status')"]
       interval: 30s
       timeout: 10s
       retries: 3
       start_period: 10s
+
+networks:
+  meshcore-net:
+    driver: bridge