FitTrack_ReportGenerator/specs/001-create-a-new/data-model.md

Data Model

Entities

User

• Description: Represents a user of the system, primarily for storing personalized settings.
• Fields:
  • id: Unique identifier (e.g., UUID)
  • ftp_value: Configured Functional Threshold Power (float, nullable, default value if null)
• Relationships: One-to-many with WorkoutAnalysis (a user can have multiple analyses).
• Validation Rules: ftp_value must be a positive number if set.

WorkoutAnalysis

• Description: Represents the result of analyzing a single workout file. This entity links a user to their analyzed workout data.
• Fields:
  • id: Unique identifier (e.g., UUID)
  • user_id: Foreign key to User.id
  • file_name: Original name of the workout file (string)
  • analysis_date: Timestamp of when the analysis was performed (datetime)
  • status: Status of the analysis (e.g., 'completed', 'failed', 'processing')
  • summary_metrics: JSONB field for storing overall workout summary metrics (e.g., total distance, duration, average speed, etc.)
  • report_path: Path to the generated report (string)
  • chart_paths: JSONB field for storing paths to generated charts (e.g., {'power_curve': '/path/to/chart.png'})
• Relationships: Many-to-one with User.

WorkoutData (Conceptual/In-Memory Structure)

• Description: Represents the complete raw and processed data for a single workout session. This is primarily an in-memory object during analysis and its key components are persisted in WorkoutAnalysis.
• Fields:
  • metadata: WorkoutMetadata object
  • time_series_data: Pandas DataFrame containing raw time-series data (e.g., timestamp, power, heart rate, speed, elevation)
  • power_data: PowerData object
  • heart_rate_data: HeartRateData object
  • speed_data: SpeedData object (derived from time-series)
  • elevation_data: ElevationData object (derived from time-series)

WorkoutMetadata

• Description: Metadata extracted from the workout file.
• Fields:
  • start_time: Datetime of workout start
  • duration: Total duration (timedelta or seconds)
  • device: Device used for recording (string)
  • file_type: Original file type (e.g., 'FIT', 'TCX', 'GPX')

PowerData

• Description: Contains all power-related analysis results.
• Fields:
  • raw_power_stream: List of power values
  • average_power: Float
  • normalized_power: Float
  • intensity_factor: Float
  • training_stress_score: Float
  • zone_distribution: Dictionary/JSONB of time spent in each power zone

HeartRateData

• Description: Contains all heart-rate-related analysis results.
• Fields:
  • raw_hr_stream: List of heart rate values
  • average_hr: Float
  • max_hr: Integer
  • zone_distribution: Dictionary/JSONB of time spent in each heart rate zone

ZoneCalculator (Utility)

• Description: A utility class/module for defining and calculating training zones based on user-specific thresholds (like FTP) or default values.
• Fields: (Methods for calculation, not data fields)
  • calculate_power_zones(ftp, max_power)
  • calculate_heart_rate_zones(max_hr)