kinemotion 0.34.0__tar.gz → 0.35.1__tar.gz

kinemotion-0.35.1/.basic-memory/authentication/supabase-google-oauth-setup-guide.md

@@ -0,0 +1,118 @@
+---
+title: Supabase Google OAuth Setup Guide
+type: note
+permalink: authentication/supabase-google-oauth-setup-guide-1
+---
+
+# Supabase Google OAuth Setup Guide
+
+## Overview
+This guide explains how to enable Google OAuth authentication in Supabase, allowing users to sign in with their Google accounts.
+
+## Step 1: Configure Google Cloud Console
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project or select an existing one
+3. Navigate to **APIs & Services** → **Credentials**
+4. Click **Create Credentials** → **OAuth client ID**
+5. If prompted, configure the OAuth consent screen:
+   - Choose **External** (unless you have a Google Workspace)
+   - Fill in app name, support email, developer contact
+   - Add scopes: `email`, `profile`, `openid`
+   - Add test users if needed (for testing before verification)
+6. Create OAuth client:
+   - **Application type**: Web application
+   - **Name**: Kinemotion (or your app name)
+   - **Authorized JavaScript origins**:
+     - `https://kinemotion.vercel.app` (production)
+     - `http://localhost:5173` (local development)
+   - **Authorized redirect URIs**:
+     - Get from Supabase Dashboard → Authentication → Providers → Google
+     - Format: `https://<project-id>.supabase.co/auth/v1/callback`
+     - For local dev: `http://localhost:3000/auth/v1/callback` (if using Supabase local)
+7. Click **Create** and save:
+   - **Client ID** (looks like: `123456789-abc...googleusercontent.com`)
+   - **Client Secret** (looks like: `GOCSPX-abc...`)
+
+## Step 2: Configure Supabase Dashboard
+
+1. Go to your Supabase project dashboard
+2. Navigate to **Authentication** → **Providers**
+3. Find **Google** in the list and click to configure
+4. Enable the provider
+5. Enter:
+   - **Client ID**: From Google Cloud Console
+   - **Client Secret**: From Google Cloud Console
+6. Click **Save**
+
+**Important**: The redirect URI in Google Cloud Console must match:
+- Production: `https://<your-project-id>.supabase.co/auth/v1/callback`
+- Local dev: `http://localhost:3000/auth/v1/callback` (if using Supabase local)
+
+## Step 3: Update Frontend Code
+
+### Add Google Sign-In Button
+
+Update `frontend/src/components/Auth.tsx` to include a Google sign-in button.
+
+### Update useAuth Hook
+
+Add `signInWithGoogle()` method to `frontend/src/hooks/useAuth.ts`:
+
+```typescript
+signInWithGoogle: () => Promise<void>
+```
+
+Implementation uses `supabase.auth.signInWithOAuth({ provider: 'google' })`.
+
+## Step 4: Update Redirect URLs
+
+Ensure your Supabase project has the correct redirect URLs configured:
+
+1. Go to **Authentication** → **URL Configuration**
+2. **Site URL**: `https://kinemotion.vercel.app`
+3. **Redirect URLs**:
+   - `https://kinemotion.vercel.app/**`
+   - `http://localhost:5173/**`
+
+## Testing
+
+1. Start your frontend: `cd frontend && yarn dev`
+2. Click "Sign in with Google"
+3. You should be redirected to Google's OAuth consent screen
+4. After authorization, you'll be redirected back to your app
+5. Check Supabase Dashboard → Authentication → Users to see the new user
+
+## Troubleshooting
+
+**Error: "redirect_uri_mismatch"**
+- Ensure the redirect URI in Google Cloud Console exactly matches Supabase callback URL
+- Check for trailing slashes or protocol mismatches (http vs https)
+
+**Error: "invalid_client"**
+- Verify Client ID and Client Secret are correct in Supabase Dashboard
+- Ensure Google OAuth consent screen is configured
+
+**User not appearing in Supabase**
+- Check browser console for errors
+- Verify redirect URLs are configured correctly
+- Check Supabase logs in Dashboard → Logs → Auth Logs
+
+## Security Notes
+
+- Never commit Client Secret to git
+- Use environment variables for sensitive values
+- Google OAuth tokens are handled by Supabase automatically
+- JWT tokens from Supabase work the same way for Google-authenticated users
+
+## Free Tier Limits
+
+- Google OAuth: No additional cost
+- Supabase Auth: 50,000 MAUs/month (free tier)
+- Each Google sign-in counts as one MAU
+
+## References
+
+- [Supabase Google OAuth Docs](https://supabase.com/docs/guides/auth/social-login/auth-google)
+- [Google Cloud Console](https://console.cloud.google.com/)
+- [Supabase Dashboard](https://supabase.com/dashboard)

kinemotion-0.35.1/.basic-memory/codebase/validation-architecture-visual-hierarchy-after-refactoring.md

@@ -0,0 +1,202 @@
+---
+title: Validation Architecture - Visual Hierarchy After Refactoring
+type: note
+permalink: codebase/validation-architecture-visual-hierarchy-after-refactoring-1
+---
+
+# Validation Architecture - After Refactoring
+
+## Class Hierarchy
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│           core/validation.py (SHARED BASE CLASSES)          │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌─ ValidationSeverity (enum)                              │
+│  │    └─ ERROR, WARNING, INFO                              │
+│  │                                                          │
+│  ├─ ValidationIssue (dataclass)                            │
+│  │    └─ severity, metric, message, value, bounds          │
+│  │                                                          │
+│  ├─ AthleteProfile (enum)                                 │
+│  │    └─ ELDERLY, UNTRAINED, RECREATIONAL, TRAINED, ELITE │
+│  │                                                          │
+│  ├─ MetricBounds (dataclass)                              │
+│  │    ├─ absolute/practical/recreational/elite ranges     │
+│  │    ├─ contains(value, profile) → bool                  │
+│  │    └─ is_physically_possible(value) → bool             │
+│  │                                                          │
+│  ├─ ValidationResult (dataclass + ABC)                    │
+│  │    ├─ issues, status, athlete_profile                 │
+│  │    ├─ add_error(metric, message, value, bounds)        │
+│  │    ├─ add_warning(metric, message, value, bounds)      │
+│  │    ├─ add_info(metric, message, value)                 │
+│  │    ├─ finalize_status() → determines PASS/WARNING/FAIL │
+│  │    └─ to_dict() → abstract (subclass implements)       │
+│  │                                                          │
+│  └─ MetricsValidator (ABC)                               │
+│       ├─ __init__(assumed_profile)                        │
+│       └─ validate(metrics) → abstract                     │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+              ▲                              ▲
+              │                              │
+    ┌─────────┴────────┐            ┌───────┴────────┐
+    │                  │            │                │
+
+┌────────────────────────┐    ┌──────────────────────────┐
+│   cmj/ (CMJ-specific)  │    │  dropjump/ (DJ-specific) │
+├────────────────────────┤    ├──────────────────────────┤
+│                        │    │                          │
+│ metrics_validator.py:  │    │ metrics_validator.py:    │
+│ ┌────────────────────┐ │    │ ┌──────────────────────┐ │
+│ │ CMJMetricsValidator│ │    │ │DropJumpMetricsVali- │ │
+│ │ (extends Metrics-  │ │    │ │ dator (extends       │ │
+│ │  Validator)        │ │    │ │ MetricsValidator)    │ │
+│ │                    │ │    │ │                      │ │
+│ │ CMJValidationResult│ │    │ │ DropJumpValidation-  │ │
+│ │ (extends Validation│ │    │ │ Result (extends      │ │
+│ │  Result)           │ │    │ │ ValidationResult)    │ │
+│ └────────────────────┘ │    │ └──────────────────────┘ │
+│                        │    │                          │
+│ validation_bounds.py:  │    │ validation_bounds.py:   │
+│ ┌────────────────────┐ │    │ ┌──────────────────────┐ │
+│ │ CMJBounds          │ │    │ │ DropJumpBounds       │ │
+│ │  └─ FLIGHT_TIME    │ │    │ │  └─ CONTACT_TIME     │ │
+│ │  └─ JUMP_HEIGHT    │ │    │ │  └─ FLIGHT_TIME      │ │
+│ │  └─ ...            │ │    │ │  └─ JUMP_HEIGHT      │ │
+│ │                    │ │    │ │  └─ RSI              │ │
+│ │ TripleExtension-   │ │    │ │                      │ │
+│ │ Bounds (hip/knee/  │ │    │ │ estimate_athlete_    │ │
+│ │  ankle angles)     │ │    │ │ profile()            │ │
+│ │                    │ │    │ │                      │ │
+│ │ RSIBounds (CMJ-    │ │    │ └──────────────────────┘ │
+│ │ specific RSI ranges)│ │    │                          │
+│ │                    │ │    │                          │
+│ │ MetricConsistency  │ │    │                          │
+│ │ (cross-validation  │ │    │                          │
+│ │  tolerances)       │ │    │                          │
+│ │                    │ │    │                          │
+│ │ estimate_athlete_  │ │    │                          │
+│ │ profile()          │ │    │                          │
+│ └────────────────────┘ │    │                          │
+│                        │    │                          │
+└────────────────────────┘    └──────────────────────────┘
+```
+
+## Data Flow Example
+
+### CMJ Validation Flow
+```
+metrics_dict (CMJ data)
+    │
+    ▼
+api.py or test imports CMJMetricsValidator()
+    │
+    ▼
+validator.validate(metrics_dict)
+    │
+    ├─ Estimate profile from jump_height
+    │
+    ├─ Check individual bounds (flight_time, jump_height, etc.)
+    │   └─ Each uses MetricBounds.contains(value, profile)
+    │
+    ├─ Cross-validation checks
+    │   └─ Uses MetricConsistency tolerances
+    │
+    └─ Finalize status
+        └─ Calls ValidationResult.finalize_status()
+    │
+    ▼
+CMJValidationResult
+    ├─ status: "PASS" / "PASS_WITH_WARNINGS" / "FAIL"
+    ├─ issues: list[ValidationIssue]
+    ├─ athlete_profile: AthleteProfile
+    ├─ rsi: float
+    ├─ height_flight_time_consistency: float
+    └─ [CMJ-specific fields]
+    │
+    ▼
+result.to_dict() → JSON-serializable dictionary
+```
+
+## Import Structure After Refactoring
+
+### Old (Duplicated)
+```python
+# api.py
+from .core.cmj_metrics_validator import CMJMetricsValidator
+from .core.dropjump_metrics_validator import DropJumpMetricsValidator
+
+# tests/test_cmj_physiological_bounds.py
+from kinemotion.core.cmj_metrics_validator import CMJMetricsValidator
+from kinemotion.core.cmj_validation_bounds import CMJBounds, AthleteProfile
+```
+
+### New (Refactored)
+```python
+# api.py
+from .cmj.metrics_validator import CMJMetricsValidator
+from .dropjump.metrics_validator import DropJumpMetricsValidator
+
+# tests/test_cmj_physiological_bounds.py
+from kinemotion.cmj.metrics_validator import CMJMetricsValidator
+from kinemotion.cmj.validation_bounds import CMJBounds
+from kinemotion.core.validation import AthleteProfile, ValidationSeverity
+```
+
+## Key Improvements
+
+| Aspect | Before | After |
+|--------|--------|-------|
+| Shared code location | core/ with jump prefixes | core/validation.py (no prefixes) |
+| CMJ validator location | core/cmj_metrics_validator.py | cmj/metrics_validator.py |
+| Drop jump validator location | core/dropjump_metrics_validator.py | dropjump/metrics_validator.py |
+| Code duplication | 137 lines (7.7%) | ~10 lines (< 1%) |
+| Base class definition | None (duplicated) | core/validation.py (single source) |
+| AthleteProfile enum copies | 2 (CMJ + drop jump) | 1 (shared in core/validation.py) |
+| MetricBounds class copies | 2 (CMJ + drop jump) | 1 (shared in core/validation.py) |
+| Validator coupling | Tight (no inheritance) | Loose (via inheritance) |
+| Extensibility | Requires copying all code | Extend base classes |
+| Maintenance effort | 2x (update both files) | 1x (fix base class) |
+
+## Co-location Benefits
+
+All validation code now co-located with its jump type:
+```
+cmj/
+  ├── analysis.py              ← CMJ analysis algorithms
+  ├── kinematics.py            ← CMJ metrics calculation
+  ├── metrics_validator.py     ← ✨ NEW: CMJ validation
+  ├── validation_bounds.py     ← ✨ NEW: CMJ bounds
+  └── joint_angles.py          ← CMJ-specific angles
+
+dropjump/
+  ├── analysis.py              ← Drop jump algorithms
+  ├── kinematics.py            ← Drop jump metrics
+  ├── metrics_validator.py     ← ✨ NEW: Drop jump validation
+  └── validation_bounds.py     ← ✨ NEW: Drop jump bounds
+```
+
+This makes it easier to:
+1. **Understand the jump type** - All related code in one folder
+2. **Add new jump types** - Copy the pattern from an existing type
+3. **Modify jump-specific logic** - Find everything you need in one place
+4. **Maintain shared infrastructure** - core/validation.py is the single source
+
+## Next Jump Type Example
+
+To add a new jump type (e.g., Standing Jump):
+```
+1. Create standingjump/ folder
+2. Copy structure from cmj/ or dropjump/
+3. Create standingjump/metrics_validator.py
+   └─ Extend MetricsValidator from core/validation.py
+4. Create standingjump/validation_bounds.py
+   └─ Define StandingJumpBounds, estimate_athlete_profile()
+5. Update api.py imports
+6. All base classes already available in core/validation.py ✅
+```
+
+No more code duplication needed!

kinemotion-0.35.1/.basic-memory/codebase/validation-code-duplication-evidence.md

@@ -0,0 +1,258 @@
+---
+title: Validation Code Duplication Evidence
+type: note
+permalink: codebase/validation-code-duplication-evidence-1
+---
+
+# Validation Code Duplication Evidence
+
+## Side-by-Side Comparison of Duplicated Code
+
+### 1. ValidationSeverity Enum (100% Identical)
+
+**CMJ Validator (lines 24-30):**
+```python
+class ValidationSeverity(Enum):
+    """Severity level for validation issues."""
+    ERROR = "ERROR"
+    WARNING = "WARNING"
+    INFO = "INFO"
+```
+
+**Drop Jump Validator (lines 20-26):**
+```python
+class ValidationSeverity(Enum):
+    """Severity level for validation issues."""
+    ERROR = "ERROR"
+    WARNING = "WARNING"
+    INFO = "INFO"
+```
+
+**Duplication:** 7 lines, 100% identical
+
+---
+
+### 2. ValidationIssue Dataclass (100% Identical)
+
+**CMJ Validator (lines 32-41):**
+```python
+@dataclass
+class ValidationIssue:
+    """Single validation issue."""
+    severity: ValidationSeverity
+    metric: str
+    message: str
+    value: float | None = None
+    bounds: tuple[float, float] | None = None
+```
+
+**Drop Jump Validator (lines 28-37):**
+```python
+@dataclass
+class ValidationIssue:
+    """Single validation issue."""
+    severity: ValidationSeverity
+    metric: str
+    message: str
+    value: float | None = None
+    bounds: tuple[float, float] | None = None
+```
+
+**Duplication:** 10 lines, 100% identical
+
+---
+
+### 3. ValidationResult Methods (100% Identical)
+
+**add_error() - CMJ (lines 56-72) vs Drop Jump (lines 50-66):**
+```python
+def add_error(
+    self,
+    metric: str,
+    message: str,
+    value: float | None = None,
+    bounds: tuple[float, float] | None = None,
+) -> None:
+    """Add error-level issue."""
+    self.issues.append(
+        ValidationIssue(
+            severity=ValidationSeverity.ERROR,
+            metric=metric,
+            message=message,
+            value=value,
+            bounds=bounds,
+        )
+    )
+```
+
+**Duplication:** 17 lines × 3 methods (add_error, add_warning, add_info) = 51 lines
+
+---
+
+**finalize_status() - CMJ (lines 108-122) vs Drop Jump (lines 102-116):**
+```python
+def finalize_status(self) -> None:
+    """Determine final pass/fail status based on issues."""
+    has_errors = any(
+        issue.severity == ValidationSeverity.ERROR for issue in self.issues
+    )
+    has_warnings = any(
+        issue.severity == ValidationSeverity.WARNING for issue in self.issues
+    )
+
+    if has_errors:
+        self.status = "FAIL"
+    elif has_warnings:
+        self.status = "PASS_WITH_WARNINGS"
+    else:
+        self.status = "PASS"
+```
+
+**Duplication:** 15 lines, 100% identical
+
+---
+
+### 4. AthleteProfile Enum (100% Identical)
+
+**CMJ Bounds (lines 22-30):**
+```python
+class AthleteProfile(Enum):
+    """Athlete performance categories for metric bounds."""
+    ELDERLY = "elderly"
+    UNTRAINED = "untrained"
+    RECREATIONAL = "recreational"
+    TRAINED = "trained"
+    ELITE = "elite"
+```
+
+**Drop Jump Bounds (lines 22-30):**
+```python
+class AthleteProfile(Enum):
+    """Athlete performance categories for metric bounds."""
+    ELDERLY = "elderly"
+    UNTRAINED = "untrained"
+    RECREATIONAL = "recreational"
+    TRAINED = "trained"
+    ELITE = "elite"
+```
+
+**Duplication:** 9 lines, 100% identical
+
+---
+
+### 5. MetricBounds Dataclass (100% Identical)
+
+**CMJ Bounds (lines 32-76):**
+```python
+@dataclass
+class MetricBounds:
+    """Physiological bounds for a single metric."""
+    absolute_min: float
+    practical_min: float
+    recreational_min: float
+    recreational_max: float
+    elite_min: float
+    elite_max: float
+    absolute_max: float
+    unit: str
+
+    def contains(self, value: float, profile: AthleteProfile) -> bool:
+        """Check if value is within bounds for athlete profile."""
+        if profile == AthleteProfile.ELDERLY:
+            return self.practical_min <= value <= self.recreational_max
+        elif profile == AthleteProfile.UNTRAINED:
+            return self.practical_min <= value <= self.recreational_max
+        elif profile == AthleteProfile.RECREATIONAL:
+            return self.recreational_min <= value <= self.recreational_max
+        elif profile == AthleteProfile.TRAINED:
+            trained_min = (self.recreational_min + self.elite_min) / 2
+            trained_max = (self.recreational_max + self.elite_max) / 2
+            return trained_min <= value <= trained_max
+        elif profile == AthleteProfile.ELITE:
+            return self.elite_min <= value <= self.elite_max
+        return False
+
+    def is_physically_possible(self, value: float) -> bool:
+        """Check if value is within absolute physiological limits."""
+        return self.absolute_min <= value <= self.absolute_max
+```
+
+**Drop Jump Bounds (lines 32-76):**
+```python
+@dataclass
+class MetricBounds:
+    """Physiological bounds for a single metric."""
+    absolute_min: float
+    practical_min: float
+    recreational_min: float
+    recreational_max: float
+    elite_min: float
+    elite_max: float
+    absolute_max: float
+    unit: str
+
+    def contains(self, value: float, profile: AthleteProfile) -> bool:
+        """Check if value is within bounds for athlete profile."""
+        if profile == AthleteProfile.ELDERLY:
+            return self.practical_min <= value <= self.recreational_max
+        elif profile == AthleteProfile.UNTRAINED:
+            return self.practical_min <= value <= self.recreational_max
+        elif profile == AthleteProfile.RECREATIONAL:
+            return self.recreational_min <= value <= self.recreational_max
+        elif profile == AthleteProfile.TRAINED:
+            trained_min = (self.recreational_min + self.elite_min) / 2
+            trained_max = (self.recreational_max + self.elite_max) / 2
+            return trained_min <= value <= trained_max
+        elif profile == AthleteProfile.ELITE:
+            return self.elite_min <= value <= self.elite_max
+        return False
+
+    def is_physically_possible(self, value: float) -> bool:
+        """Check if value is within absolute physiological limits."""
+        return self.absolute_min <= value <= self.absolute_max
+```
+
+**Duplication:** 45 lines, 100% identical
+
+---
+
+## Duplication Summary
+
+| Component | Lines | Duplication % | Status |
+|-----------|-------|---------------|--------|
+| ValidationSeverity | 7 | 100% | \u274c Duplicate |
+| ValidationIssue | 10 | 100% | \u274c Duplicate |
+| ValidationResult.add_error() | 17 | 100% | \u274c Duplicate |
+| ValidationResult.add_warning() | 17 | 100% | \u274c Duplicate |
+| ValidationResult.add_info() | 17 | 100% | \u274c Duplicate |
+| ValidationResult.finalize_status() | 15 | 100% | \u274c Duplicate |
+| AthleteProfile | 9 | 100% | \u274c Duplicate |
+| MetricBounds (full class) | 45 | 100% | \u274c Duplicate |
+
+**Total Duplication:** ~137 lines of identical code across 4 files
+
+**File sizes:**
+- cmj_metrics_validator.py: 831 lines
+- cmj_validation_bounds.py: 395 lines
+- dropjump_metrics_validator.py: 347 lines
+- dropjump_validation_bounds.py: 197 lines
+- **Combined:** 1,770 lines
+
+**Duplication percentage:** 137 / 1770 = **7.7% duplication**
+
+**Project standard:** < 3%
+**Status:** \u26a0\ufe0f **Violates quality standard by 2.6x**
+
+## Impact
+
+1. **Maintenance burden:** Bug fixes must be applied twice
+2. **Inconsistency risk:** Changes to one validator may not propagate to the other
+3. **Extensibility:** Adding new jump types requires copying all base code again
+4. **Code smell:** Indicates architectural debt that should be refactored
+
+## Resolution Path
+
+Extract shared abstractions to `core/validation.py` as base classes, then:
+- CMJMetricsValidator extends base in `cmj/metrics_validator.py`
+- DropJumpMetricsValidator extends base in `dropjump/metrics_validator.py`
+- Estimated duplication after refactor: < 1% (only jump-specific validation logic remains)