MotionMate

An Indonesian home-rehabilitation prototype with browser-based pose tracking, guided exercise sessions, and progress history.

MotionMate reached 6th-place national finalist in the FLORE New Venture Competition. The repository focuses on turning a rehabilitation concept into a testable product workflow: onboarding, exercise selection, live session tracking, completion metrics, and a zero-registration demo.

MotionMate is an educational prototype, not a medical device. Pose-derived feedback is approximate and does not replace a clinician’s assessment or treatment plan.

What the product does

• Runs knee-extension and bicep-curl landmark tracking in the browser with MediaPipe Pose.
• Uses joint angles, smoothing buffers, hold thresholds, and a repetition state machine to reduce accidental rep counts.
• Supports manual rep and timer controls when camera tracking is unavailable.
• Saves completed sessions with reps, sets, duration, and a clamped 0–100 posture score.
• Shows session history, dashboard summaries, exercise guidance, and rehabilitation mini-games.
• Includes a dummy-data mode so reviewers can explore the workflow without creating an account.
• Keeps camera frames in the browser; the Flask backend receives completion metrics, not the video stream.

MediaPipe runtime assets are currently loaded from jsDelivr, so first use requires network access. Browser camera permission is requested only after the user starts pose tracking.

Architecture

Layer	Implementation
Web application	Flask 3 application factory and blueprints
Persistence	SQLAlchemy; SQLite by default, configurable database URL
Authentication	Session-based login and Werkzeug password hashing
Pose tracking	MediaPipe Pose in the browser
Session logic	Joint-angle thresholds, rep state machine, manual fallback
Interface	Jinja templates with responsive HTML/CSS/JavaScript
Verification	pytest route, model, validation, and security tests

Quick start

git clone https://github.com/evan-william/motionmate.git
cd motionmate
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linuxsource .venv/bin/activate
pip install -r requirements.txt
python app.py

Open http://localhost:5000.

To inspect the product without registering, choose Explore with Dummy Data on the landing page or visit /dummy/enable.

Main workflow

1. Register or enter dummy mode.
2. Select an exercise and start a rehabilitation session.
3. Use camera-assisted tracking or manual controls.
4. Review reps, sets, elapsed time, and the posture estimate.
5. Save the session and inspect history/dashboard summaries.

Both the browser form flow and JSON clients can complete a session. Browser submissions redirect back to the history view; JSON requests receive a structured response.

Project structure

.
├── app.py # Development entry point
├── app/
│ ├── __init__.py # App factory and security headers
│ ├── config.py # Development, testing, production settings
│ ├── models/ # User, exercise, session, progress, game data
│ ├── routes/ # Auth, dashboard, exercise, session, game flows
│ └── utils/ # Auth decorators and input validation
├── templates/
│ ├── sessions/tracker.html # MediaPipe tracking and session controls
│ ├── dashboard/ # Progress overview
│ ├── exercises/ # Exercise library and details
│ └── games/ # Memory and speech exercises
├── static/ # Images and application icons
└── tests/test_app.py # End-to-end Flask test suite

Configuration

Development defaults to SQLite. For another database or production deployment:

FLASK_ENV=productionSECRET_KEY=replace-with-a-long-random-valueDATABASE_URL=postgresql://user:password@host/database

Production startup fails if the placeholder secret is still in use. Session cookies are HTTP-only, SameSite=Lax, and secure in production. Responses include frame, MIME-sniffing, referrer, and browser-permission headers.

The project does not yet include database migrations; use a migration tool before evolving a persistent production schema.

Verification

pytest -q

Current local verification: 39 tests passing. Coverage includes registration and login, password hashing, open-redirect protection, demo mode, protected routes, completion through HTML forms and JSON, persisted session metrics, invalid metric handling, score clamping, production secret enforcement, and security headers.

Current limitations

• Pose thresholds currently support knee extension and bicep curl only.
• Accuracy is a product feedback heuristic, not a clinically validated measurement.
• The MediaPipe scripts are third-party CDN dependencies.
• No CSRF token framework or database migration system is included yet.
• Speech-game behavior depends on browser speech-recognition support.
• The demo dashboard includes illustrative data that is clearly labeled as dummy content.

License

See the repository license file for usage terms.