# Action Plan: Reverse-Engineer Hevy Live Workout State

## EXECUTIVE SUMMARY

**Goal**: Discover how Hevy stores/transmits live workout state so Fitbit can read it.

**Status**: Research complete. Three viable paths identified. Ready to execute experiments.

**Recommended first move**: Web app DevTools capture (Experiment 1) — 30 min, no setup.

---

## PHASE 1: Quick Win (Today)

### Experiment 1: Web App Network Capture
**Time**: 30 min | **Risk**: None | **Requires**: Chrome + Hevy account

```
1. Log into hevy.com on Chrome
2. F12 → Network → Filter "api.hevyapp.com" → Preserve log
3. Start a workout (any routine or empty workout)
4. Complete a few sets
5. Finish workout
6. Right-click → Save all as HAR with content
7. Report: What endpoints fired during the live workout?
```

**Success criteria**: List of 2-5 new endpoint paths related to workout sessions.

---

## PHASE 2: Deep Dive (This Week)

### Experiment 2: ADB Local State Extraction
**Time**: 30 min | **Risk**: Low | **Requires**: Pixel 9a + USB cable

```
1. adb devices  # verify connection
2. Start a workout in Hevy on the phone
3. adb shell run-as com.hevy ls /data/data/com.hevy/databases/
4. adb shell "run-as com.hevy cat /data/data/com.hevy/databases/RKStorage" > rkstorage.db
5. sqlite3 rkstorage.db ".dump" | grep -i workout
6. Document the JSON structure of active workout state
```

**Success criteria**: Extract the MobX/AsyncStorage key structure for active workout state.

### Experiment 3: hevy-shared Module Analysis
**Time**: 15 min | **Risk**: None | **Requires**: npm

```
1. npm pack hevy-shared
2. tar xzf hevy-shared-*.tgz
3. cat package/built/websocket.js
4. cat package/built/constants.js
5. cat package/built/index.d.ts | grep -i workout
```

**Success criteria**: WebSocket endpoint URL, API constants, type definitions.

---

## PHASE 3: Heavy Lifting (If Needed)

### Experiment 4: APK Decompile
**Time**: 1-2 hours | **Risk**: Low | **Requires**: 156MB download + jadx

```
1. wget APK from apkpure
2. jadx -d hevy_decompiled/ hevy.apk
3. strings resources/assets/index.android.bundle | grep -oP 'https?://[^"\47\s,\}\]]+' | sort -u > urls.txt
4. grep "api.hevyapp.com" urls.txt
5. grep -i "workout\|session\|draft" resources/assets/index.android.bundle > workout_refs.txt
```

**Success criteria**: Complete list of internal API endpoints, WebSocket URLs, and storage keys.

### Experiment 5: mitmproxy Capture (if cert pinning is an issue)
**Time**: 2-4 hours | **Risk**: Medium | **Requires**: Ubuntu server, patched APK

```
1. Start mitmweb on Ubuntu server
2. Patch APK with apk-mitm
3. Install patched APK on Pixel 9a
4. Configure proxy to Ubuntu server
5. Start workout, capture all traffic
```

**Success criteria**: Intercept all API calls during a live workout without encryption.

---

## DECISION TREE

```
Can you access Hevy web app?
├── YES → Experiment 1 (30 min) → Found live endpoints?
│   ├── YES → Proceed to integration design
│   └── NO  → Experiment 2 (ADB extraction)
└── NO  → Experiment 2 (ADB extraction)

Can you access Pixel 9a via ADB?
├── YES → Experiment 2 → Found live state in AsyncStorage?
│   ├── YES → Proceed to integration design
│   └── NO  → Experiment 4 (APK analysis)
└── NO  → Experiment 4 (APK analysis)

APK analysis found endpoints + storage keys?
├── YES → Proceed to integration design
└── NO  → Experiment 5 (mitmproxy capture)
```

---

## INTEGRATION DESIGN (what to build after discovery)

### If live API endpoints exist:
```
Fitbit companion app → Pipo backend → Hevy internal API
                                  → GET /workout_sessions/active
                                  → PUT /workout_sessions/{id} (update from watch)
```

### If only local state is accessible:
```
Pixel 9a (Hevy app) → Local HTTP server (termux/tiny) → Tailscale → Pipo backend → Fitbit
                    → OR: ADB polling from Pipo backend over Tailscale SSH
```

### If neither works:
```
Fitbit acts as PRIMARY workout companion (not Hevy mirror)
Fitbit → Pipo backend → Hevy v1 API (POST /v1/workouts on completion)
```

---

## DEPENDENCIES TO INSTALL

```bash
# On Ubuntu server:
sudo apt-get install -y adb android-tools-adb mitmproxy jadx sqlite3

# On dev machine:
# Chrome DevTools (already available)
# Python 3 (already available)

# Optional:
npm install -g apk-mitm   # for cert pinning bypass
pip install frida-tools    # for runtime hooking (if needed)
```

---

## REFERENCES

- [dmzoneill/hevyapp-api](https://github.com/dmzoneill/hevyapp-api) — Internal API docs
- [gab-es21/hevy-workout-generator](https://github.com/gab-es21/hevy-workout-generator) — Internal API usage proof
- [casudo/Hevy-Insights](https://github.com/casudo/Hevy-Insights) — OAuth2 login flow
- [Hevy Official API](https://api.hevyapp.com/docs/) — Public API docs
- [Hevy APK on APKPure](https://apkpure.com/hevy-gym-log-workout-tracker/com.hevy) — Download
- [mitmproxy docs](https://docs.mitmproxy.org/) — Proxy setup
- [apk-mitm](https://www.npmjs.com/package/apk-mitm) — Cert pinning bypass