mirror of
https://github.com/sstent/GarminSync.git
synced 2026-01-26 17:12:50 +00:00
117 lines
4.6 KiB
Markdown
117 lines
4.6 KiB
Markdown
# 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:** CLI (Go)
|
|
**Backend:** Go
|
|
**Database:** SQLite (garmin.db)
|
|
**Hosting:** Docker container
|
|
**Key Libraries:** garminexport (Go), viper (env vars), cobra (CLI framework), go-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: `sudo 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
|
|
├── main.go (CLI entrypoint and command implementations)
|
|
├── internal/
|
|
│ ├── config/
|
|
│ │ └── config.go (configuration loading)
|
|
│ ├── garmin/
|
|
│ │ ├── client.go (API integration)
|
|
│ │ └── activity.go (activity models)
|
|
│ └── db/
|
|
│ ├── database.go (embedded schema)
|
|
│ ├── sync.go (database synchronization)
|
|
│ └── migrations.go (versioned migrations)
|
|
├── Dockerfile
|
|
├── .env
|
|
└── README.md
|
|
```
|
|
|
|
## Technical Implementation Notes
|
|
- **Architecture:** Go-based implementation with Cobra CLI framework
|
|
- **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:** Embedded schema creation in Go code with versioned migrations
|
|
- **Database Sync:** Before any list/download operation, the application performs a synchronization between Garmin Connect and the local SQLite database to ensure activity records are up-to-date.
|
|
- **CLI Structure:** All CLI commands and flags are implemented in main.go using Cobra, without separate command files
|
|
- **Docker:**
|
|
- All commands require sudo as specified
|
|
- Fully containerized build process (no host Go dependencies)
|
|
- **Session management:** Automatic cookie handling via garminexport with file-based persistence
|
|
- **Pagination:** Implemented for activity listing
|
|
- **Package stability:** Always use stable, released versions of packages to ensure reproducibility
|
|
|
|
## Development Phases
|
|
### Phase 1: Core Infrastructure - COMPLETE
|
|
- [x] Dockerfile creation
|
|
- [x] Environment variable handling (viper)
|
|
- [x] Cobra CLI framework setup
|
|
- [x] garminexport client initialization (with session persistence)
|
|
|
|
### Phase 2: Activity Listing - COMPLETE
|
|
- [x] SQLite schema implementation
|
|
- [x] Activity listing commands
|
|
- [x] Database synchronization
|
|
- [x] List command UI implementation
|
|
|
|
### Phase 3: Download Pipeline - COMPLETE
|
|
- [x] FIT file download implementation
|
|
- [x] Idempotent download logic (with exponential backoff)
|
|
- [x] Database update on success
|
|
- [x] Database sync integration
|
|
|
|
### Phase 4: Polish
|
|
- [x] Progress indicators (download command)
|
|
- [~] Error handling (partial implementation - retry logic exists but needs expansion)
|
|
- [ ] README documentation
|
|
- [x] Session timeout handling (via garminexport)
|
|
|
|
## Critical Roadblocks
|
|
1. **Rate limiting:** Built-in 2-second request delays (implemented)
|
|
2. **Session management:** Automatic cookie handling via garminexport (implemented)
|
|
3. **File conflicts:** Atomic database updates during downloads (implemented)
|
|
4. **Docker permissions:** Volume-mounted /data directory for downloads (implemented)
|
|
5. ~~**Database sync:** Efficient Garmin API ↔ local sync~~ (implemented)
|
|
|
|
## Current Status
|
|
**Working on:** Phase 4 - Final polish and error handling
|
|
**Next steps:**
|
|
1. Fix command flag parsing issue
|
|
2. Implement comprehensive error handling
|
|
3. Complete README documentation
|
|
4. Final testing and validation
|
|
|
|
**Known issues:** None
|
|
|
|
## Recent Fixes
|
|
- Fixed package declaration conflicts in cmd/ directory (changed from `package cmd` to `package main`)
|
|
- Removed unnecessary import in root.go that was causing build errors
|
|
- Verified Docker build process now completes successfully
|