MotionLy

Research-based, gamified tasks to track cognitive and motor changes in people living with neurodegenerative diseases over time.

Built on a modern AI-powered Next.js / TypeScript stack, MotionLy lets clinicians and researchers rapidly design, deploy, and iterate digital tasks while keeping a complete longitudinal record of patient performance.

✅ Status: Early-stage prototype focused on AI-assisted task building, sandboxed execution, and computer‑vision–enhanced motion tasks.

---

Table of Contents

• Features
• Architecture Overview
• Getting Started
• Configuration
• Usage
• Repository Structure
• Clinical / Research Use Considerations
• Contributing
• Security
• License

---

Features

• Research-based gamified tasks: Model patient activities as configurable, repeatable tasks designed around clinical outcome measures (cognition, motor function, adherence).
• Longitudinal tracking: Capture and aggregate per-session performance metrics to visualize symptom evolution over weeks and months.
• AI-assisted task builder: Use AI to clone existing interfaces or generate new React-based tasks from natural language instructions.
• Sandboxed execution: Safely generate and run task UIs in isolated sandboxes (Vercel Sandbox or E2B) without impacting production systems.
• Multi-model AI support: Route generation and refactoring through OpenAI, Anthropic, Google Gemini, or Groq via Vercel AI Gateway.
• Modern UI/UX: Responsive Next.js 15 app with rich motion (Framer Motion), Tailwind CSS, Radix UI primitives, and a focus on accessibility and clarity for patients and clinicians.
• Computer-vision–enhanced tasks (MediaPipe): For movement and motor tasks, MotionLy is designed to integrate with pre-trained computer-vision pipelines such as MediaPipe for pose, hand, and gesture tracking. These models are trained using supervised machine-learning techniques on large annotated video datasets, and MotionLy consumes their outputs (e.g., joint positions, movement smoothness, tremor amplitude) to derive clinically meaningful task metrics—without retraining the underlying models in this repository.

Suggested images (to be replaced with real assets later):

• docs/images/dashboard-overview.png – main clinician dashboard showing patient timelines.
• docs/images/task-session-view.png – in-depth view of a single gamified task session.
• docs/images/protocol-builder.png – configuration screen for creating research protocols.

---

Architecture Overview

At a high level, MotionLy combines an AI code-generation engine, a sandboxed runtime, and a task-tracking UX layer:

flowchart LR
    Patient[Patient / Participant] -->|plays tasks| MotionLyUI[MotionLy Web App]
    Clinician[Clinician / Researcher] -->|designs protocols & reviews data| MotionLyUI

    MotionLyUI -->|AI prompts & task specs| AIEngine[AI Generation Layer]
    AIEngine -->|React code & layouts| Sandbox[Sandbox Runtime]
    Sandbox -->|running task UI| Patient

    MotionLyUI -->|event streams & scores| DataStore[(Longitudinal Data Store)]
    DataStore --> Analytics[Analytics & Visualization]
    Analytics --> Clinician

Loading

See docs/architecture.md for a deeper technical breakdown of the Next.js app, sandbox orchestration, and AI integration.

---

Getting Started

Prerequisites

• Node.js: v20 LTS (or the minimum supported by Next.js 15.4.x).
• Package manager: pnpm (recommended), npm, or yarn.
• Git and GitHub CLI (gh) if you plan to contribute or create your own fork/template.

1. Clone the repository

git clone https://github.com/<your-username>/MotionLy.git
cd MotionLy

2. Install dependencies

Using pnpm (recommended):

pnpm install

Or with npm:

npm install

3. Configure environment variables

Copy the example environment file and fill in your keys:

cp .env.example .env.local

The most important variables are:

# Web scraping / site cloning
FIRECRAWL_API_KEY=your_firecrawl_api_key

# Sandbox provider (choose ONE)
SANDBOX_PROVIDER=vercel           # or "e2b"
VERCEL_OIDC_TOKEN=auto_generated_by_vercel_env_pull
# or:
# VERCEL_TEAM_ID=...
# VERCEL_PROJECT_ID=...
# VERCEL_TOKEN=...

# AI gateway (recommended)
AI_GATEWAY_API_KEY=your_ai_gateway_api_key

# Fallback individual providers
OPENAI_API_KEY=your_openai_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key
GEMINI_API_KEY=your_gemini_api_key
GROQ_API_KEY=your_groq_api_key

# Optional fast-apply engine
MORPH_API_KEY=your_fast_apply_key

4. Run the development server

pnpm dev
# or
npm run dev

Then open http://localhost:3000 in your browser.

---

Usage

MotionLy currently exposes a powerful AI-powered builder UI that you can use to design and run experimental tasks.

1. Clone or design a task UI

1. Launch the app at http://localhost:3000.
2. On the home screen:
   • Paste a URL of an existing task/interface you want to clone or extend, or
   • Enter a search term describing the interface you want to build (e.g., "stroop-like reaction-time game").
3. Choose a visual style and target AI model.
4. Click "Scrape Site" or "Search" and follow the prompts.

Suggested image: docs/images/home-screen.png (screenshot of the home page with URL/search input).

2. Customize the experimental protocol

Once you’re in the builder screen:

• Use the AI chat to describe task rules, scoring, and timing (e.g., "3 blocks of 20 trials each, with increasing difficulty").
• Let the AI generate React components and supporting code inside an isolated sandbox.
• Preview the outcome in the embedded iframe.

sequenceDiagram
    participant R as Researcher
    participant UI as MotionLy Builder UI
    participant AI as AI Engine
    participant SB as Sandbox Runtime

    R->>UI: Describe new gamified task
    UI->>AI: Send prompt + current sandbox context
    AI-->>UI: Stream React/TypeScript code changes
    UI->>SB: Apply code & restart sandbox
    SB-->>R: Render updated task for review

Loading

3. Capture and review patient sessions (conceptual)

The intended workflow for clinical use is:

1. Assign a curated set of tasks to a patient.
2. Let the patient complete tasks daily or weekly via the MotionLy front-end.
3. Capture trial-level metrics (reaction times, errors, completion rates).
4. Visualize longitudinal trends in a clinician dashboard.

Note: The current open-source prototype focuses on the builder and sandbox pieces. A production deployment for real patient data must add a secure backend and storage layer (see docs/architecture.md).

---

Repository Structure

High-level structure of the codebase:

.
├─ app/                      # Next.js 15 app router pages
│  ├─ page.tsx               # Landing page with URL/search-based entry
│  ├─ generation/            # AI builder & sandbox UI
│  └─ builder/               # Additional builder/preview flows
├─ components/               # Shared and feature-specific React components
├─ config/
│  └─ app.config.ts          # Centralized runtime configuration
├─ lib/                      # Utilities, AI/sandbox helpers, icons, etc.
├─ styles/                   # Tailwind + custom CSS design system
├─ types/                    # Shared TypeScript types
├─ docs/
│  ├─ architecture.md        # High-level technical architecture
│  └─ developer-guide.md     # Developer/API usage guide
├─ .env.example              # Example environment configuration
├─ .gitignore
├─ eslint.config.mjs
├─ next.config.ts
├─ package.json
└─ tsconfig.json

For more details on modules, data flow, and sandbox orchestration, see:

• docs/architecture.md
• docs/developer-guide.md

---

Clinical / Research Use Considerations

MotionLy is not a medical device and is not cleared or approved for diagnostic use.

• Any deployment for real patients must undergo institutional review and comply with applicable regulations (e.g., HIPAA, GDPR, local privacy laws).
• You are responsible for obtaining ethics approval, informed consent, and data-protection safeguards in your jurisdiction.
• This repository is best used as a prototype and experimentation environment for designing digital tasks and pilots.

---

Contributing

Contributions are welcome!

• Read the full guidelines in CONTRIBUTING.md.
• Open an issue for bugs, feature requests, or documentation improvements.
• For code changes, please:
  • Fork the repo and create a feature branch.
  • Add or update tests where appropriate.
  • Run linting and tests locally before opening a pull request.

---

Security

Please do not report security issues publicly in GitHub issues.

• See SECURITY.md for how to report vulnerabilities responsibly and privately.
• Avoid committing real patient data or secrets (API keys, .env files, etc.) to the repository.

---

License

This project is licensed under the MIT License.
See LICENSE for full details.