{
  "openapi": "3.0.0",
  "info": {
    "title": "Quick Connect API",
    "description": "API documentation for Quick Connect Backend - A comprehensive QR code management system with Memory Tag features, user authentication, and privacy controls.",
    "version": "1.0.0",
    "contact": {
      "name": "Quick Connect API Support",
      "email": "support@quickconnect.com"
    }
  },
  "servers": [
    {
      "url": "http://localhost:3002/api",
      "description": "Development server (HTTP)"
    },
    {
      "url": "https://quickconnect.prodservers.com:5513/api",
      "description": "Development server (HTTPS)"
    },
    {
      "url": "https://api.quickconnect.com/api",
      "description": "Production server (HTTPS)"
    },
    {
      "url": "https://quickconnect.prodservers.com:5513/api",
      "description": "Staging server (HTTPS)"
    }
  ],
  "paths": {
    "/auth/register": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Register a new user",
        "description": "Create a new user account with email and password. Optionally include device token for push notifications.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "password"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "User's email address"
                  },
                  "password": {
                    "type": "string",
                    "minLength": 8,
                    "description": "User's password (minimum 8 characters)"
                  },
                  "first_name": {
                    "type": "string",
                    "description": "User's first name (optional)"
                  },
                  "last_name": {
                    "type": "string",
                    "description": "User's last name (optional)"
                  },
                  "deviceToken": {
                    "type": "string",
                    "description": "Device token for push notifications (optional)"
                  },
                  "deviceType": {
                    "type": "string",
                    "enum": [
                      "ios",
                      "android",
                      "web"
                    ],
                    "description": "Type of device for push notifications (optional)"
                  }
                }
              },
              "examples": {
                "basicRegistration": {
                  "summary": "Basic registration",
                  "value": {
                    "email": "user@example.com",
                    "password": "SecurePass123@"
                  }
                },
                "fullRegistration": {
                  "summary": "Registration with device token",
                  "value": {
                    "email": "user40@example.com",
                    "password": "JP123456789@",
                    "deviceToken": "string",
                    "deviceType": "ios"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "User registered successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "User registered successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "user": {
                          "$ref": "#/components/schemas/User"
                        },
                        "token": {
                          "type": "string",
                          "description": "JWT authentication token"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or user already exists"
          }
        }
      }
    },
    "/auth/login": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Login user",
        "description": "Authenticate user with email and password. Upon successful login, a session is created and user information is stored in the express session. The response includes a JWT token for API authentication and session cookie for session-based authentication.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "password"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "User's email address"
                  },
                  "password": {
                    "type": "string",
                    "description": "User's password"
                  },
                  "deviceToken": {
                    "type": "string",
                    "description": "Device token for push notifications (optional)"
                  },
                  "deviceType": {
                    "type": "string",
                    "enum": [
                      "ios",
                      "android",
                      "web"
                    ],
                    "description": "Type of device (optional)"
                  }
                }
              },
              "examples": {
                "basicLogin": {
                  "summary": "Basic login",
                  "value": {
                    "email": "user@example.com",
                    "password": "SecurePass123@"
                  }
                },
                "loginWithDevice": {
                  "summary": "Login with device token",
                  "value": {
                    "email": "user@example.com",
                    "password": "SecurePass123@",
                    "deviceToken": "device-token-string",
                    "deviceType": "ios"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Login successful. Session is created and user information is stored in express session.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Login successful"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "user": {
                          "$ref": "#/components/schemas/User"
                        },
                        "token": {
                          "type": "string",
                          "description": "JWT authentication token"
                        }
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "Set-Cookie": {
                "description": "Session cookie is set automatically by express-session",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "Invalid credentials",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/auth/logout": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Logout user",
        "description": "Logout the current user. This endpoint destroys the express session and invalidates the user's session. The user can be authenticated via JWT token (Bearer token) or session cookie. Both authentication methods are supported for backward compatibility.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Logout successful. Session has been destroyed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Logout successful"
                    },
                    "data": {
                      "type": "object",
                      "description": "Logout confirmation data"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - User not authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Logout failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/auth/verify-otp": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Verify OTP",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "otp"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "otp": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OTP verified successfully"
          },
          "400": {
            "description": "Invalid OTP"
          }
        }
      }
    },
    "/auth/resend-otp": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Resend OTP",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OTP resent successfully"
          }
        }
      }
    },
    "/auth/check-password-strength": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Check password strength",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "password"
                ],
                "properties": {
                  "password": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Password strength checked"
          }
        }
      }
    },
    "/auth/forgot-password": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Request password reset",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reset email sent"
          }
        }
      }
    },
    "/auth/profile": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "summary": "Get current user profile",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "User profile retrieved"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      },
      "put": {
        "tags": [
          "Authentication"
        ],
        "summary": "Update user profile",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "first_name": {
                    "type": "string"
                  },
                  "last_name": {
                    "type": "string"
                  },
                  "phone_number": {
                    "type": "string"
                  },
                  "profile_picture": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Profile updated successfully"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/auth/profile/{id}": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "summary": "Get user profile by ID",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "User profile retrieved"
          },
          "404": {
            "description": "User not found"
          }
        }
      }
    },
    "/auth/profile-resources": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "summary": "Get profile resources",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Profile resources retrieved"
          }
        }
      }
    },
    "/auth/change-password": {
      "put": {
        "tags": [
          "Authentication"
        ],
        "summary": "Change password",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "currentPassword",
                  "newPassword",
                  "confirmPassword"
                ],
                "properties": {
                  "currentPassword": {
                    "type": "string"
                  },
                  "newPassword": {
                    "type": "string"
                  },
                  "confirmPassword": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Password changed successfully"
          }
        }
      }
    },
    "/auth/reset-password": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Reset password with token",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "newPassword",
                  "confirmPassword"
                ],
                "properties": {
                  "newPassword": {
                    "type": "string"
                  },
                  "confirmPassword": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Password reset successfully"
          }
        }
      }
    },
    "/auth/create-profile": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Create user profile",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "first_name": {
                    "type": "string"
                  },
                  "last_name": {
                    "type": "string"
                  },
                  "phone_number": {
                    "type": "string"
                  },
                  "country": {
                    "type": "string"
                  },
                  "State": {
                    "type": "string"
                  },
                  "City": {
                    "type": "string"
                  },
                  "role": {
                    "type": "string",
                    "enum": [
                      "USER",
                      "ADMIN",
                      "SCANNER"
                    ]
                  },
                  "profile_picture": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Profile created successfully"
          }
        }
      }
    },
    "/auth/notification-preference": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Update notification preferences",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "emailNotifications": {
                    "type": "boolean"
                  },
                  "pushNotifications": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Preferences updated"
          }
        }
      }
    },
    "/auth/edit-profile": {
      "put": {
        "tags": [
          "Authentication"
        ],
        "summary": "Edit user profile",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "first_name": {
                    "type": "string"
                  },
                  "last_name": {
                    "type": "string"
                  },
                  "profile_picture": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Profile updated successfully"
          }
        }
      }
    },
    "/qrcodes": {
      "get": {
        "tags": [
          "QR Codes"
        ],
        "summary": "Get all QR codes for authenticated user",
        "description": "Retrieve paginated list of QR codes with optional filtering by type, status, and search query. Excludes MEMORY_TAG type by default.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            },
            "description": "Page number for pagination"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10
            },
            "description": "Number of items per page"
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Search by item name or type"
          }
        ],
        "responses": {
          "200": {
            "description": "QR codes retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "qrcodes": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/QRCode"
                          }
                        },
                        "total": {
                          "type": "integer"
                        },
                        "page": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "totalPages": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "QR Codes"
        ],
        "summary": "Create new QR code",
        "description": "Create a new QR code with support for multiple types (CAR, PET, MEDICAL_QR, LUGGAGE, IDENTIFICATIONS, DOCUMENT, MEMORY_TAG). Supports file uploads for images and location tracking.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "title",
                  "type"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "QR code title"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "CAR",
                      "PET",
                      "MEDICAL_QR",
                      "LUGGAGE",
                      "IDENTIFICATIONS",
                      "DOCUMENT",
                      "MEMORY_TAG",
                      "WIFI"
                    ],
                    "description": "Type of QR code"
                  },
                  "item_name": {
                    "type": "string",
                    "description": "Name of the item (e.g., 'Honda Civic 2020', 'Buddy - Golden Retriever')"
                  },
                  "item_description": {
                    "type": "string",
                    "description": "Detailed description of the item"
                  },
                  "type_details": {
                    "type": "string",
                    "description": "JSON string containing type-specific details (e.g., car details, pet info, medical data)"
                  },
                  "location": {
                    "type": "string",
                    "description": "JSON string with latitude and longitude: {\"latitude\": 40.7128, \"longitude\": -74.0060}"
                  },
                  "location_enabled": {
                    "type": "boolean",
                    "description": "Enable location tracking for this QR code"
                  },
                  "access_type": {
                    "type": "string",
                    "enum": [
                      "PUBLIC",
                      "PRIVATE",
                      "PROTECTED"
                    ],
                    "description": "Access control type"
                  },
                  "pin": {
                    "type": "string",
                    "description": "PIN for PRIVATE or PROTECTED access types"
                  },
                  "color": {
                    "type": "string",
                    "description": "QR code foreground color (hex format)"
                  },
                  "background_color": {
                    "type": "string",
                    "description": "QR code background color (hex format)"
                  },
                  "size": {
                    "type": "integer",
                    "description": "QR code size in pixels"
                  },
                  "notes": {
                    "type": "string",
                    "description": "Additional notes"
                  },
                  "images": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "binary"
                    },
                    "description": "Image files for the QR code"
                  },
                  "memory_tag": {
                    "type": "string",
                    "description": "JSON string for Memory Tag specific data (for MEMORY_TAG type only)"
                  },
                  "privacy_controls": {
                    "type": "string",
                    "description": "JSON string for privacy settings"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "QR code created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "$ref": "#/components/schemas/QRCode"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "QR code limit reached for subscription tier"
          }
        }
      }
    },
    "/qrcodes/public/{id}": {
      "get": {
        "tags": [
          "QR Codes"
        ],
        "summary": "Get public QR code",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "QR code retrieved"
          },
          "404": {
            "description": "QR code not found"
          }
        }
      }
    },
    "/qrcodes/{id}/verify-pin": {
      "post": {
        "tags": [
          "QR Codes"
        ],
        "summary": "Verify QR code PIN for private access",
        "description": "Verify the PIN for a PRIVATE or PROTECTED QR code to gain access to its content",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "QR code ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "pin"
                ],
                "properties": {
                  "pin": {
                    "type": "string",
                    "description": "4-digit PIN code"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "PIN verified successfully, QR code data returned"
          },
          "400": {
            "description": "PIN is required"
          },
          "401": {
            "description": "Invalid PIN"
          },
          "404": {
            "description": "QR code not found"
          }
        }
      }
    },
    "/qrcodes/usage/stats": {
      "get": {
        "tags": [
          "QR Codes"
        ],
        "summary": "Get QR code usage statistics for current user",
        "description": "Retrieve statistics about QR code usage including total count, active count, and subscription tier information",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Usage statistics retrieved successfully"
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "User not found"
          }
        }
      }
    },
    "/qrcodes/subscription/limits": {
      "get": {
        "tags": [
          "QR Codes"
        ],
        "summary": "Get subscription limits and current usage",
        "description": "Returns information about QR code limits based on user's subscription tier and current usage",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Subscription limits retrieved successfully"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/qrcodes/{id}": {
      "get": {
        "tags": [
          "QR Codes"
        ],
        "summary": "Get QR code by ID",
        "description": "Retrieve detailed information about a specific QR code including all metadata, images, location, and type-specific details",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "QR code ID"
          }
        ],
        "responses": {
          "200": {
            "description": "QR code retrieved successfully"
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "QR code not found"
          }
        }
      },
      "delete": {
        "tags": [
          "QR Codes"
        ],
        "summary": "Delete QR code (soft delete)",
        "description": "Soft delete a QR code by setting isDelete flag to true and status to INACTIVE. The QR code data is retained but marked as deleted.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "QR code ID"
          }
        ],
        "responses": {
          "200": {
            "description": "QR code deleted successfully"
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "QR code not found"
          }
        }
      }
    },
    "/qrcodes/{qrcodeId}": {
      "put": {
        "tags": [
          "QR Codes"
        ],
        "summary": "Update QR code",
        "description": "Update an existing QR code. Supports partial updates and file uploads. Can update all fields including images, location, and type-specific details.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "qrcodeId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "QR code ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "item_name": {
                    "type": "string"
                  },
                  "item_description": {
                    "type": "string"
                  },
                  "type_details": {
                    "type": "string",
                    "description": "JSON string with type-specific details"
                  },
                  "location": {
                    "type": "string",
                    "description": "JSON string with latitude and longitude"
                  },
                  "location_enabled": {
                    "type": "boolean"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "ACTIVE",
                      "INACTIVE",
                      "MISSING"
                    ]
                  },
                  "notes": {
                    "type": "string"
                  },
                  "images": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "binary"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "QR code updated successfully"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "QR code not found"
          }
        }
      }
    },
    "/qrcodes/{id}/toggle-status": {
      "patch": {
        "tags": [
          "QR Codes"
        ],
        "summary": "Toggle QR code status between ACTIVE and MISSING",
        "description": "Toggle the status of a QR code. If currently ACTIVE, it will be set to MISSING. If MISSING, it will be set to ACTIVE.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "QR code ID"
          }
        ],
        "responses": {
          "200": {
            "description": "QR code status toggled successfully"
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "QR code not found"
          }
        }
      }
    },
    "/qrcodes/{id}/memory-tag/images": {
      "post": {
        "tags": [
          "QR Codes"
        ],
        "summary": "Upload images to Memory Tag QR code",
        "description": "Add new images to an existing Memory Tag QR code. Multiple images can be uploaded at once.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Memory Tag QR code ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "images"
                ],
                "properties": {
                  "images": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "binary"
                    },
                    "description": "Image files to upload"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Images uploaded successfully"
          },
          "400": {
            "description": "No images uploaded"
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Memory Tag QR code not found"
          }
        }
      }
    },
    "/qrcodes/{id}/memory-tag/location": {
      "put": {
        "tags": [
          "QR Codes"
        ],
        "summary": "Update Memory Tag location",
        "description": "Update the geographic location associated with a Memory Tag QR code. Can enable/disable location tracking.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Memory Tag QR code ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "latitude",
                  "longitude"
                ],
                "properties": {
                  "latitude": {
                    "type": "number",
                    "description": "Latitude coordinate"
                  },
                  "longitude": {
                    "type": "number",
                    "description": "Longitude coordinate"
                  },
                  "location_enabled": {
                    "type": "boolean",
                    "description": "Enable or disable location tracking"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Memory Tag location updated successfully"
          },
          "400": {
            "description": "Invalid location data"
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Memory Tag QR code not found"
          }
        }
      }
    },
    "/qrcodes/{id}/memory-tag/images/{imageId}": {
      "delete": {
        "tags": [
          "QR Codes"
        ],
        "summary": "Remove image from Memory Tag",
        "description": "Delete a specific image from a Memory Tag QR code. The image file and database record will be removed.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "imageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Image ID to remove"
          }
        ],
        "responses": {
          "200": {
            "description": "Image removed successfully"
          },
          "400": {
            "description": "Invalid image ID"
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Memory Tag QR code or image not found"
          }
        }
      }
    },
    "/memory-tags": {
      "get": {
        "tags": [
          "Memory Tags"
        ],
        "summary": "Get all memory tags",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Memory tags retrieved"
          }
        }
      },
      "post": {
        "tags": [
          "Memory Tags"
        ],
        "summary": "Create new memory tag",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "location_enabled": {
                    "type": "boolean"
                  },
                  "category": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Memory tag created"
          }
        }
      }
    },
    "/memory-tags/stats": {
      "get": {
        "tags": [
          "Memory Tags"
        ],
        "summary": "Get memory tag statistics",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Statistics retrieved"
          }
        }
      }
    },
    "/memory-tags/shared": {
      "get": {
        "tags": [
          "Memory Tags"
        ],
        "summary": "Get shared memory tags",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Shared memory tags retrieved"
          }
        }
      }
    },
    "/memory-tags/category/{category}": {
      "get": {
        "tags": [
          "Memory Tags"
        ],
        "summary": "Get memory tags by category",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "category",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Memory tags retrieved"
          }
        }
      }
    },
    "/memory-tags/{id}": {
      "get": {
        "tags": [
          "Memory Tags"
        ],
        "summary": "Get memory tag by ID",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Memory tag retrieved"
          },
          "404": {
            "description": "Memory tag not found"
          }
        }
      },
      "put": {
        "tags": [
          "Memory Tags"
        ],
        "summary": "Update memory tag",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Memory tag updated"
          }
        }
      },
      "delete": {
        "tags": [
          "Memory Tags"
        ],
        "summary": "Delete memory tag",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Memory tag deleted"
          }
        }
      }
    },
    "/memory-tags/{id}/toggle-share": {
      "patch": {
        "tags": [
          "Memory Tags"
        ],
        "summary": "Toggle share with caregiver",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Share status toggled"
          }
        }
      }
    },
    "/scans/public": {
      "post": {
        "tags": [
          "Scans"
        ],
        "summary": "Public scan QR code",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "qrcodeId"
                ],
                "properties": {
                  "qrcodeId": {
                    "type": "string"
                  },
                  "location": {
                    "type": "object",
                    "properties": {
                      "latitude": {
                        "type": "number"
                      },
                      "longitude": {
                        "type": "number"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Scan recorded"
          }
        }
      }
    },
    "/scans/geocoded": {
      "post": {
        "tags": [
          "Scans"
        ],
        "summary": "Create a new scan with geocoding",
        "description": "Create a new scan record with geocoded location data. Supports guest scans via 'type=guest' query parameter.",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "guest"
              ]
            },
            "description": "Set to 'guest' to generate a guest token for the scanner"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "qrcode_id",
                  "latitude",
                  "longitude"
                ],
                "properties": {
                  "qrcode_id": {
                    "type": "string",
                    "description": "ID of the scanned QR code"
                  },
                  "qr_code_id": {
                    "type": "string",
                    "description": "Alternative field name for QR code ID"
                  },
                  "qrcodeId": {
                    "type": "string",
                    "description": "Alternative field name for QR code ID"
                  },
                  "latitude": {
                    "type": "string",
                    "description": "Latitude of the scan location"
                  },
                  "longitude": {
                    "type": "string",
                    "description": "Longitude of the scan location"
                  },
                  "device_info": {
                    "type": "string",
                    "description": "Information about the scanning device"
                  },
                  "notes": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "Optional notes about the scan"
                  },
                  "is_anonymous": {
                    "type": "boolean",
                    "default": false,
                    "description": "Whether the scan is anonymous"
                  },
                  "password": {
                    "type": "string",
                    "description": "Password for private QR codes"
                  },
                  "userId": {
                    "type": "string",
                    "description": "User ID (for email notifications)"
                  }
                }
              },
              "examples": {
                "basicGeocodedScan": {
                  "summary": "Basic geocoded scan",
                  "value": {
                    "qrcode_id": "507f1f77bcf86cd799439011",
                    "latitude": "40.7128",
                    "longitude": "-74.0060"
                  }
                },
                "guestScan": {
                  "summary": "Guest scan requesting token",
                  "value": {
                    "qrcode_id": "507f1f77bcf86cd799439011",
                    "latitude": "40.7128",
                    "longitude": "-74.0060",
                    "device_info": "iPhone 14 Pro"
                  }
                },
                "privateQRGeocodedScan": {
                  "summary": "Geocoded scan for PRIVATE QR code",
                  "value": {
                    "qrcode_id": "507f1f77bcf86cd799439011",
                    "latitude": "40.7128",
                    "longitude": "-74.0060",
                    "password": "secret123"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Scan recorded successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/Scan"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "guestToken": {
                              "type": "string",
                              "description": "JWT token for guest user (only if type=guest)"
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "404": {
            "description": "QR code not found"
          }
        }
      }
    },
    "/scans/public/{id}": {
      "get": {
        "tags": [
          "Scans"
        ],
        "summary": "Get public scan details",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Scan details retrieved"
          }
        }
      }
    },
    "/scans/check-access/{qrcodeId}": {
      "get": {
        "tags": [
          "Scans"
        ],
        "summary": "Check QR code access",
        "parameters": [
          {
            "name": "qrcodeId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Access checked"
          }
        }
      }
    },
    "/scans/verify-pin/{id}": {
      "post": {
        "tags": [
          "Scans"
        ],
        "summary": "Verify PIN for protected scan",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "pin"
                ],
                "properties": {
                  "pin": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "PIN verified"
          }
        }
      }
    },
    "/scans": {
      "get": {
        "tags": [
          "Scans"
        ],
        "summary": "Get user scans",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Scans retrieved"
          }
        }
      },
      "post": {
        "tags": [
          "Scans"
        ],
        "summary": "Create authenticated scan",
        "description": "Create a new scan record for a QR code. Supports both camelCase and snake_case field names for API compatibility. For PRIVATE QR codes, include the password field. IP address is automatically detected from the request.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "qr_code_id"
                ],
                "properties": {
                  "qr_code_id": {
                    "type": "string",
                    "description": "QR code ID (MongoDB ObjectId)"
                  },
                  "qrcode_id": {
                    "type": "string",
                    "description": "Alternative field name for QR code ID"
                  },
                  "password": {
                    "type": "string",
                    "description": "Password for PRIVATE or PROTECTED QR codes. Required if the QR code has access_type set to PRIVATE."
                  },
                  "location": {
                    "type": "object",
                    "description": "Geographic location where the scan occurred. City and country are automatically derived from coordinates.",
                    "properties": {
                      "latitude": {
                        "type": "number",
                        "minimum": -90,
                        "maximum": 90,
                        "description": "Latitude coordinate"
                      },
                      "longitude": {
                        "type": "number",
                        "minimum": -180,
                        "maximum": 180,
                        "description": "Longitude coordinate"
                      }
                    }
                  },
                  "scan_location": {
                    "type": "object",
                    "description": "Alternative field name for location"
                  },
                  "device_info": {
                    "type": "string",
                    "description": "Information about the device used for scanning (free-form text, max 255 characters)"
                  },
                  "deviceInfo": {
                    "type": "string",
                    "description": "Alternative field name for device info (string format)"
                  },
                  "ip_address": {
                    "type": "string",
                    "description": "IP address of the scanner (auto-detected if not provided)"
                  },
                  "scanned_by": {
                    "type": "string",
                    "description": "User ID of the scanner (auto-populated from JWT if authenticated)"
                  },
                  "notes": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "Optional notes about the scan"
                  },
                  "is_anonymous": {
                    "type": "boolean",
                    "default": false,
                    "description": "Whether this is an anonymous scan"
                  },
                  "isAnonymous": {
                    "type": "boolean",
                    "description": "Alternative field name for is_anonymous"
                  }
                }
              },
              "examples": {
                "basicScan": {
                  "summary": "Basic scan (minimal fields)",
                  "value": {
                    "qr_code_id": "507f1f77bcf86cd799439011"
                  }
                },
                "scanWithLocation": {
                  "summary": "Scan with location data",
                  "value": {
                    "qr_code_id": "507f1f77bcf86cd799439011",
                    "location": {
                      "latitude": 40.7128,
                      "longitude": -74.006
                    },
                    "device_info": "iPhone 14 Pro"
                  }
                },
                "privateScan": {
                  "summary": "Scan PRIVATE QR code with password",
                  "value": {
                    "qr_code_id": "507f1f77bcf86cd799439011",
                    "password": "secret123",
                    "location": {
                      "latitude": 40.7128,
                      "longitude": -74.006
                    }
                  }
                },
                "fullScan": {
                  "summary": "Complete scan with all fields",
                  "value": {
                    "qr_code_id": "507f1f77bcf86cd799439011",
                    "location": {
                      "latitude": 40.7128,
                      "longitude": -74.006
                    },
                    "device_info": "Samsung Galaxy S23",
                    "notes": "Found at Central Park",
                    "is_anonymous": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Scan recorded successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Scan recorded successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Scan"
                    },
                    "statusCode": {
                      "type": "integer",
                      "example": 201
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or validation error"
          },
          "401": {
            "description": "Invalid password for PRIVATE QR code",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": false
                    },
                    "error": {
                      "type": "string",
                      "example": "Invalid password for private QR code"
                    },
                    "data": {
                      "type": "null"
                    },
                    "statusCode": {
                      "type": "integer",
                      "example": 401
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "QR code not found"
          }
        }
      }
    },
    "/scans/analytics": {
      "get": {
        "tags": [
          "Scans"
        ],
        "summary": "Get scan analytics with filtering and grouping",
        "description": "Retrieve detailed scan analytics with optional filtering by QR code, date range, and grouping options. Returns aggregated statistics including total scans, unique scanners, geographic distribution, and time-based trends.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "qrcode_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter analytics by specific QR code ID (MongoDB ObjectId)"
          },
          {
            "name": "date_from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Start date for analytics period (ISO 8601 format, e.g., 2024-01-01T00:00:00Z)"
          },
          {
            "name": "date_to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "End date for analytics period (ISO 8601 format, e.g., 2024-12-31T23:59:59Z)"
          },
          {
            "name": "group_by",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "day",
                "week",
                "month",
                "year",
                "hour"
              ]
            },
            "description": "Group analytics data by time period for trend analysis"
          }
        ],
        "responses": {
          "200": {
            "description": "Scan analytics retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Scan analytics retrieved successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "totalScans": {
                          "type": "integer",
                          "description": "Total number of scans in the period",
                          "example": 1250
                        },
                        "uniqueScanners": {
                          "type": "integer",
                          "description": "Number of unique users who scanned",
                          "example": 342
                        },
                        "scansByLocation": {
                          "type": "array",
                          "description": "Geographic distribution of scans",
                          "items": {
                            "type": "object",
                            "properties": {
                              "country": {
                                "type": "string",
                                "example": "United States"
                              },
                              "city": {
                                "type": "string",
                                "example": "New York"
                              },
                              "count": {
                                "type": "integer",
                                "example": 45
                              }
                            }
                          }
                        },
                        "scansByQRCode": {
                          "type": "array",
                          "description": "Scans grouped by QR code",
                          "items": {
                            "type": "object",
                            "properties": {
                              "qrcode_id": {
                                "type": "string",
                                "example": "507f1f77bcf86cd799439011"
                              },
                              "title": {
                                "type": "string",
                                "example": "My Pet QR Code"
                              },
                              "count": {
                                "type": "integer",
                                "example": 125
                              }
                            }
                          }
                        },
                        "scansByTimePeriod": {
                          "type": "array",
                          "description": "Time-based scan trends (when group_by is specified)",
                          "items": {
                            "type": "object",
                            "properties": {
                              "period": {
                                "type": "string",
                                "example": "2024-11-20"
                              },
                              "count": {
                                "type": "integer",
                                "example": 87
                              }
                            }
                          }
                        },
                        "averageScansPerDay": {
                          "type": "number",
                          "description": "Average number of scans per day",
                          "example": 41.67
                        },
                        "peakScanTime": {
                          "type": "object",
                          "description": "Time period with highest scan activity",
                          "properties": {
                            "period": {
                              "type": "string",
                              "example": "2024-11-15"
                            },
                            "count": {
                              "type": "integer",
                              "example": 156
                            }
                          }
                        }
                      }
                    },
                    "statusCode": {
                      "type": "integer",
                      "example": 200
                    }
                  }
                },
                "examples": {
                  "allScans": {
                    "summary": "All scans analytics",
                    "value": {
                      "success": true,
                      "message": "Scan analytics retrieved successfully",
                      "data": {
                        "totalScans": 1250,
                        "uniqueScanners": 342,
                        "scansByLocation": [
                          {
                            "country": "United States",
                            "city": "New York",
                            "count": 245
                          },
                          {
                            "country": "United Kingdom",
                            "city": "London",
                            "count": 189
                          }
                        ],
                        "averageScansPerDay": 41.67
                      },
                      "statusCode": 200
                    }
                  },
                  "specificQRCode": {
                    "summary": "Analytics for specific QR code",
                    "value": {
                      "success": true,
                      "message": "Scan analytics retrieved successfully",
                      "data": {
                        "totalScans": 125,
                        "uniqueScanners": 87,
                        "scansByLocation": [
                          {
                            "country": "United States",
                            "city": "Los Angeles",
                            "count": 45
                          }
                        ],
                        "averageScansPerDay": 4.17
                      },
                      "statusCode": 200
                    }
                  },
                  "groupedByDay": {
                    "summary": "Analytics grouped by day",
                    "value": {
                      "success": true,
                      "message": "Scan analytics retrieved successfully",
                      "data": {
                        "totalScans": 450,
                        "scansByTimePeriod": [
                          {
                            "period": "2024-11-18",
                            "count": 87
                          },
                          {
                            "period": "2024-11-19",
                            "count": 92
                          },
                          {
                            "period": "2024-11-20",
                            "count": 105
                          }
                        ],
                        "peakScanTime": {
                          "period": "2024-11-20",
                          "count": 105
                        }
                      },
                      "statusCode": 200
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters"
          },
          "401": {
            "description": "Unauthorized - Invalid or missing JWT token"
          }
        }
      }
    },
    "/scans/{id}": {
      "get": {
        "tags": [
          "Scans"
        ],
        "summary": "Get scan by ID",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Scan retrieved"
          }
        }
      },
      "put": {
        "tags": [
          "Scans"
        ],
        "summary": "Update scan",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "notes": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Scan updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Scan"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Scans"
        ],
        "summary": "Delete scan",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Scan deleted"
          }
        }
      }
    },
    "/admin/get-analytics": {
      "get": {
        "tags": [
          "Admin"
        ],
        "summary": "Get analytics",
        "responses": {
          "200": {
            "description": "Analytics retrieved"
          }
        }
      }
    },
    "/analytics": {
      "get": {
        "tags": [
          "Analytics"
        ],
        "summary": "Get analytics data",
        "description": "Retrieves analytics metrics for specified time periods. The endpoint returns counts for users, QR codes, and media, along with daily breakdowns based on the selected time period (week or month).",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "description": "Time period for analytics data ('week' for the current week or 'month' for the current month)",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "week",
                "month"
              ],
              "default": "week"
            },
            "example": "week"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with analytics data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "Status message",
                      "example": "Request successful"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "totalUsers": {
                          "type": "integer",
                          "description": "Total number of users with profile completion",
                          "example": 150
                        },
                        "totalQrCodes": {
                          "type": "integer",
                          "description": "Total number of active QR codes",
                          "example": 320
                        },
                        "mediaCount": {
                          "type": "integer",
                          "description": "Total number of media files",
                          "example": 1200
                        },
                        "dailyAnalytics": {
                          "type": "array",
                          "description": "Daily analytics breakdown for the selected period",
                          "items": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string",
                                "description": "Name of the day or date identifier",
                                "example": "Mon"
                              },
                              "scans": {
                                "type": "integer",
                                "description": "Number of scans for the day",
                                "example": 0
                              },
                              "users": {
                                "type": "integer",
                                "description": "Number of users for the day",
                                "example": 0
                              }
                            },
                            "required": [
                              "name",
                              "scans",
                              "users"
                            ]
                          }
                        }
                      },
                      "required": [
                        "totalUsers",
                        "totalQrCodes",
                        "mediaCount",
                        "dailyAnalytics"
                      ]
                    },
                    "statusCode": {
                      "type": "integer",
                      "description": "HTTP status code",
                      "example": 200
                    }
                  },
                  "required": [
                    "message",
                    "data",
                    "statusCode"
                  ]
                },
                "example": {
                  "message": "Request successful",
                  "data": {
                    "totalUsers": 150,
                    "totalQrCodes": 320,
                    "mediaCount": 1200,
                    "dailyAnalytics": [
                      {
                        "name": "Sun",
                        "scans": 45,
                        "users": 12
                      },
                      {
                        "name": "Mon",
                        "scans": 67,
                        "users": 23
                      },
                      {
                        "name": "Tue",
                        "scans": 89,
                        "users": 31
                      },
                      {
                        "name": "Wed",
                        "scans": 56,
                        "users": 18
                      },
                      {
                        "name": "Thu",
                        "scans": 78,
                        "users": 25
                      },
                      {
                        "name": "Fri",
                        "scans": 102,
                        "users": 35
                      },
                      {
                        "name": "Sat",
                        "scans": 91,
                        "users": 29
                      }
                    ]
                  },
                  "statusCode": 200
                }
              }
            }
          },
          "400": {
            "description": "Invalid analytics type parameter",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "Error message",
                      "example": "Invalid analytics type. Must be 'week' or 'month'."
                    },
                    "data": {
                      "type": "object",
                      "nullable": true
                    },
                    "statusCode": {
                      "type": "integer",
                      "description": "HTTP status code",
                      "example": 400
                    }
                  },
                  "required": [
                    "message",
                    "data",
                    "statusCode"
                  ]
                },
                "example": {
                  "message": "Invalid analytics type. Must be 'week' or 'month'.",
                  "data": null,
                  "statusCode": 400
                }
              }
            }
          }
        }
      }
    },
    "/admin/users": {
      "get": {
        "tags": [
          "Admin"
        ],
        "summary": "Get all users",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Users retrieved"
          },
          "403": {
            "description": "Admin access required"
          }
        }
      }
    },
    "/admin/analytics": {
      "get": {
        "tags": [
          "Admin"
        ],
        "summary": "Get admin analytics",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Analytics retrieved"
          }
        }
      }
    },
    "/admin/qrcodes": {
      "get": {
        "tags": [
          "Admin"
        ],
        "summary": "Get all QR codes",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "QR codes retrieved"
          }
        }
      }
    },
    "/admin/qrcode/{id}": {
      "delete": {
        "tags": [
          "Admin"
        ],
        "summary": "Delete QR code (soft delete)",
        "description": "Soft delete a QR code by setting isDelete to true and status to INACTIVE. The QR code data is preserved but marked as deleted. Only admins can perform this action.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "QR code ID (MongoDB ObjectId)",
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-fA-F]{24}$"
            },
            "examples": {
              "validId": {
                "summary": "Valid QR code ID",
                "value": "507f1f77bcf86cd799439011"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "QR code deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Successful deletion",
                    "value": {
                      "success": true,
                      "message": "QR code deleted successfully",
                      "data": null,
                      "code": 200
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid QR code ID format",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidId": {
                    "summary": "Invalid ID format",
                    "value": {
                      "success": false,
                      "message": "Invalid QR code ID",
                      "data": null,
                      "code": 400
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found - QR code not found or already deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "notFound": {
                    "summary": "QR code not found",
                    "value": {
                      "success": false,
                      "message": "QR code not found or already deleted",
                      "data": null,
                      "code": 404
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Admin authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/admin/media": {
      "get": {
        "tags": [
          "Admin"
        ],
        "summary": "Get all media",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Media retrieved"
          }
        }
      }
    },
    "/admin-document": {
      "post": {
        "tags": [
          "Admin Document"
        ],
        "summary": "Upload admin document",
        "description": "Upload a document for admin use. Supported document types: company-profile, terms-and-conditions, privacy-policy, financial-report, marketing-presentation. If a document of the same type already exists, it will be replaced.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "document",
                  "type"
                ],
                "properties": {
                  "document": {
                    "type": "string",
                    "format": "binary",
                    "description": "Document file to upload"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "company-profile",
                      "terms-and-conditions",
                      "privacy-policy",
                      "financial-report",
                      "marketing-presentation"
                    ],
                    "description": "Type of document"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Document uploaded successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing file or document type"
          },
          "401": {
            "description": "Unauthorized - admin authentication required"
          }
        }
      },
      "get": {
        "tags": [
          "Admin Document"
        ],
        "summary": "Get all admin documents",
        "description": "Retrieve all admin documents with pagination and search functionality. Supports searching by document type or file name.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1
            },
            "description": "Page number for pagination"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10,
              "minimum": 1,
              "maximum": 100
            },
            "description": "Number of documents per page"
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Search term to filter documents by type or file name"
          }
        ],
        "responses": {
          "200": {
            "description": "Documents retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - admin authentication required"
          }
        }
      }
    },
    "/admin-document/{id}": {
      "get": {
        "tags": [
          "Admin Document"
        ],
        "summary": "Get admin document by ID",
        "description": "Retrieve a specific admin document by ID. Returns document information including download URL. The download count will be incremented.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Admin document ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Document retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "404": {
            "description": "Document not found"
          },
          "401": {
            "description": "Unauthorized - admin authentication required"
          }
        }
      },
      "delete": {
        "tags": [
          "Admin Document"
        ],
        "summary": "Delete admin document",
        "description": "Delete an admin document by ID. This will also delete the associated media file from the filesystem. Requires admin authentication.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Admin document ID to delete"
          }
        ],
        "responses": {
          "200": {
            "description": "Document deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "404": {
            "description": "Document not found"
          },
          "401": {
            "description": "Unauthorized - admin authentication required"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/admin-document/{id}/download": {
      "get": {
        "tags": [
          "Admin Document"
        ],
        "summary": "Download admin document",
        "description": "Download an admin document by ID as a file stream. Requires admin authentication. The download count will be incremented.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Admin document ID to download"
          }
        ],
        "responses": {
          "200": {
            "description": "File stream",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "Document not found"
          },
          "401": {
            "description": "Unauthorized - admin authentication required"
          }
        }
      }
    },
    "/admin/user/{id}": {
      "delete": {
        "tags": [
          "Admin"
        ],
        "summary": "Delete user",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "User deleted"
          }
        }
      }
    },
    "/admin/user/{id}/status": {
      "patch": {
        "tags": [
          "Admin"
        ],
        "summary": "Change user status",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "status"
                ],
                "properties": {
                  "status": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "User status changed"
          }
        }
      }
    },
    "/admin/admin-analytics": {
      "get": {
        "tags": [
          "Admin"
        ],
        "summary": "Get comprehensive admin analytics",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Admin analytics retrieved"
          }
        }
      }
    },
    "/admin/admin-analytics-document": {
      "get": {
        "tags": [
          "Admin"
        ],
        "summary": "Generate admin analytics PDF document",
        "description": "Generate a comprehensive PDF document containing admin analytics data. The PDF includes KPIs, summary statistics, daily analytics, QR code type distribution, recent activity, and top performing QR codes. The document features the Quick Connect logo and is formatted for professional presentation.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "period",
            "in": "query",
            "description": "Time period for analytics. Options: 7days, 30days, 90days, year",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "7days",
                "30days",
                "90days",
                "year"
              ],
              "default": "7days"
            },
            "examples": {
              "7days": {
                "summary": "Last 7 days",
                "value": "7days"
              },
              "30days": {
                "summary": "Last 30 days",
                "value": "30days"
              },
              "90days": {
                "summary": "Last 90 days",
                "value": "90days"
              },
              "year": {
                "summary": "Last year",
                "value": "year"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "PDF document generated successfully",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                },
                "example": "PDF binary data"
              }
            },
            "headers": {
              "Content-Disposition": {
                "schema": {
                  "type": "string"
                },
                "description": "Attachment filename"
              }
            }
          },
          "400": {
            "description": "Invalid period parameter",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": false
                    },
                    "message": {
                      "type": "string",
                      "example": "Invalid period. Must be one of: 7days, 30days, 90days, year"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - User not authenticated"
          },
          "403": {
            "description": "Forbidden - Admin privileges required"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/admin/qrcode-pdf-report": {
      "get": {
        "tags": [
          "Admin"
        ],
        "summary": "Generate QR code PDF report",
        "description": "Generate a comprehensive PDF report for QR code metrics and statistics. Supports three generation modes: on-demand (all active QR codes), daily (last 30 days), and custom (specific date range or QR code ID). The report includes executive summary, top QR codes by scan count, and recent scan activity logs.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "mode",
            "in": "query",
            "description": "Report generation mode. 'on-demand' exports all active QR codes, 'daily' generates summary for QR codes created in last 30 days, 'custom' allows specific date range or QR code ID filtering",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "on-demand",
                "daily",
                "custom"
              ],
              "default": "on-demand"
            },
            "examples": {
              "onDemand": {
                "summary": "On-demand export",
                "value": "on-demand"
              },
              "daily": {
                "summary": "Daily summary",
                "value": "daily"
              },
              "custom": {
                "summary": "Custom date range",
                "value": "custom"
              }
            }
          },
          {
            "name": "qrcodeId",
            "in": "query",
            "description": "Specific QR code ID to generate report for (only used in custom mode)",
            "required": false,
            "schema": {
              "type": "string",
              "format": "objectid"
            },
            "example": "507f1f77bcf86cd799439011"
          },
          {
            "name": "startDate",
            "in": "query",
            "description": "Start date for custom mode (ISO format: YYYY-MM-DD or YYYY-MM-DDTHH:mm:ss). Required when mode is 'custom'",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2024-01-01T00:00:00Z"
          },
          {
            "name": "endDate",
            "in": "query",
            "description": "End date for custom mode (ISO format: YYYY-MM-DD or YYYY-MM-DDTHH:mm:ss). Required when mode is 'custom'",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2024-01-31T23:59:59Z"
          }
        ],
        "responses": {
          "200": {
            "description": "PDF report generated successfully. Returns PDF file with Content-Type: application/pdf",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                },
                "example": "PDF binary content"
              }
            },
            "headers": {
              "Content-Type": {
                "schema": {
                  "type": "string",
                  "example": "application/pdf"
                },
                "description": "MIME type of the response"
              },
              "Content-Disposition": {
                "schema": {
                  "type": "string",
                  "example": "attachment; filename=\"qrcode-report-on-demand-2024-01-15.pdf\""
                },
                "description": "Filename for the downloaded PDF"
              }
            }
          },
          "400": {
            "description": "Invalid parameters (invalid mode, missing dates for custom mode, invalid date format, or startDate after endDate)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": false
                    },
                    "message": {
                      "type": "string",
                      "example": "Invalid mode. Must be 'on-demand', 'daily', or 'custom'."
                    }
                  }
                },
                "examples": {
                  "invalidMode": {
                    "summary": "Invalid mode parameter",
                    "value": {
                      "success": false,
                      "message": "Invalid mode. Must be 'on-demand', 'daily', or 'custom'."
                    }
                  },
                  "missingDates": {
                    "summary": "Missing dates for custom mode",
                    "value": {
                      "success": false,
                      "message": "startDate and endDate are required for custom mode"
                    }
                  },
                  "invalidDateFormat": {
                    "summary": "Invalid date format",
                    "value": {
                      "success": false,
                      "message": "Invalid date format. Use ISO format (YYYY-MM-DD or YYYY-MM-DDTHH:mm:ss)"
                    }
                  },
                  "invalidDateRange": {
                    "summary": "Start date after end date",
                    "value": {
                      "success": false,
                      "message": "startDate must be before endDate"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Failed to generate PDF report (database query failure, PDF generation error, or internal server error)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": false
                    },
                    "message": {
                      "type": "string",
                      "example": "Failed to generate QR code PDF report"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/admin/user-behavior-pdf": {
      "get": {
        "tags": [
          "Admin"
        ],
        "summary": "Generate user behavior PDF report",
        "description": "Generate a comprehensive PDF report based on user behavior analytics. The report includes login activity, user registrations, QR code creations, scan activity, top active users, security events, and daily activity breakdown.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "timePeriod",
            "in": "query",
            "description": "Time period for the report",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1d",
                "7d",
                "30d"
              ],
              "default": "30d"
            }
          },
          {
            "name": "startDate",
            "in": "query",
            "description": "Optional start date (ISO format). If not provided, calculated based on timePeriod",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "endDate",
            "in": "query",
            "description": "Optional end date (ISO format). If not provided, uses current date",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "PDF report generated successfully. Returns a download URL.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "User behavior PDF report generated successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "downloadUrl": {
                          "type": "string",
                          "format": "uri",
                          "example": "http://localhost:3002/uploads/reports/user-behavior-report-30d-2024-01-15-1234567890-987654321.pdf",
                          "description": "URL to download the generated PDF report"
                        },
                        "filename": {
                          "type": "string",
                          "example": "user-behavior-report-30d-2024-01-15-1234567890-987654321.pdf",
                          "description": "Name of the generated PDF file"
                        },
                        "timePeriod": {
                          "type": "string",
                          "example": "30d",
                          "description": "Time period used for the report"
                        },
                        "generatedAt": {
                          "type": "string",
                          "format": "date-time",
                          "example": "2024-01-15T10:30:00.000Z",
                          "description": "Timestamp when the report was generated"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid time period or date parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": false
                    },
                    "message": {
                      "type": "string",
                      "example": "Invalid time period. Must be '1d', '7d', or '30d'."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Failed to generate PDF report",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": false
                    },
                    "message": {
                      "type": "string",
                      "example": "Failed to generate user behavior PDF report"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/admin/notifications/toggle": {
      "post": {
        "tags": [
          "Admin"
        ],
        "summary": "Toggle admin notifications",
        "description": "Enable or disable admin notifications. When disabled, the admin will not receive system notifications (e.g., critical logs, medical document uploads). This is separate from general push notifications.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Admin notification preference updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Admin notifications enabled successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "adminNotificationsEnabled": {
                          "type": "boolean",
                          "example": true,
                          "description": "Current state of admin notifications (true = enabled, false = disabled)"
                        }
                      }
                    },
                    "code": {
                      "type": "integer",
                      "example": 200
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - User not authenticated"
          },
          "403": {
            "description": "Forbidden - Admin privileges required"
          },
          "404": {
            "description": "User not found"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/admin/notifications/status": {
      "get": {
        "tags": [
          "Admin"
        ],
        "summary": "Get admin notification status",
        "description": "Retrieve the current admin notification preference. Returns whether admin notifications are enabled or disabled.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Admin notification status retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Admin notification status retrieved successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "adminNotificationsEnabled": {
                          "type": "boolean",
                          "example": true,
                          "description": "Current state of admin notifications (true = enabled, false = disabled)"
                        }
                      }
                    },
                    "code": {
                      "type": "integer",
                      "example": 200
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - User not authenticated"
          },
          "403": {
            "description": "Forbidden - Admin privileges required"
          },
          "404": {
            "description": "User not found"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/notifications": {
      "get": {
        "tags": [
          "Notifications"
        ],
        "summary": "Get notifications with pagination and filters",
        "description": "Retrieve user notifications with optional filtering by read status and type. Supports pagination.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "description": "Page number for pagination",
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of notifications per page (default returns all)",
            "schema": {
              "type": "integer",
              "default": 2147483647,
              "minimum": 1
            }
          },
          {
            "name": "is_read",
            "in": "query",
            "description": "Filter by read status",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "Filter by notification type. UNREAD returns only unread notifications, DEFAULT returns all",
            "schema": {
              "type": "string",
              "enum": [
                "MESSAGE",
                "EMERGENCY",
                "QRSCAN",
                "MEMORY",
                "GENERAL",
                "DEFAULT",
                "UNREAD"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Notifications retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Notifications retrieved successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "notifications": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "_id": {
                                "type": "string",
                                "example": "507f1f77bcf86cd799439011"
                              },
                              "title": {
                                "type": "string",
                                "example": "QR Code Scanned"
                              },
                              "message": {
                                "type": "string",
                                "example": "Your QR code 'My Car QR' was scanned"
                              },
                              "type": {
                                "type": "string",
                                "example": "QRSCAN"
                              },
                              "link": {
                                "type": "string",
                                "example": "/qrcodes/507f1f77bcf86cd799439011"
                              },
                              "is_read": {
                                "type": "boolean",
                                "example": false
                              },
                              "user_id": {
                                "type": "string",
                                "example": "507f1f77bcf86cd799439011"
                              },
                              "qrcode_id": {
                                "type": "string",
                                "example": "507f1f77bcf86cd799439011"
                              },
                              "qrcode": {
                                "type": "object",
                                "properties": {
                                  "_id": {
                                    "type": "string"
                                  },
                                  "title": {
                                    "type": "string"
                                  },
                                  "type": {
                                    "type": "string"
                                  }
                                }
                              },
                              "push_sent": {
                                "type": "boolean",
                                "example": true
                              },
                              "push_sent_at": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "data": {
                                "type": "object"
                              },
                              "created_at": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "updated_at": {
                                "type": "string",
                                "format": "date-time"
                              }
                            }
                          }
                        },
                        "total": {
                          "type": "integer",
                          "example": 25
                        },
                        "page": {
                          "type": "integer",
                          "example": 1
                        },
                        "limit": {
                          "type": "integer",
                          "example": 10
                        },
                        "totalPages": {
                          "type": "integer",
                          "example": 3
                        },
                        "unreadCount": {
                          "type": "integer",
                          "example": 5
                        },
                        "EnabledNotification": {
                          "type": "boolean",
                          "example": true
                        }
                      }
                    },
                    "statusCode": {
                      "type": "integer",
                      "example": 200
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing token"
          }
        }
      },
      "post": {
        "tags": [
          "Notifications"
        ],
        "summary": "Create a new notification",
        "description": "Create a notification for a user. Regular users can only create notifications for themselves. Admin users can create notifications for any user.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title",
                  "message"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "Notification title",
                    "example": "QR Code Scanned"
                  },
                  "message": {
                    "type": "string",
                    "description": "Notification message content",
                    "example": "Your QR code was scanned at New York, NY"
                  },
                  "type": {
                    "type": "string",
                    "description": "Notification type",
                    "enum": [
                      "MESSAGE",
                      "EMERGENCY",
                      "QRSCAN",
                      "MEMORY",
                      "GENERAL"
                    ],
                    "default": "GENERAL",
                    "example": "QRSCAN"
                  },
                  "link": {
                    "type": "string",
                    "description": "Optional link to navigate to",
                    "example": "/qrcodes/507f1f77bcf86cd799439011"
                  },
                  "user_id": {
                    "type": "string",
                    "description": "Target user ID (admin only)",
                    "example": "507f1f77bcf86cd799439011"
                  },
                  "qrcode_id": {
                    "type": "string",
                    "description": "Associated QR code ID",
                    "example": "507f1f77bcf86cd799439011"
                  },
                  "data": {
                    "type": "object",
                    "description": "Additional custom data",
                    "example": {
                      "location": "New York, NY",
                      "device": "iPhone 14 Pro"
                    }
                  },
                  "sendPush": {
                    "type": "boolean",
                    "description": "Whether to send push notification",
                    "default": true,
                    "example": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Notification created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Notification created successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "_id": {
                          "type": "string"
                        },
                        "title": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string"
                        },
                        "is_read": {
                          "type": "boolean"
                        },
                        "push_sent": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid input"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/notifications/unread-count": {
      "get": {
        "tags": [
          "Notifications"
        ],
        "summary": "Get unread notification count",
        "description": "Retrieve the total count of unread notifications for the authenticated user",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Unread count retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Unread count retrieved successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer",
                          "example": 5
                        }
                      }
                    },
                    "statusCode": {
                      "type": "integer",
                      "example": 200
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/notifications/push-status": {
      "get": {
        "tags": [
          "Notifications"
        ],
        "summary": "Get push notification status",
        "description": "Check if push notifications are enabled for the authenticated user",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Push notification status retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Push notification status retrieved successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "pushNotificationsEnabled": {
                          "type": "boolean",
                          "example": true
                        }
                      }
                    },
                    "statusCode": {
                      "type": "integer",
                      "example": 200
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/notifications/push-toggle": {
      "patch": {
        "tags": [
          "Notifications"
        ],
        "summary": "Toggle push notifications",
        "description": "Enable or disable push notifications for the authenticated user. Toggles the current state automatically.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Push notifications toggled successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Push notifications enabled successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "pushNotificationsEnabled": {
                          "type": "boolean",
                          "example": true
                        }
                      }
                    },
                    "statusCode": {
                      "type": "integer",
                      "example": 200
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/notifications/{id}/read": {
      "patch": {
        "tags": [
          "Notifications"
        ],
        "summary": "Mark notification as read",
        "description": "Mark a specific notification as read for the authenticated user",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Notification ID",
            "schema": {
              "type": "string"
            },
            "example": "507f1f77bcf86cd799439011"
          }
        ],
        "responses": {
          "200": {
            "description": "Notification marked as read successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Notification marked as read"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "_id": {
                          "type": "string"
                        },
                        "is_read": {
                          "type": "boolean",
                          "example": true
                        }
                      }
                    },
                    "statusCode": {
                      "type": "integer",
                      "example": 200
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Notification not found"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/notifications/mark-all-read": {
      "patch": {
        "tags": [
          "Notifications"
        ],
        "summary": "Mark all notifications as read",
        "description": "Mark all unread notifications as read for the authenticated user",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "All notifications marked as read successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "5 notifications marked as read"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer",
                          "description": "Number of notifications marked as read",
                          "example": 5
                        }
                      }
                    },
                    "statusCode": {
                      "type": "integer",
                      "example": 200
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/notifications/{id}": {
      "delete": {
        "tags": [
          "Notifications"
        ],
        "summary": "Delete notification",
        "description": "Delete a specific notification for the authenticated user",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Notification ID to delete",
            "schema": {
              "type": "string"
            },
            "example": "507f1f77bcf86cd799439011"
          }
        ],
        "responses": {
          "200": {
            "description": "Notification deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Notification deleted successfully"
                    },
                    "statusCode": {
                      "type": "integer",
                      "example": 200
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Notification not found"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/dashboard/cards": {
      "get": {
        "tags": [
          "Dashboard"
        ],
        "summary": "Get dashboard cards",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Dashboard cards retrieved"
          }
        }
      }
    },
    "/dashboard/analytics": {
      "get": {
        "tags": [
          "Dashboard"
        ],
        "summary": "Get dashboard analytics",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Dashboard analytics retrieved"
          }
        }
      }
    },
    "/subscription/all": {
      "get": {
        "tags": [
          "Subscription"
        ],
        "summary": "Get all subscription packages",
        "responses": {
          "200": {
            "description": "Subscription packages retrieved"
          }
        }
      }
    },
    "/subscription/my-subscriptions": {
      "get": {
        "tags": [
          "Subscription"
        ],
        "summary": "Get user subscriptions",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "User subscriptions retrieved"
          }
        }
      }
    },
    "/subscription/status": {
      "get": {
        "tags": [
          "Subscription"
        ],
        "summary": "Get subscription status",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Subscription status retrieved"
          }
        }
      }
    },
    "/subscription/tier": {
      "get": {
        "tags": [
          "Subscription"
        ],
        "summary": "Get subscription tier",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Subscription tier retrieved"
          }
        }
      }
    },
    "/subscription/stats": {
      "get": {
        "tags": [
          "Subscription"
        ],
        "summary": "Get subscription statistics",
        "responses": {
          "200": {
            "description": "Subscription statistics retrieved"
          }
        }
      }
    },
    "/subscription/checkout-session": {
      "post": {
        "tags": [
          "Subscription"
        ],
        "summary": "Create checkout session",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "priceId"
                ],
                "properties": {
                  "priceId": {
                    "type": "string",
                    "description": "Stripe Price ID for the subscription"
                  },
                  "successUrl": {
                    "type": "string",
                    "description": "URL to redirect after successful checkout (defaults to origin/success?session_id={CHECKOUT_SESSION_ID})"
                  },
                  "cancelUrl": {
                    "type": "string",
                    "description": "URL to redirect after cancelled checkout (defaults to origin/cancel)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Checkout session created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "sessionId": {
                          "type": "string",
                          "description": "ID of the created checkout session"
                        },
                        "url": {
                          "type": "string",
                          "description": "URL to redirect the user to complete checkout"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/subscription/cleanup": {
      "post": {
        "tags": [
          "Subscription"
        ],
        "summary": "Cleanup duplicate subscriptions",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Cleanup completed"
          }
        }
      }
    },
    "/subscription/cancel/{subscriptionId}": {
      "delete": {
        "tags": [
          "Subscription"
        ],
        "summary": "Cancel subscription",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "subscriptionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Subscription cancelled"
          }
        }
      }
    },
    "/subscription/check-expired": {
      "post": {
        "tags": [
          "Subscription"
        ],
        "summary": "Check expired subscriptions",
        "responses": {
          "200": {
            "description": "Expired subscriptions checked"
          }
        }
      }
    },
    "/subscription/sync-tier": {
      "post": {
        "tags": [
          "Subscription"
        ],
        "summary": "Sync subscription tier",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Subscription tier synced"
          }
        }
      }
    },
    "/webhooks/stripe": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Handle Stripe webhook",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string"
                  },
                  "data": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook processed"
          },
          "400": {
            "description": "Invalid webhook"
          }
        }
      }
    },
    "/logging": {
      "get": {
        "tags": [
          "Logging"
        ],
        "summary": "Get logs with filtering options",
        "description": "Retrieve logs with optional filtering by module, level, admin ID, user ID, and date range. Supports pagination.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "module",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by module name"
          },
          {
            "name": "level",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "INFO",
                "WARN",
                "ERROR",
                "DEBUG",
                "CRITICAL"
              ]
            },
            "description": "Filter by log level"
          },
          {
            "name": "admin_id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by admin ID"
          },
          {
            "name": "user_id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by user ID"
          },
          {
            "name": "startDate",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Start date for date range filter"
          },
          {
            "name": "endDate",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "End date for date range filter"
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1
            },
            "description": "Page number for pagination"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 1000
            },
            "description": "Number of logs per page"
          }
        ],
        "responses": {
          "200": {
            "description": "Logs retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LogsResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing authentication token"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      },
      "post": {
        "tags": [
          "Logging"
        ],
        "summary": "Create a manual log entry",
        "description": "Create a new log entry manually. ERROR and CRITICAL logs will trigger push notifications to the admin.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateLogRequest"
              },
              "examples": {
                "infoLog": {
                  "summary": "Info level log",
                  "value": {
                    "module": "UserService",
                    "level": "INFO",
                    "action": "User profile updated successfully",
                    "metadata": {
                      "userId": "1234567890abcdef",
                      "changes": [
                        "email",
                        "phone"
                      ]
                    }
                  }
                },
                "errorLog": {
                  "summary": "Error level log",
                  "value": {
                    "module": "PaymentService",
                    "level": "ERROR",
                    "action": "Payment processing failed",
                    "error_details": {
                      "error": "Stripe API error",
                      "code": "card_declined"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Log entry created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LogEntry"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid input data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing authentication token"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/logging/admin": {
      "get": {
        "tags": [
          "Logging"
        ],
        "summary": "Get logs for default admin",
        "description": "Retrieve logs specific to the default admin user (ID: 694564d876661ff3f9b4887f) with optional filtering.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "module",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by module name"
          },
          {
            "name": "level",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "INFO",
                "WARN",
                "ERROR",
                "DEBUG",
                "CRITICAL"
              ]
            },
            "description": "Filter by log level"
          },
          {
            "name": "startDate",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Start date for date range filter"
          },
          {
            "name": "endDate",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "End date for date range filter"
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            },
            "description": "Page number for pagination"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            },
            "description": "Number of logs per page"
          }
        ],
        "responses": {
          "200": {
            "description": "Admin logs retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LogsResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Admin not found"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/logging/admin/{adminId}": {
      "get": {
        "tags": [
          "Logging"
        ],
        "summary": "Get logs for specific admin",
        "description": "Retrieve logs for a specific admin user by ID with optional filtering.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "adminId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Admin user ID"
          },
          {
            "name": "module",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by module name"
          },
          {
            "name": "level",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "INFO",
                "WARN",
                "ERROR",
                "DEBUG",
                "CRITICAL"
              ]
            },
            "description": "Filter by log level"
          },
          {
            "name": "startDate",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Start date for date range filter"
          },
          {
            "name": "endDate",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "End date for date range filter"
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            },
            "description": "Page number for pagination"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            },
            "description": "Number of logs per page"
          }
        ],
        "responses": {
          "200": {
            "description": "Admin logs retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LogsResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Admin not found"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/logging/statistics": {
      "get": {
        "tags": [
          "Logging"
        ],
        "summary": "Get log statistics",
        "description": "Retrieve aggregated statistics about logs including counts by level and module.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "startDate",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Start date for statistics calculation"
          },
          {
            "name": "endDate",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "End date for statistics calculation"
          },
          {
            "name": "module",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter statistics by module"
          }
        ],
        "responses": {
          "200": {
            "description": "Statistics retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LogStatistics"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/logging/detail-pdf": {
      "get": {
        "tags": [
          "Logging"
        ],
        "summary": "Generate PDF report for admin logs",
        "description": "Generate a detailed PDF report of logging data for admin users. Includes formatted tables, summaries, and timestamps. Filters can be applied via query parameters.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "module",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by module name"
          },
          {
            "name": "level",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "INFO",
                "WARN",
                "ERROR",
                "DEBUG",
                "CRITICAL"
              ]
            },
            "description": "Filter by log level"
          },
          {
            "name": "startDate",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Start date for date range filter"
          },
          {
            "name": "endDate",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "End date for date range filter"
          }
        ],
        "responses": {
          "200": {
            "description": "PDF report generated successfully",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing authentication token"
          },
          "404": {
            "description": "No logs found matching criteria"
          },
          "500": {
            "description": "Internal server error during PDF generation"
          }
        }
      }
    },
    "/multi-profile-setup/create-family": {
      "post": {
        "tags": [
          "Family"
        ],
        "summary": "Create or update a family",
        "description": "Creates a new family with the authenticated user as the owner, or updates the existing family if one already exists for the user. Requires family subscription tier.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "familyName"
                ],
                "properties": {
                  "familyName": {
                    "type": "string",
                    "description": "Name of the family"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Family updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Family updated successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Family"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Family created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Family created successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Family"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Family subscription required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Family already exists for user (in case of implementation that doesn't allow updates)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/multi-profile-setup/family/{id}": {
      "get": {
        "tags": [
          "Family"
        ],
        "summary": "Get family by ID",
        "description": "Retrieves a family by its ID. User must be a member of the family to access it. Requires family subscription tier.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Family ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Family retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Family retrieved successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Family"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid family ID format",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Access denied: User is not part of this family",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Family not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/multi-profile-setup/create-family-member": {
      "post": {
        "tags": [
          "Family"
        ],
        "summary": "Add a member to a family",
        "description": "Adds a new member to an existing family. Only family owners can add members. Requires family management subscription tier.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "familyId",
                  "name",
                  "email"
                ],
                "properties": {
                  "familyId": {
                    "type": "string",
                    "description": "ID of the family to add the member to"
                  },
                  "name": {
                    "type": "string",
                    "description": "Name of the family member"
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "Email of the family member"
                  },
                  "role": {
                    "type": "string",
                    "enum": [
                      "MEMBER",
                      "SPOUSE",
                      "CHILD",
                      "WIFE",
                      "RELATIVES"
                    ],
                    "description": "Role of the family member (default: MEMBER)"
                  },
                  "memberUserId": {
                    "type": "string",
                    "description": "ID of the user to add as a family member (optional, defaults to authenticated user)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Family member added successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Family member added successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Family"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Access denied: Only family owners can add members or family management feature not available on current tier",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/multi-profile-setup/family-members/{familyId}": {
      "get": {
        "tags": [
          "Family"
        ],
        "summary": "Get all members of a family",
        "description": "Retrieves all members of a specified family. User must be part of the family to access member information. Requires family management subscription tier.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "familyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the family"
          }
        ],
        "responses": {
          "200": {
            "description": "Family members retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Family members retrieved successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/FamilyMember"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid family ID format",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Access denied: User is not part of this family or family management feature not available on current tier",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Family not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/multi-profile-setup/family-member/{id}": {
      "put": {
        "tags": [
          "Family"
        ],
        "summary": "Update a family member",
        "description": "Updates an existing family member's information. Only family owners can update members. Requires family management subscription tier.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the family member to update"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Updated name of the family member"
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "Updated email of the family member"
                  },
                  "familyRole": {
                    "type": "string",
                    "enum": [
                      "MEMBER",
                      "SPOUSE",
                      "CHILD",
                      "WIFE",
                      "RELATIVES"
                    ],
                    "description": "Updated role of the family member"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Family member updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Family member updated successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/FamilyMember"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Access denied: Only family owners can update members or family management feature not available on current tier",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Family member not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Family"
        ],
        "summary": "Remove a family member",
        "description": "Removes a member from a family. Only family owners can remove members. Requires family management subscription tier.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID of the family member to remove"
          }
        ],
        "responses": {
          "200": {
            "description": "Family member removed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Family member removed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Family"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid family member ID format",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Access denied: Only family owners can remove members or family management feature not available on current tier",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Family member not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/help-and-feedback/contact": {
      "post": {
        "tags": [
          "Help and Feedback"
        ],
        "summary": "Create a new contact/feedback entry",
        "description": "Allows users to submit contact requests or feedback. This is a public endpoint that does not require authentication.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "email",
                  "message"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "User's name"
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "User's email address"
                  },
                  "message": {
                    "type": "string",
                    "description": "The feedback or contact message"
                  },
                  "subject": {
                    "type": "string",
                    "description": "Subject of the message (optional)"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "feedback",
                      "support",
                      "bug",
                      "feature_request"
                    ],
                    "description": "Type of contact (optional)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Contact/feedback entry created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Contact request submitted successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "_id": {
                          "type": "string",
                          "example": "507f1f77bcf86cd799439011"
                        },
                        "name": {
                          "type": "string",
                          "example": "John Doe"
                        },
                        "email": {
                          "type": "string",
                          "format": "email",
                          "example": "john@example.com"
                        },
                        "message": {
                          "type": "string",
                          "example": "This is a feedback message"
                        },
                        "status": {
                          "type": "string",
                          "example": "OPEN"
                        },
                        "priority": {
                          "type": "string",
                          "example": "MEDIUM"
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input data"
          }
        }
      }
    },
    "/help-and-feedback/export/pdf": {
      "get": {
        "tags": [
          "Help and Feedback"
        ],
        "summary": "Export help and feedback data as PDF",
        "description": "Generates a PDF report of help and feedback data. Requires authentication.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "PDF report generated successfully",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing token"
          },
          "500": {
            "description": "Internal server error during PDF generation"
          }
        }
      }
    },
    "/help-and-feedback/contacts": {
      "get": {
        "tags": [
          "Help and Feedback"
        ],
        "summary": "Get all contacts/feedback entries",
        "description": "Retrieve a list of all contact/feedback entries. Requires authentication.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            },
            "description": "Page number for pagination"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10
            },
            "description": "Number of items per page"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "OPEN",
                "IN_PROGRESS",
                "RESOLVED",
                "CLOSED"
              ]
            },
            "description": "Filter by status"
          },
          {
            "name": "priority",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "LOW",
                "MEDIUM",
                "HIGH",
                "CRITICAL"
              ]
            },
            "description": "Filter by priority"
          }
        ],
        "responses": {
          "200": {
            "description": "Contacts/feedback entries retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Contacts retrieved successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "contacts": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "_id": {
                                "type": "string",
                                "example": "507f1f77bcf86cd799439011"
                              },
                              "name": {
                                "type": "string",
                                "example": "John Doe"
                              },
                              "email": {
                                "type": "string",
                                "format": "email",
                                "example": "john@example.com"
                              },
                              "message": {
                                "type": "string",
                                "example": "This is a feedback message"
                              },
                              "status": {
                                "type": "string",
                                "example": "OPEN"
                              },
                              "priority": {
                                "type": "string",
                                "example": "MEDIUM"
                              },
                              "type": {
                                "type": "string",
                                "example": "feedback"
                              },
                              "created_at": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "updated_at": {
                                "type": "string",
                                "format": "date-time"
                              }
                            }
                          }
                        },
                        "total": {
                          "type": "integer",
                          "example": 50
                        },
                        "page": {
                          "type": "integer",
                          "example": 1
                        },
                        "limit": {
                          "type": "integer",
                          "example": 10
                        },
                        "totalPages": {
                          "type": "integer",
                          "example": 5
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing token"
          }
        }
      }
    },
    "/help-and-feedback/contact/{id}": {
      "get": {
        "tags": [
          "Help and Feedback"
        ],
        "summary": "Get a specific contact/feedback entry by ID",
        "description": "Retrieve details of a specific contact/feedback entry. Requires authentication.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Contact/feedback entry ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Contact/feedback entry retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Contact retrieved successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "_id": {
                          "type": "string",
                          "example": "507f1f77bcf86cd799439011"
                        },
                        "name": {
                          "type": "string",
                          "example": "John Doe"
                        },
                        "email": {
                          "type": "string",
                          "format": "email",
                          "example": "john@example.com"
                        },
                        "message": {
                          "type": "string",
                          "example": "This is a feedback message"
                        },
                        "status": {
                          "type": "string",
                          "example": "OPEN"
                        },
                        "priority": {
                          "type": "string",
                          "example": "MEDIUM"
                        },
                        "type": {
                          "type": "string",
                          "example": "feedback"
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing token"
          },
          "404": {
            "description": "Contact/feedback entry not found"
          }
        }
      },
      "put": {
        "tags": [
          "Help and Feedback"
        ],
        "summary": "Update a specific contact/feedback entry by ID",
        "description": "Update details of a specific contact/feedback entry. Requires authentication.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Contact/feedback entry ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "User's name"
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "User's email address"
                  },
                  "message": {
                    "type": "string",
                    "description": "The feedback or contact message"
                  },
                  "subject": {
                    "type": "string",
                    "description": "Subject of the message (optional)"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "OPEN",
                      "IN_PROGRESS",
                      "RESOLVED",
                      "CLOSED"
                    ],
                    "description": "Status of the contact request (optional)"
                  },
                  "priority": {
                    "type": "string",
                    "enum": [
                      "LOW",
                      "MEDIUM",
                      "HIGH",
                      "CRITICAL"
                    ],
                    "description": "Priority of the contact request (optional)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contact/feedback entry updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Contact updated successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "_id": {
                          "type": "string",
                          "example": "507f1f77bcf86cd799439011"
                        },
                        "name": {
                          "type": "string",
                          "example": "John Doe"
                        },
                        "email": {
                          "type": "string",
                          "format": "email",
                          "example": "john@example.com"
                        },
                        "message": {
                          "type": "string",
                          "example": "This is a feedback message"
                        },
                        "status": {
                          "type": "string",
                          "example": "IN_PROGRESS"
                        },
                        "priority": {
                          "type": "string",
                          "example": "HIGH"
                        },
                        "type": {
                          "type": "string",
                          "example": "support"
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input data"
          },
          "401": {
            "description": "Unauthorized - Invalid or missing token"
          },
          "404": {
            "description": "Contact/feedback entry not found"
          }
        }
      },
      "delete": {
        "tags": [
          "Help and Feedback"
        ],
        "summary": "Delete a specific contact/feedback entry by ID",
        "description": "Delete a specific contact/feedback entry. Requires authentication.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Contact/feedback entry ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Contact/feedback entry deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Contact deleted successfully"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing token"
          },
          "404": {
            "description": "Contact/feedback entry not found"
          }
        }
      }
    },
    "/help-and-feedback/contact/{id}/status": {
      "put": {
        "tags": [
          "Help and Feedback"
        ],
        "summary": "Update the status of a specific contact/feedback entry",
        "description": "Update only the status of a specific contact/feedback entry. Requires authentication.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Contact/feedback entry ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "status"
                ],
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "OPEN",
                      "IN_PROGRESS",
                      "RESOLVED",
                      "CLOSED"
                    ],
                    "description": "New status for the contact request"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contact/feedback status updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Contact status updated successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "_id": {
                          "type": "string",
                          "example": "507f1f77bcf86cd799439011"
                        },
                        "status": {
                          "type": "string",
                          "example": "IN_PROGRESS"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input data"
          },
          "401": {
            "description": "Unauthorized - Invalid or missing token"
          },
          "404": {
            "description": "Contact/feedback entry not found"
          }
        }
      }
    },
    "/help-and-feedback/contact/{id}/priority": {
      "put": {
        "tags": [
          "Help and Feedback"
        ],
        "summary": "Update the priority of a specific contact/feedback entry",
        "description": "Update only the priority of a specific contact/feedback entry. Requires authentication.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Contact/feedback entry ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "priority"
                ],
                "properties": {
                  "priority": {
                    "type": "string",
                    "enum": [
                      "LOW",
                      "MEDIUM",
                      "HIGH",
                      "CRITICAL"
                    ],
                    "description": "New priority for the contact request"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contact/feedback priority updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Contact priority updated successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "_id": {
                          "type": "string",
                          "example": "507f1f77bcf86cd799439011"
                        },
                        "priority": {
                          "type": "string",
                          "example": "HIGH"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input data"
          },
          "401": {
            "description": "Unauthorized - Invalid or missing token"
          },
          "404": {
            "description": "Contact/feedback entry not found"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "QRCode": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "description": "QR code unique identifier"
          },
          "title": {
            "type": "string",
            "description": "QR code title"
          },
          "type": {
            "type": "string",
            "enum": [
              "CAR",
              "PET",
              "MEDICAL_QR",
              "LUGGAGE",
              "IDENTIFICATIONS",
              "DOCUMENT",
              "MEMORY_TAG"
            ],
            "description": "Type of QR code"
          },
          "item_name": {
            "type": "string",
            "description": "Name of the item"
          },
          "item_description": {
            "type": "string",
            "description": "Description of the item"
          },
          "type_details": {
            "type": "object",
            "description": "Type-specific details (varies by QR code type)"
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "INACTIVE",
              "MISSING"
            ],
            "description": "Current status of the QR code"
          },
          "access_type": {
            "type": "string",
            "enum": [
              "PUBLIC",
              "PRIVATE",
              "PROTECTED"
            ],
            "description": "Access control type"
          },
          "location": {
            "type": "object",
            "properties": {
              "latitude": {
                "type": "number"
              },
              "longitude": {
                "type": "number"
              },
              "City": {
                "type": "string"
              },
              "address": {
                "type": "string"
              },
              "country": {
                "type": "string"
              }
            }
          },
          "location_enabled": {
            "type": "boolean",
            "description": "Whether location tracking is enabled"
          },
          "images": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "_id": {
                  "type": "string"
                },
                "originalName": {
                  "type": "string"
                },
                "filePath": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                }
              }
            }
          },
          "memory_tag": {
            "type": "object",
            "description": "Memory Tag specific data (only for MEMORY_TAG type)",
            "properties": {
              "location_enabled": {
                "type": "boolean"
              },
              "images": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "location": {
                "type": "object"
              }
            }
          },
          "qr_code_url": {
            "type": "string",
            "description": "URL to the generated QR code image"
          },
          "created_by": {
            "type": "object",
            "description": "User who created the QR code"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "User ID"
          },
          "first_name": {
            "type": "string",
            "minLength": 2,
            "maxLength": 50,
            "description": "User's first name"
          },
          "last_name": {
            "type": "string",
            "minLength": 2,
            "maxLength": 50,
            "description": "User's last name"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "User's email address"
          },
          "phone_number": {
            "type": "string",
            "minLength": 10,
            "maxLength": 15,
            "description": "User's phone number"
          },
          "profile_picture": {
            "type": "string",
            "description": "Profile picture URL"
          },
          "role": {
            "type": "string",
            "enum": [
              "USER",
              "ADMIN"
            ],
            "default": "USER",
            "description": "User role"
          },
          "is_verified": {
            "type": "boolean",
            "default": false,
            "description": "Whether the user's email is verified"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "User creation timestamp"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "User last update timestamp"
          }
        }
      },
      "Notification": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "description": "Notification ID"
          },
          "title": {
            "type": "string",
            "description": "Notification title"
          },
          "message": {
            "type": "string",
            "description": "Notification message"
          },
          "type": {
            "type": "string",
            "enum": [
              "MESSAGE",
              "EMERGENCY",
              "QRSCAN",
              "DEFAULT"
            ],
            "description": "Notification type"
          },
          "is_read": {
            "type": "boolean",
            "default": false,
            "description": "Whether notification is read"
          },
          "user_id": {
            "type": "string",
            "description": "User ID"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Creation timestamp"
          }
        }
      },
      "Scan": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "description": "Scan ID"
          },
          "qrcode_id": {
            "type": "string",
            "description": "QR Code ID"
          },
          "scanned_by": {
            "type": "string",
            "description": "User ID who scanned"
          },
          "scan_location": {
            "type": "object",
            "description": "Location of the scan. City and country are automatically derived from latitude and longitude.",
            "properties": {
              "latitude": {
                "type": "number"
              },
              "longitude": {
                "type": "number"
              },
              "country": {
                "type": "string",
                "readOnly": true
              },
              "city": {
                "type": "string",
                "readOnly": true
              },
              "address": {
                "type": "string",
                "readOnly": true
              }
            }
          },
          "notes": {
            "type": "string"
          },
          "is_anonymous": {
            "type": "boolean"
          },
          "ip_address": {
            "type": "string"
          },
          "device_info": {
            "type": "string"
          },
          "isPublic": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "LogEntry": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "description": "Log entry unique identifier"
          },
          "module": {
            "type": "string",
            "description": "Module name that generated the log"
          },
          "level": {
            "type": "string",
            "enum": [
              "INFO",
              "WARN",
              "ERROR",
              "DEBUG",
              "CRITICAL"
            ],
            "description": "Log level"
          },
          "action": {
            "type": "string",
            "description": "Action description"
          },
          "admin_id": {
            "type": "string",
            "description": "Admin ID reference (optional)"
          },
          "user_id": {
            "type": "string",
            "description": "User ID reference (optional)"
          },
          "metadata": {
            "type": "object",
            "description": "Additional metadata"
          },
          "ip_address": {
            "type": "string",
            "description": "IP address (for security logs)"
          },
          "user_agent": {
            "type": "string",
            "description": "User agent (for request logs)"
          },
          "error_details": {
            "type": "object",
            "description": "Error details (for ERROR and CRITICAL logs)"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Log creation timestamp"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Last update timestamp"
          }
        }
      },
      "CreateLogRequest": {
        "type": "object",
        "required": [
          "module",
          "level",
          "action"
        ],
        "properties": {
          "module": {
            "type": "string",
            "description": "Module name that generated the log"
          },
          "level": {
            "type": "string",
            "enum": [
              "INFO",
              "WARN",
              "ERROR",
              "DEBUG",
              "CRITICAL"
            ],
            "description": "Log level"
          },
          "action": {
            "type": "string",
            "description": "Action description"
          },
          "metadata": {
            "type": "object",
            "description": "Additional metadata (optional)"
          },
          "error_details": {
            "type": "object",
            "description": "Error details (optional, for ERROR and CRITICAL logs)"
          }
        }
      },
      "LogsResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "properties": {
              "logs": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/LogEntry"
                }
              },
              "pagination": {
                "type": "object",
                "properties": {
                  "page": {
                    "type": "integer"
                  },
                  "limit": {
                    "type": "integer"
                  },
                  "total": {
                    "type": "integer"
                  },
                  "totalPages": {
                    "type": "integer"
                  }
                }
              }
            }
          },
          "code": {
            "type": "integer"
          }
        }
      },
      "LogStatistics": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer",
                "description": "Total number of logs"
              },
              "byLevel": {
                "type": "array",
                "description": "Log counts grouped by level",
                "items": {
                  "type": "object",
                  "properties": {
                    "level": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              },
              "byModule": {
                "type": "array",
                "description": "Log counts grouped by module",
                "items": {
                  "type": "object",
                  "properties": {
                    "_id": {
                      "type": "string",
                      "description": "Module name"
                    },
                    "count": {
                      "type": "integer",
                      "description": "Number of logs for this module"
                    }
                  }
                }
              }
            }
          },
          "code": {
            "type": "integer"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "message": {
            "type": "string",
            "description": "Error message"
          },
          "error": {
            "type": "object",
            "description": "Error details (optional)"
          },
          "code": {
            "type": "integer",
            "description": "HTTP status code"
          }
        }
      },
      "Family": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "description": "Family unique identifier"
          },
          "familyName": {
            "type": "string",
            "description": "Name of the family"
          },
          "familyOwner": {
            "$ref": "#/components/schemas/User",
            "description": "User who owns the family"
          },
          "members": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FamilyMember"
            },
            "description": "List of family members"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "FamilyMember": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "description": "Family member unique identifier"
          },
          "userId": {
            "$ref": "#/components/schemas/User",
            "description": "Reference to the user account"
          },
          "name": {
            "type": "string",
            "description": "Name of the family member"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email of the family member"
          },
          "familyRole": {
            "type": "string",
            "enum": [
              "OWNER",
              "MEMBER",
              "SPOUSE",
              "CHILD",
              "WIFE",
              "RELATIVES"
            ],
            "description": "Role of the family member"
          },
          "phoneNumber": {
            "type": "string",
            "description": "Phone number of the family member"
          },
          "profilePicture": {
            "type": "string",
            "description": "Profile picture URL"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}