BoxCoach 🥊

A personal boxing development system that runs on your phone, not a fitness tracker. Every session, sparring round, drill, decision and coach note becomes evidence about your boxing. A development model is built from that evidence, and the training plan is the model's output.

It's an installable web app (PWA). It works offline after the first load, and all your data stays on your phone.

Architecture

            ┌──────────────────────┐
            │ MEMORY (by source)   │  coach said · your notes · AI observations · measured
            └──────────┬───────────┘
                       ↓
┌─────────────┐   ┌──────────────────┐   ┌─────────────────────┐
│ TRAINING LOG│──→│ DEVELOPMENT MODEL│←──│ CAMERA / VIDEO / IMU│
└─────────────┘   │ 18 skills from   │   └─────────────────────┘
                  │ evidence         │
                  └────────┬─────────┘
                           ↓
                  ┌──────────────────┐  problems · priorities · hypotheses
                  │ DECISION ENGINE  │  recovery · fight camp phase
                  └────────┬─────────┘
                           ↓
                  ┌──────────────────┐
                  │ ADAPTIVE PLAN →  │  week plan · "what should I train today?"
                  │ NEXT SESSION     │  constraint + opponent rounds
                  └──────────────────┘

The data model is built around skills, observations, hypotheses, training stimuli (constraints, opponents, patterns), outcomes (per-round metrics, hits, decisions) and coach feedback.

Coach me

One button on Today. It asks only what it needs (time, equipment, how you feel), then:

1. Finds the root problems (coachme.js detectWeaknesses): symptoms from sparring hits, repeated habits, camera measurements, fatigue decay and coach notes are grouped under the habit that causes them ("getting hit backing up isn't the problem; you stay square after your combinations"). Each has a do this / not that replacement and a measurement that tests whether it caught on.
2. Builds today's session around the time, gear and energy you have: warm-up, a drill from the root problem's 4-level ladder (purpose, success condition, progression, regression), constraint rounds, conditioning that fits your equipment. It cuts volume on its own when recovery is poor, technical quality is dropping, you're tired or sore, or you're back after a break, and says why.
3. Adapts during the session: combo calls end with your fix ("…then pivot out"); after each round it simplifies, pushes harder, or switches the stimulus if fatigue is breaking your technique.
4. Judges it afterwards: the drill's success condition passes or not; two passes move the ladder up, two misses move it down.

Also: combos built on what you already throw, a 4-weekly benchmark (same 3 × 2-min test) to compare months, "my coach disagrees" overrides that the bot remembers, and a plain-language first-run setup.

Features

#	Feature	Where
1	Skill tree: 18 attributes (footwork, distance, head movement, defense, jab, cross, hooks, uppercuts, combinations, counters, feints, timing, rhythm, angles, ring cutting, clinch, conditioning, fight IQ). Calculated from evidence and never set by hand, each with a confidence level and a list of the evidence behind it	Boxer → Skills
2	Technique decay detection: compares fresh rounds with late rounds and separates technical weakness (bad even when fresh) from fatigue-induced weakness (fine early, breaks late), with advice for each	Boxer → Analysis
3	Training transfer score: tracks each pattern through drilling → shadowboxing → bag → sparring (attempted and landed). The camera counts combinations automatically	Boxer → Analysis
4	"Why did you get hit?" Tap the reason after sparring (failed exit, hands down, rhythm, distance…); results are aggregated over your last 10 sessions and feed the plan	Log (sparring), Boxer → Analysis
5	Style discovery: tendencies (jab usage, movement, combination volume, body work, exits, counters) found from data, plus the style you currently lean towards, and how it has changed	Boxer → Style
6	Decision drills: fight scenarios with reaction time; wrong answers come back more often (spaced repetition); repeated mistakes are listed; builds a Fight IQ score	Coach → Fight IQ
7	Randomised shadowboxing generator: each round gets a constraint and sometimes an opponent, chosen from your weaknesses and gaps in exposure	Train, Today
8	Constraint-based training: rounds are problems to solve ("every combo ends with an exit"); compliance is auto-scored by the camera where possible, otherwise you rate it	Live session, post-session review
9	Round-by-round fatigue map: technique / pace / defense / footwork per round, and which one breaks first	Session summary, Boxer → Analysis
10	Deload / overtraining logic: session load (effort × minutes), acute vs 4-week chronic load, and morning check-ins (sleep, soreness, motivation, resting HR). Detects performance dropping while load rises and cuts volume automatically

Plus: a round timer with voice combos, the live camera coach, motion-sensor punch counting, a weekly plan built around your gym days, weight tracking in pounds with a pro weight-class picker, progress charts and JSON backup.

Honest limits

• Camera analysis is an estimate from one phone camera. Confidence scores are shown so you can judge detections.
• Ratings start at 50 and only move with evidence. A skill with no evidence says so.
• Hypotheses are tests on your own data, not science. Small samples are labelled inconclusive rather than overclaimed.
• Decision-drill "best answers" follow conventional coaching; context in a real fight always matters.

Put it on your phone

The camera and motion sensors only work over https, so the app needs to be hosted. GitHub Pages is already set up:

1. In this repo on GitHub, go to Settings → Pages and set Source to GitHub Actions (one-time).
2. Merge to main. The workflow runs the tests and publishes the web/ folder.
3. Open https://<your-username>.github.io/<repo-name>/ on your phone.
4. Add to Home Screen. iPhone: Safari → Share → Add to Home Screen. Android: Chrome → ⋮ → Install app.

Development

No build step; it's plain HTML/CSS/ES modules.

npm start   # serves web/ at http://localhost:8080 (localhost counts as secure, so the camera works)
npm test    # unit tests for the whole model: pose analysis, skills, decay, transfer, recovery, hypotheses, engine, plan

Module	Purpose
web/js/library.js	Skills, hit reasons, constraints, opponents, decision scenarios, patterns
web/js/skills.js	Evidence extraction, ratings, proof of improvement, timeline, style
web/js/analysis.js	Fatigue map, decay, minimum effective dose, transfer, hit analysis, exposure
web/js/recovery.js	Load, readiness, deload detection
web/js/hypotheses.js	Hypothesis templates, testing, evaluation
web/js/engine.js	Problem ranking, priorities, round generator, today's session, AI observations
web/js/plan.js	Weekly plan, fight camp phases, rescheduling, weight
web/js/coach.js	Session scoring, feedback, habit memory
web/js/form.js	Pose → punches (with confidence), combinations, guard, stance, footwork
web/js/views/*	Boxer, Coach, review and video screens
web/js/app.js	Today, Plan, Train, Log, live session