{
    "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"
                    }
                }
            }
        }
    }
}
