openapi: 3.0.0
info:
  title: FitTrack Report Generator API
  version: 1.0.0
  description: API for analyzing workout files and generating reports.

servers:
  - url: /api
    description: Base API path

paths:
  /analyze/workout:
    post:
      summary: Analyze a single workout file
      description: Uploads a single workout file (FIT, TCX, or GPX) for comprehensive analysis.
      operationId: analyzeSingleWorkout
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The workout file (FIT, TCX, or GPX) to analyze.
                user_id:
                  type: string
                  format: uuid
                  description: Optional user ID to associate the analysis with.
                ftp_value:
                  type: number
                  format: float
                  description: Optional Functional Threshold Power (FTP) value for calculations. Overrides user's default if provided.
              required:
                - file
      responses:
        '200':
          description: Analysis successful. Returns a summary of the analysis.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkoutAnalysisSummary'
        '400':
          description: Invalid input or file format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /analyze/batch:
    post:
      summary: Analyze multiple workout files in a batch
      description: Uploads a directory (as a zip file) of workout files for batch analysis and generates a summary report.
      operationId: analyzeBatchWorkouts
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                zip_file:
                  type: string
                  format: binary
                  description: A zip file containing multiple workout files (FIT, TCX, or GPX).
                user_id:
                  type: string
                  format: uuid
                  description: Optional user ID to associate the analysis with.
                ftp_value:
                  type: number
                  format: float
                  description: Optional Functional Threshold Power (FTP) value for calculations. Overrides user's default if provided.
              required:
                - zip_file
      responses:
        '200':
          description: Batch analysis initiated. Returns a summary of the batch process.
          content:
            application/json:
              schema:
                type: object
                properties:
                  batch_id:
                    type: string
                    format: uuid
                    description: Unique ID for the batch analysis.
                  status:
                    type: string
                    description: Status of the batch analysis (e.g., 'processing', 'completed').
                  total_files:
                    type: integer
                    description: Total number of files submitted in the batch.
        '400':
          description: Invalid input or file format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /analysis/{analysis_id}/charts:
    get:
      summary: Retrieve generated charts for a specific analysis
      description: Returns a PNG image of the requested chart for a previously analyzed workout.
      operationId: getAnalysisCharts
      parameters:
        - name: analysis_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The ID of the workout analysis.
        - name: chart_type
          in: query
          required: true
          schema:
            type: string
            enum: [power_curve, elevation_profile, zone_distribution_power, zone_distribution_hr, zone_distribution_speed]
          description: The type of chart to retrieve.
      responses:
        '200':
          description: Chart image successfully retrieved.
          content:
            image/png:
              schema:
                type: string
                format: binary
        '404':
          description: Analysis or chart not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /analysis/{analysis_id}/summary:
    get:
      summary: Retrieve a summary of a specific analysis
      description: Returns a detailed summary of a previously analyzed workout.
      operationId: getAnalysisSummary
      parameters:
        - name: analysis_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The ID of the workout analysis.
      responses:
        '200':
          description: Analysis summary successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkoutAnalysisSummary'
        '404':
          description: Analysis not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    WorkoutAnalysisSummary:
      type: object
      properties:
        analysis_id:
          type: string
          format: uuid
          description: Unique ID of the analysis.
        user_id:
          type: string
          format: uuid
          description: User ID associated with the analysis.
        file_name:
          type: string
          description: Original name of the analyzed file.
        analysis_date:
          type: string
          format: date-time
          description: Timestamp of the analysis.
        status:
          type: string
          description: Status of the analysis (e.g., 'completed', 'failed').
        metrics:
          type: object
          description: Key metrics from the workout analysis (e.g., duration, distance, NP, IF, TSS).
          additionalProperties: true
        report_url:
          type: string
          format: url
          description: URL to the generated report.
        chart_urls:
          type: object
          description: URLs to generated charts.
          additionalProperties:
            type: string
            format: url
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: A unique error code.
        message:
          type: string
          description: A human-readable error message.
        details:
          type: object
          description: Optional additional error details.
          additionalProperties: true