feat: Initial implementation of FitTrack Report Generator

This commit introduces the initial version of the FitTrack Report Generator, a FastAPI application for analyzing workout files. Key features include: - Parsing of FIT, TCX, and GPX workout files. - Analysis of power, heart rate, speed, and elevation data. - Generation of summary reports and charts. - REST API for single and batch workout analysis. The project structure has been set up with a `src` directory for core logic, an `api` directory for the FastAPI application, and a `tests` directory for unit, integration, and contract tests. The development workflow is configured to use Docker and modern Python tooling.
2026-01-26 00:52:03 +00:00 · 2025-10-11 09:54:13 -07:00
parent 6643a64ff0
commit 9e0bd322d3
152 changed files with 25695 additions and 49 deletions
--- a/specs/001-create-a-new/quickstart.md
+++ b/specs/001-create-a-new/quickstart.md
@@ -0,0 +1,137 @@
+# Quickstart Guide: FitTrack Report Generator API
+
+This guide provides a quick overview of how to interact with the FitTrack Report Generator API.
+
+## Base URL
+
+The base URL for all API endpoints is `/api`.
+
+## 1. Analyze a Single Workout File
+
+To analyze a single workout file, send a `POST` request to the `/analyze/workout` endpoint with the workout file and optional user/FTP information.
+
+### Endpoint
+`POST /api/analyze/workout`
+
+### Request Example (using `curl`)
+
+```bash
+curl -X POST \
+  -H "Content-Type: multipart/form-data" \
+  -F "file=@/path/to/your/workout.fit" \
+  -F "user_id=a1b2c3d4-e5f6-7890-1234-567890abcdef" \
+  -F "ftp_value=250" \
+  http://localhost:8000/api/analyze/workout
+```
+
+### Response Example (200 OK)
+
+```json
+{
+  "analysis_id": "f1e2d3c4-b5a6-9876-5432-10fedcba9876",
+  "user_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
+  "file_name": "workout.fit",
+  "analysis_date": "2025-10-09T10:30:00Z",
+  "status": "completed",
+  "metrics": {
+    "duration": "01:00:00",
+    "distance_km": 25.5,
+    "normalized_power_watts": 220,
+    "intensity_factor": 0.88,
+    "tss": 75
+  },
+  "report_url": "/api/analysis/f1e2d3c4-b5a6-9876-5432-10fedcba9876/report",
+  "chart_urls": {
+    "power_curve": "/api/analysis/f1e2d3c4-b5a6-9876-5432-10fedcba9876/charts?chart_type=power_curve"
+  }
+}
+```
+
+## 2. Analyze Multiple Workout Files (Batch)
+
+To analyze multiple workout files, compress them into a `.zip` file and send a `POST` request to the `/analyze/batch` endpoint.
+
+### Endpoint
+`POST /api/analyze/batch`
+
+### Request Example (using `curl`)
+
+```bash
+curl -X POST \
+  -H "Content-Type: multipart/form-data" \
+  -F "zip_file=@/path/to/your/workouts.zip" \
+  -F "user_id=a1b2c3d4-e5f6-7890-1234-567890abcdef" \
+  http://localhost:8000/api/analyze/batch
+```
+
+### Response Example (200 OK)
+
+```json
+{
+  "batch_id": "g1h2i3j4-k5l6-7890-1234-567890abcdef",
+  "status": "processing",
+  "total_files": 10
+}
+```
+
+## 3. Retrieve Charts for an Analysis
+
+To get a specific chart for a previously analyzed workout, send a `GET` request to the `/analysis/{analysis_id}/charts` endpoint.
+
+### Endpoint
+`GET /api/analysis/{analysis_id}/charts`
+
+### Path Parameters
+- `analysis_id`: The unique ID of the workout analysis.
+
+### Query Parameters
+- `chart_type`: The type of chart to retrieve (e.g., `power_curve`, `elevation_profile`, `zone_distribution_power`).
+
+### Request Example
+
+```bash
+curl -X GET http://localhost:8000/api/analysis/f1e2d3c4-b5a6-9876-5432-10fedcba9876/charts?chart_type=power_curve
+```
+
+### Response
+
+Returns a PNG image of the requested chart.
+
+## 4. Retrieve Analysis Summary
+
+To get a detailed summary of a previously analyzed workout, send a `GET` request to the `/analysis/{analysis_id}/summary` endpoint.
+
+### Endpoint
+`GET /api/analysis/{analysis_id}/summary`
+
+### Path Parameters
+- `analysis_id`: The unique ID of the workout analysis.
+
+### Request Example
+
+```bash
+curl -X GET http://localhost:8000/api/analysis/f1e2d3c4-b5a6-9876-5432-10fedcba9876/summary
+```
+
+### Response Example (200 OK)
+
+```json
+{
+  "analysis_id": "f1e2d3c4-b5a6-9876-5432-10fedcba9876",
+  "user_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
+  "file_name": "workout.fit",
+  "analysis_date": "2025-10-09T10:30:00Z",
+  "status": "completed",
+  "metrics": {
+    "duration": "01:00:00",
+    "distance_km": 25.5,
+    "normalized_power_watts": 220,
+    "intensity_factor": 0.88,
+    "tss": 75
+  },
+  "report_url": "/api/analysis/f1e2d3c4-b5a6-9876-5432-10fedcba9876/report",
+  "chart_urls": {
+    "power_curve": "/api/analysis/f1e2d3c4-b5a6-9876-5432-10fedcba9876/charts?chart_type=power_curve"
+  }
+}
+```