diff --git a/.clinerules/CoreDevelopmentRules.md b/.clinerules/CoreDevelopmentRules.md
new file mode 100644
index 0000000..531d24b
--- /dev/null
+++ b/.clinerules/CoreDevelopmentRules.md
@@ -0,0 +1,381 @@
+# Development Tooling and Workflow Rules
+
+This document defines the mandatory development workflow, tooling requirements, and compliance rules for all projects. These rules ensure consistent development practices, reproducible builds, and standardized deployment procedures.
+
+## Core Development Principles
+
+### Container-First Development
+
+- **FORBIDDEN**: NEVER update or edit the .env file
+
+**Rule 1: Always Use Containers**
+- **MANDATORY**: Launch all project artifacts as containers, never as local processes
+- All applications must run in containerized environments
+- No direct execution of local binaries or scripts outside of containers
+
+**Rule 2: Docker Command**
+- **MANDATORY**: Use `docker compose` (new syntax) for all container orchestration
+- **FORBIDDEN**: Never use the deprecated `docker-compose` command (old syntax with hyphen)
+- All compose operations must use the modern Docker CLI integrated command
+
+**Rule 3: Docker Compose Version Attribute**
+- **FORBIDDEN**: Never use the obsolete `version` attribute in Docker Compose files
+- **MANDATORY**: Use modern Docker Compose files without version specification
+- The `version` attribute has been deprecated and is no longer required in current Docker Compose specifications
+
+## Package Management
+
+### Python Development
+
+**Rule 4: Python Package Management with Astral UV**
+- **MANDATORY**: Manage all Python packages using Astral UV with `pyproject.toml`
+- **MANDATORY**: Use `uv sync` for dependency synchronization
+- **FORBIDDEN**: Never use `pip` for package installation or management
+- All Python dependencies must be declared in `pyproject.toml` and managed through UV
+- **Legacy Support**: Poetry support maintained for compatibility where existing
+
+**Python Development Best Practices**:
+- Use Astral UV for dependency management
+- Follow PEP 8 coding standards
+- Use type hints where applicable
+- Structure modules by feature/domain
+
+### Frontend Development
+
+**Rule 5: React Package Management**
+- **MANDATORY**: For React projects, use `pnpm` as the package manager
+- **FORBIDDEN**: Never use `npm` for React project dependency management
+- All React dependencies must be managed through pnpm
+- **Lock File**: Use `pnpm-lock.yaml` for dependency locking
+
+**Rule 6: Pre-Build Code Quality Validation**
+
+**Python Projects**:
+- **MANDATORY**: Before building a Python container, run the following commands and fix all issues:
+ ```bash
+ ruff format .
+ ruff check --fix .
+ ```
+- **MANDATORY**: All ruff formatting and linting errors must be resolved prior to Docker build process
+- Code must pass both formatting and linting checks before containerization
+- Use ruff for consistent code formatting and quality enforcement
+
+**Frontend Projects**:
+- **MANDATORY**: Before building a React/frontend container, run `pnpm lint` and fix any errors
+- **MANDATORY**: Run `pnpm lint --fix` to automatically fix linting issues where possible
+- Code quality must be verified before containerization
+- All linting errors must be resolved prior to Docker build process
+- **MANDATORY**: Run TypeScript type checking before building containers
+
+**React Development Best Practices**:
+- **MANDATORY**: Use TypeScript for all React components and logic
+- **MANDATORY**: Use Tailwind CSS for styling
+- **MANDATORY**: Use Vite as the build tool
+- **MANDATORY**: Follow strict TypeScript configuration
+- **MANDATORY**: Use functional components with hooks
+- **MANDATORY**: Implement proper component prop typing
+- Use modern React patterns (hooks, context, suspense)
+- Implement proper error boundaries
+- Use consistent naming conventions (PascalCase for components, camelCase for functions)
+- Organize imports: React imports first, then third-party, then local imports
+
+
+## Dockerfile Authoring Rules
+
+**Rule 7: Dockerfile = Build Only**
+- **MANDATORY**: The Dockerfile must **only** describe how to **build** the image in the most efficient and smallest way possible.
+- **FORBIDDEN**: Any instruction about **how to run** the container (commands, arguments, environment, ports, volumes, networks, restart policies, replicas, resource limits, etc.) must **only** appear in Docker Compose files.
+- **MANDATORY**: Prefer **multi‑stage builds** to ensure the final image is minimal.
+- **MANDATORY**: Use the **smallest still-supported base image** that satisfies the project's requirements (e.g., `python:3.12-slim`, `alpine`, `distroless`, `ubi-micro`, etc.), and keep it **recent** to receive security patches.
+- **MANDATORY**: Remove all build-time tools, caches and temporary files in the final stage.
+- **MANDATORY**: Provide a proper `.dockerignore` to keep the build context minimal.
+- **RECOMMENDED**: Use BuildKit features such as `--mount=type=cache` to cache package managers (uv/pip/pnpm) during the build.
+- **RECOMMENDED**: Pin dependency versions where sensible to ensure reproducible builds.
+- **RECOMMENDED**: Run as a non-root user in the final stage when possible.
+- **OPTIONAL**: `ENTRYPOINT`/`CMD` can be minimal or omitted; the **effective runtime command must be set in Compose**.
+
+**Rule 8: Multi-stage Dockerfile Syntax**
+- **MANDATORY**: When writing multi-stage Dockerfiles, always use `FROM` and `AS` keywords in **UPPERCASE**
+- **MANDATORY**: Stage names should be descriptive and follow consistent naming conventions
+- **Example**: `FROM node:18-alpine AS builder` (not `from node:18-alpine as builder`)
+- This ensures consistency and follows Docker best practices for multi-stage builds
+
+## Linting Dockerfiles
+
+**Rule 9: Dockerfiles must pass `hadolint`**
+- **MANDATORY**: All Dockerfiles must be linted with **hadolint** locally
+- **MANDATORY**: Any rule suppression must be:
+ - Declared in a **project-wide `.hadolint.yaml`** with a **short rationale**, **or**
+ - Inline via `# hadolint ignore=DLXXXX` **with a reference to the issue/PR explaining why**.
+- **RECOMMENDED**: Keep the exception list short and reviewed periodically.
+
+### Sample `.hadolint.yaml`
+```yaml
+failure-threshold: warning # pipeline fails on warnings and above
+ignored:
+ # Keep this list short, each with a comment explaining *why* it is safe to ignore.
+ # - DL3008 # Example: apt-get install without --no-install-recommends (document justification)
+```
+
+
+## Container Development Workflow
+
+### Frontend Container Deployment
+
+**Rule 10: Frontend Container Deployment**
+- **MANDATORY**: Launch frontend applications by rebuilding their Docker image and launching with `docker compose`
+- **FORBIDDEN**: Never use `pnpm run` or any local package manager commands to start frontend applications
+- Frontend must always be containerized and orchestrated through Docker Compose
+
+**Rule 11: Frontend Container Build and Test Process**
+- **MANDATORY**: To build and test a new version of a frontend container always use:
+ ```bash
+ docker compose down FRONTENDNAME
+ docker compose up -d FRONTENDNAME --build
+ ```
+- This ensures clean shutdown of existing containers before rebuilding
+- Forces fresh build of the frontend container image
+- Launches in detached mode for testing
+
+### Development Workflow Commands
+
+**Backend Development**:
+```bash
+cd docker
+docker compose down backend
+docker compose up -d backend --build
+```
+
+**Frontend Development**:
+```bash
+cd docker
+docker compose down frontend
+docker compose up -d frontend --build
+```
+
+**Full Stack Development**:
+```bash
+cd docker
+docker compose down
+docker compose up -d --build
+```
+
+**Development Mode Testing**:
+```bash
+# For backend testing
+docker compose exec backend python -m src.main --help
+
+# For frontend testing
+docker compose logs frontend
+```
+
+## Environment Configuration
+
+### Centralized Environment Management
+
+**Rule 12: Root-Level Environment Variables Only**
+- **MANDATORY**: All environment variables must be stored in the root `.env` file only
+- **FORBIDDEN**: Environment variables in subdirectories (e.g., `frontend/.env`, `src/.env`)
+- **MANDATORY**: Use a single `.env.example` template at the root level
+- Both backend and frontend applications must read from the root `.env` file
+- Docker Compose should mount the root `.env` file to all containers
+
+**Environment Variable Naming Conventions**:
+- **Backend variables**: Use standard naming (e.g., `API_KEY`, `DATABASE_HOST`)
+- **Frontend variables**: Prefix with `VITE_` for Vite projects (e.g., `VITE_API_URL`)
+- **Docker variables**: Use `COMPOSE_` prefix for Docker Compose settings
+- **Shared variables**: Can be used by both backend and frontend (e.g., `APP_ENV`)
+
+## Database Integration
+
+**Rule 13: Database Configuration**
+- Place database initialization scripts in `/docker/init-scripts/`
+- Use environment variables for database configuration
+- Implement proper connection pooling
+- Follow database naming conventions
+- Mount database data as Docker volumes for persistence
+
+## Testing and Quality Assurance
+
+**Rule 14: Testing Requirements**
+- **MANDATORY**: Run all tests in containerized environments
+- Follow testing framework conventions (pytest for Python, Jest for React)
+- Include unit, integration, and end-to-end tests
+- Test data should be minimal and focused
+- Separate test types into different directories
+
+**Testing Commands**:
+```bash
+# Python tests
+docker compose exec backend python -m pytest tests/
+
+# Frontend tests
+docker compose exec frontend pnpm test
+
+# End-to-end tests
+docker compose exec e2e pnpm test:e2e
+```
+
+## Compliance Requirements
+
+### Mandatory Rules
+
+**Project Structure**:
+- **MANDATORY**: All new code must follow the standardized project structure
+- **MANDATORY**: Core backend logic only in `/src/` directory
+- **MANDATORY**: Frontend code only in `/frontend/` directory
+- **MANDATORY**: All Docker files in `/docker/` directory
+
+**Package Management**:
+- **MANDATORY**: Use UV for Python package management
+- **MANDATORY**: Use pnpm for React package management
+- **MANDATORY**: Dependencies declared in appropriate configuration files
+
+**Containerization**:
+- **MANDATORY**: Use Docker containers for all deployments
+- **MANDATORY**: Frontend applications must be containerized
+- **MANDATORY**: Use `docker compose` for orchestration
+- **MANDATORY**: Never use obsolete `version` attribute in Docker Compose files
+- **MANDATORY**: Use uppercase `FROM` and `AS` in multi-stage Dockerfiles
+
+**Code Quality**:
+- **MANDATORY**: Run linting before building frontend containers
+- **MANDATORY**: Resolve all TypeScript errors before deployment
+- **MANDATORY**: Follow language-specific coding standards
+
+### Forbidden Practices
+
+**Package Management**:
+- **FORBIDDEN**: Using `pip` for Python package management
+- **FORBIDDEN**: Using `npm` for React projects (use pnpm instead)
+- **FORBIDDEN**: Installing packages outside of containerized environments
+
+**Project Organization**:
+- **FORBIDDEN**: Business logic outside `/src/` directory
+- **FORBIDDEN**: Frontend code outside `/frontend/` directory
+- **FORBIDDEN**: Data files committed to git
+- **FORBIDDEN**: Configuration secrets in code
+- **FORBIDDEN**: Environment variables in subdirectories
+
+**Development Workflow**:
+- **FORBIDDEN**: Using deprecated `docker-compose` command (use `docker compose`)
+- **FORBIDDEN**: Using obsolete `version` attribute in Docker Compose files
+- **FORBIDDEN**: Running applications outside of containers
+- **FORBIDDEN**: Direct execution of local binaries for production code
+- **FORBIDDEN**: Using lowercase `from` and `as` in multi-stage Dockerfiles
+
+## Deployment Procedures
+
+### Production Deployment
+
+**Pre-Deployment Checklist**:
+1. All tests passing in containerized environment
+2. Linting and type checking completed
+3. Environment variables properly configured
+4. Database migrations applied
+5. Security scan completed
+
+**Deployment Commands**:
+```bash
+# Production build
+docker compose -f docker-compose.prod.yml build
+
+# Production deployment
+docker compose -f docker-compose.prod.yml up -d
+
+# Health check
+docker compose -f docker-compose.prod.yml ps
+```
+
+### Development vs Production
+
+**Development Environment**:
+- Use development Docker Compose configuration
+- Enable hot reloading where applicable
+- Include development tools and debugging utilities
+- Use development environment variables
+
+**Production Environment**:
+- Use production-optimized Docker images
+- Exclude development dependencies
+- Enable production optimizations
+- Use production environment variables
+- Implement proper logging and monitoring
+
+## Summary
+
+These rules ensure:
+- **Consistent Development Environment**: All developers use identical containerized setups
+- **Modern Tooling**: Latest Docker CLI, UV for Python, pnpm for React
+- **Quality Assurance**: Mandatory linting, type checking, and testing
+- **Reproducible Builds**: Standardized container build and deployment procedures
+- **Security**: Centralized environment management and no secrets in code
+- **Maintainability**: Clear separation of concerns and standardized workflows
+
+**Non-compliance with these rules is not acceptable and must be corrected immediately.**
+
+## Quick Reference
+
+### Common Commands
+
+**Start Development Environment**:
+```bash
+cd docker && docker compose up -d --build
+```
+
+**Rebuild Specific Service**:
+```bash
+docker compose down SERVICE_NAME
+docker compose up -d SERVICE_NAME --build
+```
+
+**View Logs**:
+```bash
+docker compose logs SERVICE_NAME -f
+```
+
+**Execute Commands in Container**:
+```bash
+docker compose exec SERVICE_NAME COMMAND
+```
+
+**Clean Up**:
+```bash
+docker compose down
+docker system prune -f
+```
+
+### Package Management Quick Reference
+
+**Python (UV)**:
+```bash
+# Add dependency
+uv add package_name
+
+# Sync dependencies
+uv sync
+
+# Remove dependency
+uv remove package_name
+```
+
+**React (pnpm)**:
+```bash
+# Install dependencies
+pnpm install
+
+# Add dependency
+pnpm add package_name
+
+# Add dev dependency
+pnpm add -D package_name
+
+# Remove dependency
+pnpm remove package_name
+
+# Run linting
+pnpm lint
+
+# Run tests
+pnpm test
+```
\ No newline at end of file
diff --git a/.clinerules/Mandates.md b/.clinerules/Mandates.md
new file mode 100644
index 0000000..6db76b2
--- /dev/null
+++ b/.clinerules/Mandates.md
@@ -0,0 +1,10 @@
+
+- use the just_run_* tools via the MCP server
+- all installs should be done in the docker container.
+- NO installs on the host
+- database upgrades should be handled during container server start up
+- always rebuild the container before running tests
+- if you need clarification return to PLAN mode
+- force rereading of the mandates on each cycle
+- always track progress of plans in todo.md
+
\ No newline at end of file
diff --git a/.clinerules/planning.md b/.clinerules/planning.md
new file mode 100644
index 0000000..9a66d5d
--- /dev/null
+++ b/.clinerules/planning.md
@@ -0,0 +1,33 @@
+# Planning and Phased Approach Guidelines
+
+## When asked to plan or solve complex problems:
+
+### 1. Always break down into phases
+- Identify 3-5 distinct phases maximum
+- Each phase should have clear deliverables
+- Phases should build logically on each other
+- Include estimated timeframes when relevant
+
+### 2. Create actionable todo lists
+- Use specific, measurable action items
+- Start each item with an action verb
+- Include who is responsible (if applicable)
+- Add priority levels (High/Medium/Low)
+- Include dependencies between tasks
+
+### 3. Structure format
+For each phase, provide:
+- **Phase Name & Objective**
+- **Key Deliverables**
+- **Todo List** (with checkboxes)
+- **Success Criteria**
+- **Estimated Duration**
+- **Dependencies/Prerequisites**
+
+### 4. Planning principles to follow:
+- Start with the end goal and work backwards
+- Identify critical path items first
+- Consider resource constraints and bottlenecks
+- Build in buffer time for unexpected issues
+- Include review/checkpoint moments
+- Make tasks concrete and specific enough that someone else could execute them
\ No newline at end of file
diff --git a/garminsync/fit_processor/gear_analyzer.py b/garminsync/fit_processor/gear_analyzer.py
new file mode 100644
index 0000000..6f13b21
--- /dev/null
+++ b/garminsync/fit_processor/gear_analyzer.py
@@ -0,0 +1,73 @@
+import numpy as np
+
+class SinglespeedAnalyzer:
+ def __init__(self):
+ self.chainring_options = [38, 46] # teeth
+ self.common_cogs = list(range(11, 28)) # 11t to 27t rear cogs
+ self.wheel_circumference_m = 2.096 # 700x25c tire
+
+ def analyze_gear_ratio(self, speed_data, cadence_data, gradient_data):
+ """Determine most likely singlespeed gear ratio"""
+ # Validate input parameters
+ if not speed_data or not cadence_data or not gradient_data:
+ raise ValueError("Input data cannot be empty")
+ if len(speed_data) != len(cadence_data) or len(speed_data) != len(gradient_data):
+ raise ValueError("Input data arrays must be of equal length")
+
+ # Filter for flat terrain segments (gradient < 3%)
+ flat_indices = [i for i, grad in enumerate(gradient_data) if abs(grad) < 3.0]
+ flat_speeds = [speed_data[i] for i in flat_indices]
+ flat_cadences = [cadence_data[i] for i in flat_indices]
+
+ # Only consider data points with sufficient speed (15 km/h) and cadence
+ valid_indices = [i for i in range(len(flat_speeds))
+ if flat_speeds[i] > 4.17 and flat_cadences[i] > 0] # 15 km/h threshold
+
+ if not valid_indices:
+ return None # Not enough data
+
+ valid_speeds = [flat_speeds[i] for i in valid_indices]
+ valid_cadences = [flat_cadences[i] for i in valid_indices]
+
+ # Calculate gear ratios from speed and cadence
+ gear_ratios = []
+ for speed, cadence in zip(valid_speeds, valid_cadences):
+ # Gear ratio = (speed in m/s * 60 seconds/minute) / (cadence in rpm * wheel circumference in meters)
+ gr = (speed * 60) / (cadence * self.wheel_circumference_m)
+ gear_ratios.append(gr)
+
+ # Calculate average gear ratio
+ avg_gear_ratio = sum(gear_ratios) / len(gear_ratios)
+
+ # Find best matching chainring and cog combination
+ best_fit = None
+ min_diff = float('inf')
+ for chainring in self.chainring_options:
+ for cog in self.common_cogs:
+ theoretical_ratio = chainring / cog
+ diff = abs(theoretical_ratio - avg_gear_ratio)
+ if diff < min_diff:
+ min_diff = diff
+ best_fit = (chainring, cog, theoretical_ratio)
+
+ if not best_fit:
+ return None
+
+ chainring, cog, ratio = best_fit
+
+ # Calculate gear metrics
+ wheel_diameter_inches = 27.0 # 700c wheel diameter
+ gear_inches = ratio * wheel_diameter_inches
+ development_meters = ratio * self.wheel_circumference_m
+
+ # Calculate confidence score (1 - relative error)
+ confidence = max(0, 1 - (min_diff / ratio)) if ratio > 0 else 0
+
+ return {
+ 'estimated_chainring_teeth': chainring,
+ 'estimated_cassette_teeth': cog,
+ 'gear_ratio': ratio,
+ 'gear_inches': gear_inches,
+ 'development_meters': development_meters,
+ 'confidence_score': confidence
+ }
diff --git a/garminsync/fit_processor/power_estimator.py b/garminsync/fit_processor/power_estimator.py
new file mode 100644
index 0000000..4dfa648
--- /dev/null
+++ b/garminsync/fit_processor/power_estimator.py
@@ -0,0 +1,44 @@
+import numpy as np
+
+class PowerEstimator:
+ def __init__(self):
+ self.bike_weight_kg = 10.0 # 22 lbs
+ self.rider_weight_kg = 75.0 # Default assumption
+ self.drag_coefficient = 0.88 # Road bike
+ self.frontal_area_m2 = 0.4 # Typical road cycling position
+ self.rolling_resistance = 0.004 # Road tires
+ self.drivetrain_efficiency = 0.97
+ self.air_density = 1.225 # kg/m³ at sea level, 20°C
+
+ def calculate_power(self, speed_ms, gradient_percent,
+ air_temp_c=20, altitude_m=0):
+ """Calculate estimated power using physics model"""
+ # Validate input parameters
+ if not isinstance(speed_ms, (int, float)) or speed_ms < 0:
+ raise ValueError("Speed must be a non-negative number")
+ if not isinstance(gradient_percent, (int, float)):
+ raise ValueError("Gradient must be a number")
+
+ # Calculate air density based on temperature and altitude
+ temp_k = air_temp_c + 273.15
+ pressure = 101325 * (1 - 0.0000225577 * altitude_m) ** 5.25588
+ air_density = pressure / (287.05 * temp_k)
+
+ # Convert gradient to angle
+ gradient_rad = np.arctan(gradient_percent / 100.0)
+
+ # Total mass
+ total_mass = self.bike_weight_kg + self.rider_weight_kg
+
+ # Power components
+ P_roll = self.rolling_resistance * total_mass * 9.81 * np.cos(gradient_rad) * speed_ms
+ P_grav = total_mass * 9.81 * np.sin(gradient_rad) * speed_ms
+ P_aero = 0.5 * air_density * self.drag_coefficient * self.frontal_area_m2 * speed_ms ** 3
+
+ # Power = (Rolling + Gravity + Aerodynamic) / Drivetrain efficiency
+ return (P_roll + P_grav + P_aero) / self.drivetrain_efficiency
+
+ def estimate_peak_power(self, power_values, durations):
+ """Calculate peak power for various durations"""
+ # This will be implemented in Phase 3
+ return {}
diff --git a/garminsync/web/templates/activity.html b/garminsync/web/templates/activity.html
new file mode 100644
index 0000000..b3f6638
--- /dev/null
+++ b/garminsync/web/templates/activity.html
@@ -0,0 +1,154 @@
+
+
+
+
+
+ Activity Details - GarminSync
+
+
+
+
+