# Path C: Android Bridge — Fitbit Sense 2 ↔ Hevy via Pixel

Date: 2026-05-26
Owner: Chicho / Pipo
Status: SPIKE — DESIGN ONLY

## Verdict

**VIABLE with caveats. Best approach is a multi-tier bridge with notification interception as primary surface, accessibility UI control as fallback, and internal API discovery as stretch goal.**

The Pixel 9a sits between the Fitbit Sense 2 and the Hevy app. The bridge reads Hevy's live workout state (notification or screen), relays it to the Pipo backend, and the Fitbit companion app displays it on the watch. Control actions from the watch flow back through the companion → backend → bridge → Hevy app.

This approach works **because**:
- Hevy posts a rich "live activity" notification during active workouts showing current exercise, set count, rest timer, and sometimes weight/rep targets.
- Android's `NotificationListenerService` can read that notification content without root.
- The Fitbit companion already does HTTPS `fetch()` to the backend.
- Chicho owns the Pixel 9a and can enable ADB/developer options freely.

The primary risk is that **Hevy's notification format could change**. The bridge needs to be resilient with fallback strategies.

## Architecture Overview

```
┌─────────────────────┐     Bluetooth      ┌──────────────────────┐
│   Fitbit Sense 2    │ ◄──────────────►  │   Fitbit App (Pixel) │
│                     │   messaging API    │                      │
│  /app/index.js      │                    │  /companion/index.js │
│  • Show exercise    │                    │  • fetch() to Pipo   │
│  • Log set (reps/   │                    │    backend (HTTPS)   │
│    weight/RIR)      │                    │  • relay to watch    │
│  • Rest timer       │                    │                      │
│  • Vibration        │                    └──────────┬───────────┘
└─────────────────────┘                               │
                                                      │ HTTPS
                                                      ▼
┌─────────────────────────────────────────────────────────────┐
│                    Pipo Backend (VPS)                        │
│                                                             │
│  /api/workout-plan/today    ← Hevy routines → watch         │
│  /api/live-workout/state    ← bridge writes, companion reads│
│  /api/live-workout/command  ← companion writes, bridge reads│
│  POST /v1/workouts          ← completed workout → Hevy API  │
└─────────────────────────────────────────────────────────────┘
                            ▲                    │
                   HTTPS    │                    │ HTTPS
                            │                    ▼
              ┌─────────────┴──────────────────────────┐
              │       Android Bridge (Pixel 9a)        │
              │                                        │
              │  Tier 1: NotificationListenerService   │
              │    └─ Reads Hevy live activity notif.  │
              │                                        │
              │  Tier 2: AccessibilityService          │
              │    └─ Reads Hevy UI, taps buttons      │
              │                                        │
              │  Tier 3: Hevy Internal API Client      │
              │    └─ Direct HTTPS to Hevy backend     │
              │                                        │
              │  Bridge Controller:                    │
              │    └─ Polls state → backend            │
              │    └─ Reads commands → executes on Hevy│
              └────────────────────────────────────────┘
                            │
                            │ Local / ADB
                            ▼
              ┌──────────────────────────┐
              │    Hevy App (Pixel 9a)   │
              │                          │
              │  • Live workout session  │
              │  • Notification posted   │
              │  • UI: exercises, sets   │
              │  • Internal API traffic  │
              └──────────────────────────┘
```

## Files in this spike

| File | Purpose |
|------|---------|
| `README.md` | This file — summary, verdict, architecture |
| `01-hevy-integration-surfaces.md` | What Hevy exposes on Android: notifications, UI, internal API, Wear OS sync |
| `02-fitbit-companion-constraints.md` | What the Fitbit companion can and cannot do on Android |
| `03-bridge-approaches.md` | Detailed comparison of bridge technologies (NotificationListener, Accessibility, ADB, Tasker, Automate, internal API) |
| `04-permissions-and-security.md` | Android permissions required, Google Play policy risks, security model |
| `05-risks-and-failure-modes.md` | What breaks, failure scenarios, mitigation strategies |
| `06-prototype-plan.md` | Step-by-step first prototype: what to build, in what order, acceptance criteria |