updated web interface - v3

2026-01-26 09:02:51 +00:00 · 2025-08-19 07:09:23 -07:00
parent 07d19cfd7a
commit b77dbdcc23
24 changed files with 2727 additions and 445 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,224 @@
+# GarminSync
+
+GarminSync is a powerful Python application that automatically downloads `.fit` files for all your activities from Garmin Connect. It provides both a command-line interface for manual operations and a daemon mode for automatic background synchronization with a web-based dashboard for monitoring and configuration.
+
+## Features
+
+- **CLI Interface**: List and download activities with flexible filtering options
+- **Daemon Mode**: Automatic background synchronization with configurable schedules
+- **Web Dashboard**: Real-time monitoring and configuration through a web interface
+- **Offline Mode**: Work with cached data without internet connectivity
+- **Database Tracking**: SQLite database to track download status and file locations
+- **Rate Limiting**: Respects Garmin Connect's servers with built-in rate limiting
+
+## Technology Stack
+
+- **Backend**: Python 3.10 with SQLAlchemy ORM
+- **CLI Framework**: Typer for command-line interface
+- **Web Framework**: FastAPI with Jinja2 templates
+- **Database**: SQLite for local data storage
+- **Scheduling**: APScheduler for daemon mode scheduling
+- **Containerization**: Docker support for easy deployment
+
+## Installation
+
+### Prerequisites
+
+- Docker (recommended) OR Python 3.10+
+- Garmin Connect account credentials
+
+### Using Docker (Recommended)
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/sstent/GarminSync.git
+   cd GarminSync
+   ```
+
+2. Create a `.env` file with your Garmin credentials:
+   ```bash
+   echo "GARMIN_EMAIL=your_email@example.com" > .env
+   echo "GARMIN_PASSWORD=your_password" >> .env
+   ```
+
+3. Build the Docker image:
+   ```bash
+   docker build -t garminsync .
+   ```
+
+### Using Python Directly
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/sstent/GarminSync.git
+   cd GarminSync
+   ```
+
+2. Create a virtual environment and activate it:
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+
+3. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+4. Create a `.env` file with your Garmin credentials:
+   ```bash
+   echo "GARMIN_EMAIL=your_email@example.com" > .env
+   echo "GARMIN_PASSWORD=your_password" >> .env
+   ```
+
+## Usage
+
+### CLI Commands
+
+List all activities:
+```bash
+# Using Docker
+docker run -it --env-file .env -v $(pwd)/data:/app/data garminsync list --all
+
+# Using Python directly
+python -m garminsync.cli list --all
+```
+
+List missing activities:
+```bash
+# Using Docker
+docker run -it --env-file .env -v $(pwd)/data:/app/data garminsync list --missing
+
+# Using Python directly
+python -m garminsync.cli list --missing
+```
+
+List downloaded activities:
+```bash
+# Using Docker
+docker run -it --env-file .env -v $(pwd)/data:/app/data garminsync list --downloaded
+
+# Using Python directly
+python -m garminsync.cli list --downloaded
+```
+
+Download missing activities:
+```bash
+# Using Docker
+docker run -it --env-file .env -v $(pwd)/data:/app/data garminsync download --missing
+
+# Using Python directly
+python -m garminsync.cli download --missing
+```
+
+Work offline (without syncing with Garmin Connect):
+```bash
+# Using Docker
+docker run -it --env-file .env -v $(pwd)/data:/app/data garminsync list --missing --offline
+
+# Using Python directly
+python -m garminsync.cli list --missing --offline
+```
+
+### Daemon Mode
+
+Start the daemon with web UI:
+```bash
+# Using Docker (expose port 8080 for web UI)
+docker run -it --env-file .env -v $(pwd)/data:/app/data -p 8080:8080 garminsync daemon --start
+
+# Using Python directly
+python -m garminsync.cli daemon --start
+```
+
+Access the web dashboard at `http://localhost:8080`
+
+### Web Interface
+
+The web interface provides real-time monitoring and configuration capabilities:
+
+1. **Dashboard**: View activity statistics, daemon status, and recent logs
+2. **Activities**: Browse all activities with detailed information in a sortable table
+3. **Logs**: Filter and browse synchronization logs with pagination
+4. **Configuration**: Manage daemon settings and scheduling
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env` file in the project root with your Garmin Connect credentials:
+
+```env
+GARMIN_EMAIL=your_email@example.com
+GARMIN_PASSWORD=your_password
+```
+
+### Daemon Scheduling
+
+The daemon uses cron-style scheduling. Configure the schedule through the web UI or by modifying the database directly. Default schedule is every 6 hours (`0 */6 * * *`).
+
+### Data Storage
+
+Downloaded `.fit` files and the SQLite database are stored in the `data/` directory by default. When using Docker, this directory is mounted as a volume to persist data between container runs.
+
+## Web API Endpoints
+
+The web interface provides RESTful API endpoints for programmatic access:
+
+- `GET /api/status` - Get daemon status and recent logs
+- `GET /api/activities/stats` - Get activity statistics
+- `GET /api/activities` - Get paginated activities with filtering
+- `GET /api/activities/{activity_id}` - Get detailed activity information
+- `GET /api/dashboard/stats` - Get comprehensive dashboard statistics
+- `GET /api/logs` - Get filtered and paginated logs
+- `POST /api/sync/trigger` - Manually trigger synchronization
+- `POST /api/schedule` - Update daemon schedule configuration
+- `POST /api/daemon/start` - Start the daemon
+- `POST /api/daemon/stop` - Stop the daemon
+- `DELETE /api/logs` - Clear all logs
+
+## Development
+
+### Project Structure
+
+```
+garminsync/
+├── garminsync/              # Main application package
+│   ├── cli.py              # Command-line interface
+│   ├── config.py           # Configuration management
+│   ├── database.py         # Database models and operations
+│   ├── garmin.py           # Garmin Connect client wrapper
+│   ├── daemon.py           # Daemon mode implementation
+│   └── web/                # Web interface components
+│       ├── app.py          # FastAPI application setup
+│       ├── routes.py       # API endpoints
+│       ├── static/         # CSS, JavaScript files
+│       └── templates/      # HTML templates
+├── data/                   # Downloaded files and database
+├── .env                    # Environment variables (gitignored)
+├── Dockerfile              # Docker configuration
+├── requirements.txt        # Python dependencies
+└── README.md               # This file
+```
+
+### Running Tests
+
+(Add test instructions when tests are implemented)
+
+## Known Limitations
+
+- No support for two-factor authentication (2FA)
+- Limited automatic retry logic for failed downloads
+- No support for selective activity date range downloads
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Support
+
+For issues and feature requests, please use the GitHub issue tracker.