# GarminSync Application Design

## Basic Info
**App Name:** GarminSync
**What it does:** CLI application that downloads FIT files for every activity in Garmin Connect

## Core Features
1. List activities (`garminsync list --all`)
2. List activities that have not been downloaded (`garminsync list --missing`)
3. List activities that have been downloaded (`garminsync list --downloaded`)
4. Download missing activities (`garminsync download --missing`)

## Tech Stack
**Frontend:** Python CLI (argparse)
**Backend:** Python 3.10+ with garminexport==1.2.0
**Database:** SQLite (garmin.db)
**Hosting:** Docker container
**Key Libraries:** garminexport, python-dotenv, sqlite3

## Data Structure
**Main data object:**
```
Activity:
- activity_id: INTEGER (primary key, from Garmin)
- start_time: TEXT (ISO 8601 format)
- filename: TEXT (unique, e.g., activity_123_20240807.fit)
- downloaded: BOOLEAN (0 = pending, 1 = completed)
```

## User Flow
1. User launches container with credentials: `docker run -it --env-file .env garminsync`
2. User is presented with CLI menu of options
3. User selects command (e.g., `garminsync download --missing`)
4. Application executes task with progress indicators
5. Application displays completion status and summary

## File Structure
```
GarminSync/
├── Dockerfile
├── .env.example
├── requirements.txt
└── main.py
```

## Technical Implementation Notes
- **Single-file architecture:** All logic in main.py (CLI, DB, Garmin integration)
- **Authentication:** Credentials via GARMIN_EMAIL/GARMIN_PASSWORD env vars (never stored)
- **File naming:** `activity_{id}_{timestamp}.fit` (e.g., activity_123456_20240807.fit)
- **Rate limiting:** 2-second delays between API requests
- **Database:** In-memory during auth testing, persistent garmin.db for production
- **Docker** All docker commands require the use of sudo

## Development Phases
### Phase 1: Core Infrastructure
- [X] Dockerfile with Python 3.10 base
- [X] Environment variable handling
- [X] garminexport client initialization

### Phase 2: Activity Listing
- [ ] SQLite schema implementation
- [ ] Activity listing commands
- [ ] Database synchronization

### Phase 3: Download Pipeline
- [ ] FIT file download implementation
- [ ] Idempotent download logic
- [ ] Database update on success

### Phase 4: Polish
- [ ] Progress indicators
- [ ] Error handling
- [ ] README documentation

## Critical Roadblocks
1. **Garmin API changes:** garminexport is abandoned, switch to garmin-connect-export instead
2. **Rate limiting:** Built-in 2-second request delays
3. **Session management:** Automatic cookie handling via garminexport
4. **File conflicts:** Atomic database updates during downloads
5. **Docker permissions:** Volume-mounted /data directory for downloads

## Current Status
**Working on:** Phase 1 - Core Infrastructure (Docker setup, env vars)
**Next steps:** Implement activity listing with SQLite schema
**Known issues:** Garmin API rate limits (mitigated by 2s delays), session timeout handling