Arise is a local wellness and fitness web app built with a Flask backend and a React + Vite frontend. It combines AI assisted exercise tracking, yoga pose guidance providing

The app is designed to run on your own machine through localhost. It uses your webcam for exercise and yoga, stores player progress locally, and includes a dark UI with multiple sections for training, mindfulness, and gamified progress.

• Project Overview
• Main Features
• Tech Stack
• Project Structure
• Prerequisites
• Setup and Installation
• How to Run the App
• How to Use the App
• Backend-Only Mode
• Local Data and Persistence
• Troubleshooting
• API Overview

Arise is built around a few experiences:

• Home: an introduction and landing area for the project.
• Exercise: live rep tracking for supported workouts using pose detection.
• Yoga: live yoga pose guidance with similarity scoring and feedback.
• Meditation: an animated breathing guide with adjustable inhale and exhale timing.
• Daily Quests: rotating daily goals, XP, streak tracking, and a local leaderboard.
• Contact Us: a simple contact form that stores messages locally.

The project is meant to feel like a personal training and wellness dashboard rather than just a computer vision demo.

• Live exercise tracking with webcam or bundled sample clips
• Supported exercise modes:
  • push-up
  • pull-up
  • squat
  • sit-up
• Yoga pose guidance with reference images and alignment feedback
• Guided meditation and breathing with adjustable inhale and exhale durations
• Daily quests that refresh on a 24 hour cycle
• XP rewards, completion streaks, and a local leaderboard
• Persistent local player progress
• Voice coaching for exercise, yoga, and meditation
• Contact form with local message storage

• Python 3.10
• Flask
• MediaPipe
• OpenCV
• NumPy
• Pandas

• React
• Vite
• Plain CSS

• Local JSON files in the data/ folder
• Browser local storage for player identity and UI preferences

.
├── app_config.py              # Shared app settings and paths
├── server.py                  # Flask API entry point
├── tracker_service.py         # Exercise session management and video streaming
├── yoga_service.py            # Yoga session management and pose feedback
├── rewards_service.py         # Daily quests, XP, streaks, leaderboard
├── voice_service.py           # Local voice clip generation and caching
├── contact_service.py         # Contact form storage logic
├── exercise_catalog.py        # Supported exercise metadata
├── yoga_catalog.py            # Supported yoga pose metadata
├── main.py                    # Legacy backend-only OpenCV runner
├── Exercise_videos/           # Sample clips for workout testing
├── yoga_backend/              # Yoga pose logic and reference assets
├── data/                      # Local saved data and generated files
├── frontend/
│   ├── src/App.jsx            # Main React app
│   ├── src/styles.css         # Main styles
│   ├── vite.config.js         # Dev server config and backend proxy
│   └── package.json           # Frontend dependencies and scripts
└── README.md

Before you run Arise, make sure you have the following installed:

• Python 3.10
• Node.js 18+
• npm

The current voice coach implementation uses macOS system speech tools such as say and afconvert. That means the TTS works best on macOS. The rest of the app can still run on other platforms, but the voice feature may need to be adapted there.

These steps assume you are already inside the project root folder in your terminal.

If you are using Git:

git clone <your-repository-url>
cd <your-project-folder>

If you downloaded a ZIP:

1. Extract the ZIP file.
2. Open a terminal inside the extracted project folder.

Use Python 3.10 for this project:

python3.10 -m venv .venv

Use the virtual environment interpreter directly:

./.venv/bin/python -m pip install --upgrade pip
./.venv/bin/python -m pip install -r requirements.txt

Move into the frontend folder and install packages:

cd frontend
npm install
cd ..

Arise uses two local servers while developing:

• Flask backend on http://127.0.0.1:5000
• Vite frontend on http://127.0.0.1:5173

You should run them in two separate terminals.

From the project root:

./.venv/bin/python server.py

If the backend starts correctly, it should bind to 127.0.0.1:5000.

From the project root:

cd frontend
npm run dev

If the frontend starts correctly, Vite should print a local URL, usually:

http://127.0.0.1:5173/

Open your browser and go to:

http://127.0.0.1:5173

To stop either server, press Ctrl + C in that terminal.

The Home tab acts as the landing page and overview section for the app.

The Exercise tab lets you track supported workouts in real time.

What you can do there:

• Choose an exercise type
• Start the webcam session
• Use sample workout clips where available
• See your current rep count and movement status
• Hear short voice cues when a rep is completed or when a correction is needed

Supported exercises:

• Push Ups
• Pull Ups
• Squats
• Sit Ups

The Yoga tab mirrors the exercise flow, but for yoga poses.

What you can do there:

• Choose a yoga pose
• View a pose reference image
• Start a live yoga session
• See similarity scoring and pose feedback
• Hear short spoken correction cues

The Meditation tab is a guided breathing section.

What you can do there:

• Start and pause a breathing session
• Reset your meditation timer
• Adjust how long inhale and exhale phases last
• Follow the animated breathing visual
• Hear spoken prompts such as breathing in and breathing out

The Daily Quests tab adds a gamified progress layer to the app. Promoting player v. player competition.

It includes:

• 3 rotating daily quests
• Quest progress tracking
• XP rewards
• Daily streak tracking
• Local leaderboard ranking

The Contact Us page includes a simple contact form. Submissions are stored locally by the backend.

If you want to run just the legacy OpenCV exercise window without the web interface, you can use main.py.

./.venv/bin/python main.py -t squat

Replace squat with one of:

• push-up
• pull-up
• squat
• sit-up

./.venv/bin/python main.py -t squat -vs squat

This uses a bundled sample clip from the Exercise_videos/ folder.

Press q to close the OpenCV window.

Arise stores data locally on your machine.

Important files include:

• data/player_progress.json
  • stores player XP, streaks, daily quest progress, and leaderboard data
• data/contact_messages.json
  • stores messages submitted through the contact form
• data/voice_cache/
  • stores generated voice clips used by the voice coach

The frontend also stores some values in browser local storage, such as:

• player identity
• contact form fallback messages

Because of this, players can leave and return later without losing their local progress on that same machine and browser profile.

Make sure you installed dependencies with the virtual environment interpreter:

./.venv/bin/python -m pip install -r requirements.txt

Do not install with the system Python directly. Use the project virtual environment:

python3.10 -m venv .venv
./.venv/bin/python -m pip install -r requirements.txt

Check that:

• the backend is running on 127.0.0.1:5000
• the frontend is running on 127.0.0.1:5173
• you started the frontend with npm run dev from the frontend/ folder

Things to check:

• your browser has camera permission enabled
• your terminal or browser has permission to access the camera
• no other app is fully locking the webcam

On macOS, you may need to approve camera access the first time.

Things to check:

• your system volume is on
• the Voice Coach toggle is enabled in the UI
• you refreshed the page after restarting the backend
• you are on macOS if you expect the current local voice system to work

That is normal during development. The frontend polls the backend to keep workout status, quest progress, and rewards information up to date.

Pose based tracking is sensitive to:

• camera angle
• Noise (whether it be people or lighting)
• whether your full body is visible
• distance from the camera

For best results:

• stand fully inside the frame
• keep your body clearly visible
• use a stable camera position
• avoid backlighting/ crowded backgrounds

The Flask backend exposes several local endpoints used by the frontend.

Examples include:

• GET /api/health
• GET /api/exercises
• GET /api/status
• POST /api/session
• DELETE /api/session
• GET /api/yoga/poses
• GET /api/yoga/status
• POST /api/yoga/session
• DELETE /api/yoga/session
• POST /api/player/bootstrap
• GET /api/player/<player_id>/rewards
• POST /api/player/<player_id>/meditation
• POST /api/contact
• POST /api/voice-coach

These are intended for the local frontend and local development environment.

• The app currently uses local storage and local files instead of a hosted database.
• The current voice coach implementation is optimized for a local macOS workflow.
• The frontend and backend are designed to work together through the local Vite proxy.
• Python 3.10 is the recommended version for this repository.