MotionScope AI

A production-grade human-activity intelligence platform for wearable sensor data.

MotionScope AI demonstrates the full machine-learning product lifecycle: data generation and validation, signal feature engineering, subject-aware model evaluation, model packaging, API inference, persistent prediction logging, observability, a polished dashboard, containerisation, CI/CD, and deployment blueprints.

This repository is a portfolio and research-engineering demonstration. It is not a medical device and does not provide diagnosis or treatment recommendations.

Why this project is different

Most portfolio projects stop at a notebook. MotionScope AI is designed as a small but complete ML product:

• Raw accelerometer and gyroscope windows are converted into reproducible features.
• Multiple model families are evaluated using participant-aware splits.
• The selected model is packaged with metadata and reference statistics.
• FastAPI serves online predictions and monitoring endpoints.
• SQLAlchemy logs inference metadata to SQLite locally or PostgreSQL in Docker.
• A real-time browser dashboard visualises activities, confidence, daily profiles, drift, and recent predictions.
• Prometheus metrics, Grafana provisioning, CI workflows, Docker, Kubernetes, Terraform, and Airflow examples are included.
• Synthetic data is included so the repository is safe to publish and runs immediately.

Architecture

flowchart LR
    A[Wearable CSV or simulator] --> B[Validation and feature extraction]
    B --> C[Training and evaluation]
    C --> D[Versioned model artifact]
    D --> E[FastAPI inference service]
    E --> F[(SQLite or PostgreSQL)]
    E --> G[Browser dashboard]
    E --> H[Prometheus metrics]
    H --> I[Grafana]
    J[Airflow or CI pipeline] --> C
    K[Docker / Kubernetes / Terraform] --> E

Loading

Fastest local start

Windows PowerShell

cd motionscope-ai
powershell -ExecutionPolicy Bypass -File scripts/bootstrap.ps1

Then open http://localhost:8000.

macOS or Linux

cd motionscope-ai
chmod +x scripts/bootstrap.sh
./scripts/bootstrap.sh

Pip fallback

When uv is unavailable, use scripts/bootstrap-pip.ps1 on Windows or scripts/bootstrap-pip.sh on macOS/Linux.

Docker

docker compose up --build

Then open:

• Dashboard: http://localhost:8000
• API documentation: http://localhost:8000/docs
• Prometheus: http://localhost:9090
• Grafana: http://localhost:3000 (admin / admin for local demo only)
• MinIO console: http://localhost:9001 (motionscope / motionscope-demo)

The API works with SQLite when run directly. Docker Compose uses PostgreSQL.

Core API

Method	Endpoint	Purpose
GET	/healthz	Application and model health
GET	/api/v1/demo/window	Generate a reproducible sensor window
POST	/api/v1/predict	Predict one activity window
POST	/api/v1/predict/batch	Predict multiple windows
GET	/api/v1/model/metrics	Model metadata and test metrics
GET	/api/v1/profile/demo	Generate a 24-hour activity profile
GET	/api/v1/monitoring/drift	Compare recent inference features with training reference data
GET	/api/v1/predictions/recent	Inspect recent prediction records
GET	/metrics	Prometheus metrics

Example:

curl "http://localhost:8000/api/v1/demo/window?activity=walking" -o window.json
curl -X POST "http://localhost:8000/api/v1/predict" \
  -H "Content-Type: application/json" \
  --data @window.json

Model design

The demo generator creates six activities:

• sitting
• standing
• walking
• running
• cycling
• stairs

Each window contains six channels: three-axis acceleration and three-axis angular velocity. The feature pipeline calculates channel statistics, signal magnitude, energy, and jerk. Training compares logistic regression and random forest models using group-aware cross-validation, where simulated participants are not shared between training and validation folds.

The saved artifact contains:

• preprocessing pipeline
• selected classifier
• class labels
• feature names
• evaluation metrics
• reference feature distribution for drift checks
• training timestamp and random seed

Repository map

apps/dashboard/             Browser frontend
src/motionscope/            Production Python package
scripts/                    Bootstrap, training, and GitHub publishing helpers
tests/                      Unit and integration tests
infrastructure/             Docker, Kubernetes, Terraform, Prometheus, Grafana
dags/                       Airflow training DAG example
docs/                       Architecture, model card, data card, security, deployment
sample_data/                Safe synthetic examples
.github/workflows/          CI, security, and Docker workflows

Engineering commands

uv sync --extra dev
uv run python scripts/train_model.py
uv run pytest --cov=motionscope
uv run ruff check .
uv run mypy src/motionscope
uv run uvicorn motionscope.main:app --reload

Portfolio evidence

This repository demonstrates:

• time-series feature engineering
• reproducible model training
• group-aware evaluation and leakage prevention
• API design and schema validation
• relational persistence
• model monitoring and drift analysis
• frontend data visualisation
• Docker and cloud architecture
• automated testing and CI/CD
• responsible handling of sensitive-style data

See docs/PORTFOLIO_PITCH.md for CV bullets and interview talking points.

Next research extensions

1. Replace handcrafted features with a one-dimensional CNN or temporal convolutional network.
2. Add self-supervised masked-signal pretraining.
3. Add public PAMAP2 or UCI HAR adapters.
4. Add posture and activity fragmentation profiles based on 15-second epochs.
5. Add pose-keypoint fusion through a temporal graph model.
6. Register models in MLflow and implement staged promotion.
7. Run a load-test and document cost per 1,000 predictions.

Licence

MIT. Synthetic demo data may be regenerated using the included scripts.