# 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)`