@shadimakhoul/ggcoach 1.0.0

package/config/swagger.ts

@@ -0,0 +1,4417 @@
+import swaggerJsdoc from "swagger-jsdoc";
+import { Request, Response } from "express";
+
+const options = {
+  definition: {
+    openapi: "3.0.0",
+    info: {
+      title: "GGCoach API",
+      version: "1.0.0",
+      description:
+        "Comprehensive API documentation for GGCoach microservices platform",
+      contact: {
+        name: "Shadi Makhoul",
+        email: "shadimakhoul570@gmail.com",
+      },
+      license: {
+        name: "ISC",
+        url: "https://opensource.org/licenses/ISC",
+      },
+    },
+    servers: [
+      {
+        url: "http://localhost:4000",
+        description: "Development API Gateway Server",
+      },
+      {
+        url: "https://gg.staging.brainexy.com",
+        description: "Staging API Gateway Server",
+      },
+    ],
+    components: {
+      securitySchemes: {
+        bearerAuth: {
+          type: "http",
+          scheme: "bearer",
+          bearerFormat: "JWT",
+          description:
+            'JWT Authorization header using the Bearer scheme. Example: "Authorization: Bearer {token}"',
+        },
+      },
+      schemas: {
+        User: {
+          type: "object",
+          properties: {
+            id: {
+              type: "integer",
+              description: "User unique identifier",
+              example: 1,
+            },
+            firstName: {
+              type: "string",
+              description: "User first name",
+              example: "John",
+              minLength: 2,
+              maxLength: 100,
+            },
+            lastName: {
+              type: "string",
+              description: "User last name",
+              example: "Doe",
+              minLength: 2,
+              maxLength: 100,
+            },
+            email: {
+              type: "string",
+              format: "email",
+              description: "User email address",
+              example: "john.doe@example.com",
+            },
+            phoneNumber: {
+              type: "string",
+              description: "User phone number",
+              example: "+1234567890",
+              pattern: "^[\\+]?[1-9][\\d]{0,15}$",
+            },
+            accountType: {
+              type: "string",
+              description: "Type of account",
+              enum: ["Client", "Provider", "Admin", "SuperAdmin"],
+              example: "Client",
+            },
+            is_active: {
+              type: "boolean",
+              description: "User account status",
+              example: true,
+            },
+            created_at: {
+              type: "string",
+              format: "date-time",
+              description: "Account creation timestamp",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+            updated_at: {
+              type: "string",
+              format: "date-time",
+              description: "Last update timestamp",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+          },
+          required: ["id", "firstName", "lastName", "email", "accountType", "is_active"],
+        },
+        UserSignup: {
+          type: "object",
+          properties: {
+            firstName: {
+              type: "string",
+              description: "User first name",
+              example: "John",
+              minLength: 2,
+              maxLength: 100,
+            },
+            lastName: {
+              type: "string",
+              description: "User last name",
+              example: "Doe",
+              minLength: 2,
+              maxLength: 100,
+            },
+            email: {
+              type: "string",
+              format: "email",
+              description: "User email address",
+              example: "john.doe@example.com",
+            },
+            phoneNumber: {
+              type: "string",
+              description: "User phone number",
+              example: "+1234567890",
+              pattern: "^[\\+]?[1-9][\\d]{0,15}$",
+            },
+            password: {
+              type: "string",
+              description: "User password",
+              example: "securePassword123",
+              minLength: 6,
+              maxLength: 255,
+            },
+            accountType: {
+              type: "string",
+              description: "Type of account to create",
+              enum: ["Client", "Provider", "Admin", "SuperAdmin"],
+              example: "Client",
+            },
+          },
+          required: ["firstName", "lastName", "email", "password", "accountType"],
+        },
+        UserSignin: {
+          type: "object",
+          properties: {
+            identifier: {
+              type: "string",
+              description: "Email address or phone number",
+              example: "john.doe@example.com",
+            },
+            password: {
+              type: "string",
+              description: "User password",
+              example: "securePassword123",
+            },
+          },
+          required: ["identifier", "password"],
+        },
+        RefreshToken: {
+          type: "object",
+          properties: {
+            refresh_token: {
+              type: "string",
+              description: "Refresh token for getting new access token",
+              example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+            },
+          },
+          required: ["refresh_token"],
+        },
+        ConfirmEmail: {
+          type: "object",
+          properties: {
+            token: {
+              type: "string",
+              description: "Email verification token",
+              example: "3b9a4c0f6b0b4c9e8a0f3a9d1f2a3b4c",
+            },
+          },
+          required: ["token"],
+        },
+        ResendConfirmation: {
+          type: "object",
+          properties: {
+            email: {
+              type: "string",
+              format: "email",
+              description: "User email address",
+              example: "john.doe@example.com",
+            },
+          },
+          required: ["email"],
+        },
+        ForgotPassword: {
+          type: "object",
+          properties: {
+            email: {
+              type: "string",
+              format: "email",
+              description: "User email address",
+              example: "john.doe@example.com",
+            },
+          },
+          required: ["email"],
+        },
+        ResetPassword: {
+          type: "object",
+          properties: {
+            token: {
+              type: "string",
+              description: "Password reset token",
+              example: "9f0e1d2c3b4a5f67890123456789abcd",
+            },
+            new_password: {
+              type: "string",
+              description: "New account password",
+              example: "securePassword123",
+              minLength: 6,
+              maxLength: 255,
+            },
+          },
+          required: ["token", "new_password"],
+        },
+        PhoneVerificationRequest: {
+          type: "object",
+          properties: {
+            phoneNumber: {
+              type: "string",
+              description: "User phone number",
+              example: "+1234567890",
+              pattern: "^[\\+]?[1-9][\\d]{0,15}$",
+            },
+          },
+          required: ["phoneNumber"],
+        },
+        PhoneVerificationConfirm: {
+          type: "object",
+          properties: {
+            phoneNumber: {
+              type: "string",
+              description: "User phone number",
+              example: "+1234567890",
+              pattern: "^[\\+]?[1-9][\\d]{0,15}$",
+            },
+            code: {
+              type: "string",
+              description: "Verification code",
+              example: "123456",
+            },
+          },
+          required: ["phoneNumber", "code"],
+        },
+        Tokens: {
+          type: "object",
+          properties: {
+            access_token: {
+              type: "string",
+              description: "JWT access token",
+              example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+            },
+            refresh_token: {
+              type: "string",
+              description: "JWT refresh token",
+              example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+            },
+          },
+          required: ["access_token", "refresh_token"],
+        },
+        AuthResponse: {
+          type: "object",
+          properties: {
+            success: {
+              type: "boolean",
+              description: "Request success status",
+              example: true,
+            },
+            message: {
+              type: "string",
+              description: "Response message",
+              example: "User created successfully",
+            },
+            data: {
+              type: "object",
+              properties: {
+                user: {
+                  $ref: "#/components/schemas/User",
+                },
+                tokens: {
+                  $ref: "#/components/schemas/Tokens",
+                },
+              },
+            },
+            error: {
+              type: "string",
+              description: "Error message (only in development)",
+              example: "Validation error",
+            },
+          },
+          required: ["success", "message"],
+        },
+        ErrorResponse: {
+          type: "object",
+          properties: {
+            success: {
+              type: "boolean",
+              description: "Request success status",
+              example: false,
+            },
+            message: {
+              type: "string",
+              description: "Error message",
+              example: "Invalid credentials",
+            },
+            error: {
+              type: "string",
+              description: "Detailed error message (only in development)",
+              example: "User not found",
+            },
+          },
+          required: ["success", "message"],
+        },
+        HealthResponse: {
+          type: "object",
+          properties: {
+            success: {
+              type: "boolean",
+              description: "Service health status",
+              example: true,
+            },
+            message: {
+              type: "string",
+              description: "Health check message",
+              example: "API Gateway is healthy",
+            },
+            timestamp: {
+              type: "string",
+              format: "date-time",
+              description: "Response timestamp",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+            service: {
+              type: "string",
+              description: "Service name",
+              example: "api-gateway",
+            },
+            version: {
+              type: "string",
+              description: "Service version",
+              example: "1.0.0",
+            },
+          },
+          required: ["success", "message", "timestamp", "service", "version"],
+        },
+        ServiceStatus: {
+          type: "object",
+          properties: {
+            success: {
+              type: "boolean",
+              description: "Request success status",
+              example: true,
+            },
+            message: {
+              type: "string",
+              description: "Status message",
+              example: "Service status retrieved",
+            },
+            data: {
+              type: "object",
+              properties: {
+                services: {
+                  type: "object",
+                  properties: {
+                    gateway: {
+                      type: "object",
+                      properties: {
+                        name: {
+                          type: "string",
+                          example: "api-gateway",
+                        },
+                        status: {
+                          type: "string",
+                          example: "healthy",
+                        },
+                        url: {
+                          type: "string",
+                          example: "http://localhost:4000",
+                        },
+                      },
+                    },
+                    auth: {
+                      type: "object",
+                      properties: {
+                        name: {
+                          type: "string",
+                          example: "auth-service",
+                        },
+                        status: {
+                          type: "string",
+                          example: "healthy",
+                        },
+                        url: {
+                          type: "string",
+                          example: "http://localhost:4001",
+                        },
+                      },
+                    },
+                  },
+                },
+                timestamp: {
+                  type: "string",
+                  format: "date-time",
+                  example: "2024-01-15T10:30:00.000Z",
+                },
+              },
+            },
+          },
+        },
+        UserProfile: {
+          type: "object",
+          properties: {
+            id: { type: "integer", example: 1 },
+            userId: {
+              type: "integer",
+              description: "Related user id",
+              example: 1,
+            },
+            birthday: { type: "string", format: "date", example: "1990-05-20" },
+            gender: {
+              type: "string",
+              example: "male",
+              enum: ["male", "female", "other"],
+            },
+            height: {
+              type: "number",
+              description: "Height in centimeters",
+              example: 180,
+            },
+            weight: {
+              type: "number",
+              description: "Weight in kilograms",
+              example: 75,
+            },
+            avatar: {
+              type: "string",
+              description: "Avatar file URL",
+              example:
+                "gg.staging.brainexy.com/uploads/avatar/1768735674627-779883386.jpg",
+            },
+            created_at: {
+              type: "string",
+              format: "date-time",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+            updated_at: {
+              type: "string",
+              format: "date-time",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+          },
+        },
+        ProfileResponse: {
+          type: "object",
+          properties: {
+            success: { type: "boolean", example: true },
+            message: { type: "string", example: "Profile created" },
+            data: {
+              type: "object",
+              properties: {
+                profile: { $ref: "#/components/schemas/UserProfile" },
+              },
+            },
+          },
+        },
+        Media: {
+          type: "object",
+          properties: {
+            id: { type: "integer", example: 1 },
+            filename: {
+              type: "string",
+              description: "Media file name",
+              example: "avatar-1609459200000.png",
+            },
+            originalName: {
+              type: "string",
+              description: "Original file name",
+              example: "avatar.png",
+            },
+            mimetype: {
+              type: "string",
+              description: "File MIME type",
+              example: "image/png",
+            },
+            size: {
+              type: "integer",
+              description: "File size in bytes",
+              example: 102400,
+            },
+            path: {
+              type: "string",
+              description: "File storage path",
+              example: "/uploads/avatar/avatar-1609459200000.png",
+            },
+            userId: {
+              type: "integer",
+              description: "User who uploaded the file",
+              example: 1,
+            },
+            type: {
+              type: "string",
+              description: "Media type (avatar or private)",
+              enum: ["avatar", "private"],
+              example: "avatar",
+            },
+            created_at: {
+              type: "string",
+              format: "date-time",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+            updated_at: {
+              type: "string",
+              format: "date-time",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+          },
+        },
+        MediaResponse: {
+          type: "object",
+          properties: {
+            success: { type: "boolean", example: true },
+            message: { type: "string", example: "File uploaded successfully" },
+            data: {
+              type: "object",
+              properties: { media: { $ref: "#/components/schemas/Media" } },
+            },
+          },
+        },
+        UserSpecializationProfile: {
+          type: "object",
+          properties: {
+            userId: {
+              type: "integer",
+              description: "User ID associated with this specialization",
+              example: 1,
+            },
+            specializationId: {
+              type: "integer",
+              description: "Specialization ID assigned to the user",
+              example: 2,
+            },
+            specializationName: {
+              type: "string",
+              nullable: true,
+              description: "Name of the specialization",
+              example: "Doctor",
+            },
+          },
+          required: ["userId", "specializationId", "specializationName"],
+        },
+        UserSpecializationProfileResponse: {
+          type: "object",
+          properties: {
+            success: { type: "boolean", example: true },
+            message: { type: "string", example: "User specialization profile retrieved successfully" },
+            data: {
+              oneOf: [
+                { $ref: "#/components/schemas/UserSpecializationProfile" },
+                {
+                  type: "array",
+                  items: { $ref: "#/components/schemas/UserSpecializationProfile" },
+                },
+              ],
+            },
+          },
+          required: ["success", "message"],
+        },
+        UserMetadata: {
+          type: "object",
+          description: "Flexible JSON object storing user-specific metadata, preferences, and settings",
+          additionalProperties: true,
+          example: {
+            theme: "dark",
+            language: "en",
+            notifications: {
+              email: true,
+              push: false
+            },
+            customField: "customValue"
+          }
+        },
+        UserMetadataResponse: {
+          type: "object",
+          properties: {
+            success: { type: "boolean", example: true },
+            message: { type: "string", example: "Metadata retrieved successfully" },
+            data: {
+              oneOf: [
+                { $ref: "#/components/schemas/UserMetadata" },
+                {
+                  type: "object",
+                  description: "Single metadata field response",
+                  additionalProperties: true,
+                  example: { theme: "dark" }
+                }
+              ]
+            }
+          },
+          required: ["success", "message"]
+        },
+        AppRole: {
+          type: "object",
+          properties: {
+            id: {
+              type: "integer",
+              description: "Role unique identifier",
+              example: 1,
+            },
+            name: {
+              type: "string",
+              description: "Role name",
+              example: "admin",
+              minLength: 2,
+              maxLength: 100,
+            },
+            description: {
+              type: "string",
+              description: "Role description",
+              example: "Administrator role with full system access",
+              nullable: true,
+            },
+            permissions: {
+              type: "array",
+              description: "Array of permissions assigned to this role",
+              items: {
+                type: "object",
+                properties: {
+                  id: { type: "integer", example: 1 },
+                  name: { type: "string", example: "users.manage" },
+                  description: { type: "string", example: "Manage users" },
+                },
+              },
+              example: [
+                { id: 1, name: "users.create", description: "Create users" },
+                { id: 2, name: "users.update", description: "Update users" },
+                { id: 3, name: "users.delete", description: "Delete users" },
+              ],
+            },
+            isActive: {
+              type: "boolean",
+              description: "Role status",
+              example: true,
+            },
+            created_at: {
+              type: "string",
+              format: "date-time",
+              description: "Role creation timestamp",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+            updated_at: {
+              type: "string",
+              format: "date-time",
+              description: "Last update timestamp",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+          },
+          required: ["id", "name", "isActive"],
+        },
+        CreateAppRoleRequest: {
+          type: "object",
+          properties: {
+            name: {
+              type: "string",
+              description: "Role name",
+              example: "moderator",
+              minLength: 2,
+              maxLength: 100,
+            },
+            description: {
+              type: "string",
+              description: "Role description",
+              example: "Moderator role with limited access",
+              nullable: true,
+            },
+            permissions: {
+              type: "array",
+              description: "Array of permission IDs to assign to this role",
+              items: { type: "integer" },
+              example: [1, 2, 3],
+            },
+            isActive: {
+              type: "boolean",
+              description: "Role status (active or inactive)",
+              example: true,
+              default: true,
+            },
+          },
+          required: ["name"],
+        },
+        UpdateAppRoleRequest: {
+          type: "object",
+          properties: {
+            name: {
+              type: "string",
+              description: "Role name",
+              example: "moderator",
+              minLength: 2,
+              maxLength: 100,
+            },
+            description: {
+              type: "string",
+              description: "Role description",
+              example: "Updated moderator description",
+              nullable: true,
+            },
+            permissions: {
+              type: "array",
+              description: "Array of permission IDs to assign to this role",
+              items: { type: "integer" },
+              example: [1, 2, 3],
+            },
+            isActive: {
+              type: "boolean",
+              description: "Role status",
+              example: true,
+            },
+          },
+        },
+        AdminRoleResponse: {
+          type: "object",
+          properties: {
+            success: {
+              type: "boolean",
+              description: "Request success status",
+              example: true,
+            },
+            message: {
+              type: "string",
+              description: "Response message",
+              example: "Role created successfully",
+            },
+            data: {
+              oneOf: [
+                { $ref: "#/components/schemas/AppRole" },
+                {
+                  type: "array",
+                  items: { $ref: "#/components/schemas/AppRole" },
+                },
+              ],
+            },
+          },
+          required: ["success", "message"],
+        },
+        Specialization: {
+          type: "object",
+          properties: {
+            id: {
+              type: "integer",
+              description: "Specialization unique identifier",
+              example: 1,
+            },
+            name: {
+              type: "string",
+              description: "Specialization name",
+              example: "Doctor",
+            },
+            parentId: {
+              type: "integer",
+              nullable: true,
+              description: "Parent specialization ID (null for root)",
+              example: null,
+            },
+            description: {
+              type: "string",
+              nullable: true,
+              description: "Specialization description",
+              example: "Medical doctor specialization",
+            },
+            imageUrl: {
+              type: "string",
+              nullable: true,
+              description: "Specialization image URL",
+              example: "https://example.com/images/doctor.png",
+            },
+            created_at: {
+              type: "string",
+              format: "date-time",
+              description: "Creation timestamp",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+            updated_at: {
+              type: "string",
+              format: "date-time",
+              description: "Last update timestamp",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+          },
+          required: ["id", "name"],
+        },
+        SpecializationTree: {
+          type: "object",
+          properties: {
+            id: {
+              type: "integer",
+              description: "Specialization unique identifier",
+              example: 1,
+            },
+            name: {
+              type: "string",
+              description: "Specialization name",
+              example: "Health",
+            },
+            description: {
+              type: "string",
+              nullable: true,
+              description: "Specialization description",
+              example: "Health specialization category",
+            },
+            imageUrl: {
+              type: "string",
+              nullable: true,
+              description: "Specialization image URL",
+              example: "https://example.com/images/health.png",
+            },
+            created_at: {
+              type: "string",
+              format: "date-time",
+              description: "Creation timestamp",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+            updated_at: {
+              type: "string",
+              format: "date-time",
+              description: "Last update timestamp",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+            children: {
+              type: "array",
+              description: "Child specializations",
+              items: {
+                type: "object",
+                properties: {
+                  id: { type: "integer" },
+                  name: { type: "string" },
+                  description: { type: "string", nullable: true },
+                  imageUrl: { type: "string", nullable: true },
+                  created_at: { type: "string", format: "date-time" },
+                  updated_at: { type: "string", format: "date-time" },
+                  children: { type: "array" },
+                },
+              },
+              example: [
+                {
+                  id: 2,
+                  name: "Doctor",
+                  description: "Medical doctor",
+                  imageUrl: "https://example.com/images/doctor.png",
+                  created_at: "2024-01-15T10:30:00.000Z",
+                  updated_at: "2024-01-15T10:30:00.000Z",
+                  children: [
+                    {
+                      id: 3,
+                      name: "Dentist",
+                      description: "Dental specialization",
+                      imageUrl: "https://example.com/images/dentist.png",
+                      created_at: "2024-01-15T10:30:00.000Z",
+                      updated_at: "2024-01-15T10:30:00.000Z",
+                      children: [],
+                    },
+                  ],
+                },
+              ],
+            },
+          },
+          required: ["id", "name"],
+        },
+        MarketingContact: {
+          type: "object",
+          properties: {
+            id: { type: "integer", example: 1 },
+            email: {
+              type: "string",
+              format: "email",
+              nullable: true,
+              example: "user@example.com",
+            },
+            phone: {
+              type: "string",
+              nullable: true,
+              example: "+1234567890",
+            },
+            status: {
+              type: "string",
+              enum: ["lead", "subscriber", "customer", "suppressed"],
+              example: "lead",
+            },
+            source: {
+              type: "string",
+              enum: ["fitness_app", "brainexy", "landing_page", "other"],
+              example: "landing_page",
+            },
+            created_at: {
+              type: "string",
+              format: "date-time",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+            updated_at: {
+              type: "string",
+              format: "date-time",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+          },
+          required: ["id", "status", "source"],
+        },
+        CreateMarketingContactRequest: {
+          type: "object",
+          properties: {
+            email: { type: "string", format: "email" },
+            phone: { type: "string" },
+            status: {
+              type: "string",
+              enum: ["lead", "subscriber", "customer", "suppressed"],
+              default: "lead",
+            },
+            source: {
+              type: "string",
+              enum: ["fitness_app", "brainexy", "landing_page", "other"],
+              default: "landing_page",
+            },
+          },
+          anyOf: [{ required: ["email"] }, { required: ["phone"] }],
+        },
+        MarketingConsent: {
+          type: "object",
+          properties: {
+            id: { type: "integer", example: 1 },
+            contact_id: { type: "integer", example: 1 },
+            channel: {
+              type: "string",
+              enum: ["email", "sms", "push"],
+              example: "email",
+            },
+            purpose: {
+              type: "string",
+              enum: ["marketing", "transactional"],
+              example: "marketing",
+            },
+            granted_at: {
+              type: "string",
+              format: "date-time",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+            revoked_at: {
+              type: "string",
+              format: "date-time",
+              nullable: true,
+              example: null,
+            },
+            source: { type: "string", nullable: true, example: "landing_page" },
+            created_at: {
+              type: "string",
+              format: "date-time",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+            updated_at: {
+              type: "string",
+              format: "date-time",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+          },
+          required: ["id", "contact_id", "channel", "purpose", "granted_at"],
+        },
+        CreateMarketingConsentRequest: {
+          type: "object",
+          properties: {
+            contact_id: { type: "integer" },
+            channel: { type: "string", enum: ["email", "sms", "push"] },
+            purpose: { type: "string", enum: ["marketing", "transactional"] },
+            granted_at: { type: "string", format: "date-time" },
+            revoked_at: { type: "string", format: "date-time", nullable: true },
+            source: { type: "string", nullable: true },
+          },
+          required: ["contact_id", "channel", "purpose"],
+        },
+        SegmentCondition: {
+          type: "object",
+          properties: {
+            type: { type: "string", enum: ["condition"], example: "condition" },
+            field: {
+              type: "string",
+              enum: ["status", "source", "email", "phone", "created_at", "updated_at"],
+            },
+            op: {
+              type: "string",
+              enum: [
+                "eq",
+                "neq",
+                "in",
+                "not_in",
+                "contains",
+                "starts_with",
+                "ends_with",
+                "gte",
+                "lte",
+              ],
+            },
+            value: {
+              oneOf: [
+                { type: "string" },
+                { type: "number" },
+                { type: "boolean" },
+                { type: "array", items: { oneOf: [{ type: "string" }, { type: "number" }] } },
+              ],
+            },
+          },
+          required: ["type", "field", "op", "value"],
+        },
+        SegmentGroup: {
+          type: "object",
+          properties: {
+            type: { type: "string", enum: ["group"], example: "group" },
+            match: { type: "string", enum: ["all", "any"], example: "all" },
+            children: {
+              type: "array",
+              items: { $ref: "#/components/schemas/SegmentNode" },
+            },
+          },
+          required: ["type", "match", "children"],
+        },
+        SegmentNode: {
+          oneOf: [
+            { $ref: "#/components/schemas/SegmentCondition" },
+            { $ref: "#/components/schemas/SegmentGroup" },
+          ],
+        },
+        MarketingSegment: {
+          type: "object",
+          properties: {
+            id: { type: "integer", example: 1 },
+            name: { type: "string", example: "New Leads" },
+            definition: { $ref: "#/components/schemas/SegmentNode" },
+            created_at: {
+              type: "string",
+              format: "date-time",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+            updated_at: {
+              type: "string",
+              format: "date-time",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+          },
+          required: ["id", "name", "definition"],
+        },
+        CreateMarketingSegmentRequest: {
+          type: "object",
+          properties: {
+            name: { type: "string", minLength: 2, maxLength: 100 },
+            definition: { $ref: "#/components/schemas/SegmentNode" },
+          },
+          required: ["name", "definition"],
+        },
+        MarketingCampaign: {
+          type: "object",
+          properties: {
+            id: { type: "integer", example: 1 },
+            name: { type: "string", example: "Welcome Campaign" },
+            channel: { type: "string", enum: ["email", "sms", "push"] },
+            segment_id: { type: "integer", example: 1 },
+            template_key: { type: "string", example: "welcome_v1" },
+            schedule: { type: "object", nullable: true, additionalProperties: true },
+            status: {
+              type: "string",
+              enum: ["draft", "active", "paused"],
+              example: "draft",
+            },
+            created_at: {
+              type: "string",
+              format: "date-time",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+            updated_at: {
+              type: "string",
+              format: "date-time",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+          },
+          required: ["id", "name", "channel", "segment_id", "template_key"],
+        },
+        CreateMarketingCampaignRequest: {
+          type: "object",
+          properties: {
+            name: { type: "string", minLength: 2, maxLength: 150 },
+            channel: { type: "string", enum: ["email", "sms", "push"] },
+            segment_id: { type: "integer" },
+            template_key: { type: "string", maxLength: 255 },
+            schedule: { type: "object", additionalProperties: true },
+            status: { type: "string", enum: ["draft", "active", "paused"], default: "draft" },
+          },
+          required: ["name", "channel", "segment_id", "template_key"],
+        },
+        MarketingCampaignRun: {
+          type: "object",
+          properties: {
+            id: { type: "integer", example: 1 },
+            campaign_id: { type: "integer", example: 1 },
+            run_at: { type: "string", format: "date-time" },
+            status: {
+              type: "string",
+              enum: ["running", "completed", "failed"],
+              example: "running",
+            },
+            total_recipients: { type: "integer", example: 10 },
+            success_count: { type: "integer", example: 10 },
+            failure_count: { type: "integer", example: 0 },
+            error: { type: "string", nullable: true, example: null },
+            created_at: { type: "string", format: "date-time" },
+          },
+          required: ["id", "campaign_id", "run_at", "status"],
+        },
+        MarketingContactResponse: {
+          type: "object",
+          properties: {
+            success: { type: "boolean", example: true },
+            data: { $ref: "#/components/schemas/MarketingContact" },
+          },
+          required: ["success", "data"],
+        },
+        MarketingConsentResponse: {
+          type: "object",
+          properties: {
+            success: { type: "boolean", example: true },
+            data: { $ref: "#/components/schemas/MarketingConsent" },
+          },
+          required: ["success", "data"],
+        },
+        MarketingSegmentResponse: {
+          type: "object",
+          properties: {
+            success: { type: "boolean", example: true },
+            data: { $ref: "#/components/schemas/MarketingSegment" },
+          },
+          required: ["success", "data"],
+        },
+        MarketingCampaignResponse: {
+          type: "object",
+          properties: {
+            success: { type: "boolean", example: true },
+            data: { $ref: "#/components/schemas/MarketingCampaign" },
+          },
+          required: ["success", "data"],
+        },
+        MarketingCampaignRunResponse: {
+          type: "object",
+          properties: {
+            success: { type: "boolean", example: true },
+            data: { $ref: "#/components/schemas/MarketingCampaignRun" },
+          },
+          required: ["success", "data"],
+        },
+        MessagingMessage: {
+          type: "object",
+          properties: {
+            id: { type: "integer", example: 1 },
+            type: {
+              type: "string",
+              enum: ["transactional", "product", "marketing"],
+              example: "marketing",
+            },
+            channel: {
+              type: "string",
+              enum: ["email", "sms", "push"],
+              example: "email",
+            },
+            template_key: { type: "string", example: "welcome" },
+            recipient: { type: "string", example: "user@example.com" },
+            payload: { type: "object", additionalProperties: true },
+            source_service: { type: "string", example: "marketing-service" },
+            status: {
+              type: "string",
+              enum: ["pending", "sent", "failed"],
+              example: "pending",
+            },
+            scheduled_at: {
+              type: "string",
+              format: "date-time",
+              nullable: true,
+              example: null,
+            },
+            sent_at: {
+              type: "string",
+              format: "date-time",
+              nullable: true,
+              example: null,
+            },
+            created_at: {
+              type: "string",
+              format: "date-time",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+            updated_at: {
+              type: "string",
+              format: "date-time",
+              example: "2024-01-15T10:30:00.000Z",
+            },
+          },
+          required: ["id", "type", "channel", "template_key", "recipient", "status"],
+        },
+        CreateMessagingMessageRequest: {
+          type: "object",
+          properties: {
+            channel: { type: "string", enum: ["email", "sms", "push"] },
+            type: { type: "string", enum: ["transactional", "product", "marketing"] },
+            template_key: { type: "string" },
+            recipient: { type: "string", format: "email" },
+            payload: { type: "object", additionalProperties: true },
+            source_service: { type: "string" },
+          },
+          required: ["channel", "type", "template_key", "recipient", "source_service"],
+        },
+        ScheduleMessagingMessageRequest: {
+          type: "object",
+          properties: {
+            channel: { type: "string", enum: ["email", "sms", "push"] },
+            type: { type: "string", enum: ["transactional", "product", "marketing"] },
+            template_key: { type: "string" },
+            recipient: { type: "string", format: "email" },
+            payload: { type: "object", additionalProperties: true },
+            source_service: { type: "string" },
+            scheduled_at: { type: "string", format: "date-time" },
+          },
+          required: [
+            "channel",
+            "type",
+            "template_key",
+            "recipient",
+            "source_service",
+            "scheduled_at",
+          ],
+        },
+        MessagingAcceptedResponse: {
+          type: "object",
+          properties: {
+            success: { type: "boolean", example: true },
+            message: { type: "string", example: "Message accepted for processing" },
+            data: {
+              type: "object",
+              properties: {
+                message_id: { type: "integer", example: 1 },
+                scheduled_at: { type: "string", format: "date-time", nullable: true },
+              },
+            },
+          },
+          required: ["success", "message", "data"],
+        },
+        MessagingMessageResponse: {
+          type: "object",
+          properties: {
+            success: { type: "boolean", example: true },
+            data: { $ref: "#/components/schemas/MessagingMessage" },
+          },
+          required: ["success", "data"],
+        },
+      },
+    },
+    // Centralized path definitions for endpoints that were previously declared inline in route files
+    paths: {
+      "/health": {
+        get: {
+          summary: "API Gateway Health Check",
+          description:
+            "Check if the API Gateway service is running and healthy",
+          tags: ["Health"],
+          responses: {
+            "200": {
+              description: "API Gateway is healthy",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/HealthResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/status": {
+        get: {
+          summary: "Service Status Overview",
+          description:
+            "Get the status of all microservices in the GGCoach platform",
+          tags: ["Health"],
+          responses: {
+            "200": {
+              description: "Service status retrieved successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ServiceStatus" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/auth": {
+        get: {
+          summary: "Authentication proxy (root)",
+          description:
+            "Authentication service endpoints (proxied by the API Gateway). Use specific auth paths for signup/signin/refresh/profile under /api/auth/*.",
+          tags: ["Authentication"],
+          responses: {
+            "200": { description: "Successful response from auth service" },
+            "401": { description: "Unauthorized" },
+            "500": { description: "Internal server error" },
+          },
+        },
+      },
+      "/api/auth/signup": {
+        post: {
+          summary: "User Registration",
+          description: "Create a new user account with email and phone number",
+          tags: ["Authentication"],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/UserSignup" },
+              },
+            },
+          },
+          responses: {
+            "201": {
+              description: "User created successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/AuthResponse" },
+                },
+              },
+            },
+            "409": {
+              description: "User already exists",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "400": {
+              description: "Validation error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/auth/signin": {
+        post: {
+          summary: "User Login",
+          description: "Authenticate user with email/phone and password",
+          tags: ["Authentication"],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/UserSignin" },
+              },
+            },
+          },
+          responses: {
+            "200": {
+              description: "Login successful",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/AuthResponse" },
+                },
+              },
+            },
+            "401": {
+              description: "Invalid credentials or account deactivated",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "400": {
+              description: "Validation error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/auth/refresh-token": {
+        post: {
+          summary: "Refresh Access Token",
+          description: "Get a new access token using refresh token",
+          tags: ["Authentication"],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/RefreshToken" },
+              },
+            },
+          },
+          responses: {
+            "200": {
+              description: "Token refreshed successfully",
+              content: { "application/json": { schema: { type: "object" } } },
+            },
+            "401": {
+              description: "Invalid refresh token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "400": {
+              description: "Refresh token is required",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/auth/user": {
+        get: {
+          summary: "Get User Auth info",
+          description: "Get current authenticated user's information",
+          tags: ["Authentication"],
+          security: [{ bearerAuth: [] }],
+          responses: {
+            "200": {
+              description: "User retrieved successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/AuthResponse" },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized - Invalid or missing token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "User not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/auth/confirm-email": {
+        post: {
+          summary: "Confirm Email",
+          description: "Confirm email address using a verification token",
+          tags: ["Authentication"],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/ConfirmEmail" },
+              },
+            },
+          },
+          responses: {
+            "200": {
+              description: "Email confirmed successfully",
+              content: {
+                "application/json": {
+                  schema: { type: "object" },
+                },
+              },
+            },
+            "400": {
+              description: "Invalid or expired token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "User not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+        get: {
+          summary: "Confirm Email (Query)",
+          description: "Confirm email address using a token in query string",
+          tags: ["Authentication"],
+          parameters: [
+            {
+              name: "token",
+              in: "query",
+              required: true,
+              schema: { type: "string" },
+              description: "Email verification token",
+            },
+          ],
+          responses: {
+            "200": {
+              description: "Email confirmed successfully",
+              content: {
+                "application/json": {
+                  schema: { type: "object" },
+                },
+              },
+            },
+            "400": {
+              description: "Invalid or expired token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "User not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/auth/resend-confirmation": {
+        post: {
+          summary: "Resend Email Confirmation",
+          description: "Resend the email confirmation link",
+          tags: ["Authentication"],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/ResendConfirmation" },
+              },
+            },
+          },
+          responses: {
+            "200": {
+              description: "Confirmation email sent if the address exists",
+              content: {
+                "application/json": {
+                  schema: { type: "object" },
+                },
+              },
+            },
+            "400": {
+              description: "Validation error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/auth/password/forgot": {
+        post: {
+          summary: "Request Password Reset",
+          description: "Request a password reset link",
+          tags: ["Authentication"],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/ForgotPassword" },
+              },
+            },
+          },
+          responses: {
+            "200": {
+              description: "Reset link sent if the email exists",
+              content: {
+                "application/json": {
+                  schema: { type: "object" },
+                },
+              },
+            },
+            "400": {
+              description: "Validation error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/auth/password/reset": {
+        post: {
+          summary: "Reset Password",
+          description: "Reset account password using a reset token",
+          tags: ["Authentication"],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/ResetPassword" },
+              },
+            },
+          },
+          responses: {
+            "200": {
+              description: "Password reset successfully",
+              content: {
+                "application/json": {
+                  schema: { type: "object" },
+                },
+              },
+            },
+            "400": {
+              description: "Invalid token or validation error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/auth/phone/verify/request": {
+        post: {
+          summary: "Request Phone Verification",
+          description: "Send a phone verification code",
+          tags: ["Authentication"],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/PhoneVerificationRequest" },
+              },
+            },
+          },
+          responses: {
+            "200": {
+              description: "Verification code sent if the phone exists",
+              content: {
+                "application/json": {
+                  schema: { type: "object" },
+                },
+              },
+            },
+            "400": {
+              description: "Validation error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/auth/phone/verify/confirm": {
+        post: {
+          summary: "Confirm Phone Verification",
+          description: "Confirm phone verification using a code",
+          tags: ["Authentication"],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/PhoneVerificationConfirm" },
+              },
+            },
+          },
+          responses: {
+            "200": {
+              description: "Phone number verified successfully",
+              content: {
+                "application/json": {
+                  schema: { type: "object" },
+                },
+              },
+            },
+            "400": {
+              description: "Invalid or expired verification code",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "User not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/user/profile": {
+        get: {
+          summary: "Get User Profile",
+          description: "Get current user's profile information",
+          tags: ["User"],
+          security: [{ bearerAuth: [] }],
+          responses: {
+            "200": {
+              description: "Profile retrieved successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ProfileResponse" },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized - Invalid or missing token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "User not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+        post: {
+          summary: "Create User Profile",
+          description:
+            "Create a profile for the authenticated user. Supports avatar upload (multipart/form-data).",
+          tags: ["User"],
+          security: [{ bearerAuth: [] }],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    birthday: { type: "string", format: "date" },
+                    gender: {
+                      type: "string",
+                      enum: ["male", "female", "other"],
+                    },
+                    height: { type: "number" },
+                    weight: { type: "number" },
+                    avatar: {
+                      type: "string",
+                      format: "string",
+                      description: "Avatar image path",
+                    },
+                  },
+                },
+              },
+            },
+          },
+          responses: {
+            "201": {
+              description: "Profile created",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ProfileResponse" },
+                },
+              },
+            },
+            "400": {
+              description: "Validation error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+        put: {
+          summary: "Update User Profile",
+          description:
+            "Update the authenticated user profile. Supports avatar upload (multipart/form-data).",
+          tags: ["User"],
+          security: [{ bearerAuth: [] }],
+          requestBody: {
+            required: false,
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    birthday: { type: "string", format: "date" },
+                    gender: {
+                      type: "string",
+                      enum: ["male", "female", "other"],
+                    },
+                    height: { type: "number" },
+                    weight: { type: "number" },
+                    avatar: {
+                      type: "string",
+                      format: "string",
+                      description: "Avatar image path",
+                    },
+                  },
+                },
+              },
+            },
+          },
+          responses: {
+            "200": {
+              description: "Profile updated",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ProfileResponse" },
+                },
+              },
+            },
+            "400": {
+              description: "Validation error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "Profile not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+        delete: {
+          summary: "Delete User Profile",
+          description: "Delete the authenticated user profile.",
+          tags: ["User"],
+          security: [{ bearerAuth: [] }],
+          responses: {
+            "200": {
+              description: "Profile deleted",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    properties: {
+                      success: { type: "boolean" },
+                      message: { type: "string" },
+                    },
+                  },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "Profile not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/user/admin/user-specialization": {
+        get: {
+          summary: "Get All User Specializations",
+          description: "Retrieve all user specialization profiles (paginated). Authentication required.",
+          tags: ["Admin User Specializations Profile"],
+          security: [{ bearerAuth: [] }],
+          responses: {
+            "200": {
+              description: "User specialization profiles retrieved successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/UserSpecializationProfileResponse" },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized - Invalid or missing token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/user/user-specialization": {
+        post: {
+          summary: "Create User Specializations",
+          description: "Bulk create user specialization profiles. Accepts an array of specialization IDs. Authentication required.",
+          tags: ["User Specializations Profile"],
+          security: [{ bearerAuth: [] }],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    specializations: {
+                      type: "array",
+                      description: "Array of specialization IDs to assign to the user",
+                      items: {
+                        type: "integer"
+                      },
+                      example: [1, 2, 5],
+                      minItems: 1
+                    }
+                  },
+                  required: ["specializations"],
+                },
+              },
+            },
+          },
+          responses: {
+            "201": {
+              description: "User specialization profile created successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/UserSpecializationProfileResponse" },
+                },
+              },
+            },
+            "400": {
+              description: "Validation error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized - Invalid or missing token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+        put: {
+          summary: "Update User Specializations",
+          description: "Replace all specializations for the authenticated user. Deletes existing specializations and creates new ones. Authentication required.",
+          tags: ["User Specializations Profile"],
+          security: [{ bearerAuth: [] }],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    specializations: {
+                      type: "array",
+                      description: "Array of specialization IDs to assign to the user",
+                      items: {
+                        type: "integer"
+                      },
+                      example: [3, 4, 6],
+                      minItems: 1
+                    }
+                  },
+                  required: ["specializations"],
+                },
+              },
+            },
+          },
+          responses: {
+            "200": {
+              description: "User specializations updated successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/UserSpecializationProfileResponse" },
+                },
+              },
+            },
+            "400": {
+              description: "Validation error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized - Invalid or missing token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+        delete: {
+          summary: "Delete User Specializations",
+          description: "Delete all specializations for the authenticated user. Authentication required.",
+          tags: ["User Specializations Profile"],
+          security: [{ bearerAuth: [] }],
+          responses: {
+            "200": {
+              description: "User specializations deleted successfully",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    properties: {
+                      success: { type: "boolean", example: true },
+                      message: { type: "string", example: "User specialization profile deleted successfully" },
+                    },
+                  },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized - Invalid or missing token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "User specialization profile not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/user/user-specialization/me": {
+        get: {
+          summary: "Get Current User Specialization Profile",
+          description: "Retrieve all specializations assigned to the authenticated user.",
+          tags: ["User Specializations Profile"],
+          security: [{ bearerAuth: [] }],
+          responses: {
+            "200": {
+              description: "Current user specializations retrieved successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/UserSpecializationProfileResponse" },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized - Invalid or missing token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/user/admin/user-specialization/user/{userId}": {
+        get: {
+          summary: "Get User Specializations by User ID",
+          description: "Retrieve all specializations assigned to a specific user. Authentication required.",
+          tags: ["Admin User Specializations Profile"],
+          security: [{ bearerAuth: [] }],
+          parameters: [
+            {
+              name: "userId",
+              in: "path",
+              required: true,
+              description: "User ID to retrieve specializations for",
+              schema: { type: "integer", example: 1 },
+            },
+          ],
+          responses: {
+            "200": {
+              description: "User specializations retrieved successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/UserSpecializationProfileResponse" },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized - Invalid or missing token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "User not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/user/admin/user-specialization/{id}": {
+        get: {
+          summary: "Get User Specialization by ID",
+          description: "Retrieve a specific user specialization profile by its ID. Authentication required.",
+          tags: ["Admin User Specializations Profile"],
+          security: [{ bearerAuth: [] }],
+          parameters: [
+            {
+              name: "id",
+              in: "path",
+              required: true,
+              description: "User specialization profile ID",
+              schema: { type: "integer", example: 1 },
+            },
+          ],
+          responses: {
+            "200": {
+              description: "User specialization profile retrieved successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/UserSpecializationProfileResponse" },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized - Invalid or missing token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "User specialization profile not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+        put: {
+          summary: "Update User Specialization",
+          description: "Update a user specialization profile. Authentication required.",
+          tags: ["User"],
+          security: [{ bearerAuth: [] }],
+          parameters: [
+            {
+              name: "id",
+              in: "path",
+              required: true,
+              description: "User specialization profile ID",
+              schema: { type: "integer", example: 1 },
+            },
+          ],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    specialization: {
+                      type: "integer",
+                      description: "Specialization ID (optional)",
+                      example: 2,
+                    },
+                    metadata: {
+                      type: "object",
+                      description: "Specialization metadata (optional)",
+                      nullable: true,
+                      example: { permissions: ["read", "write", "delete"] },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          responses: {
+            "200": {
+              description: "User specialization profile updated successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/UserSpecializationProfileResponse" },
+                },
+              },
+            },
+            "400": {
+              description: "Validation error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized - Invalid or missing token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "User specialization profile not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+        delete: {
+          summary: "Delete User Specialization",
+          description: "Delete a user specialization profile. Authentication required.",
+          tags: ["User"],
+          security: [{ bearerAuth: [] }],
+          parameters: [
+            {
+              name: "id",
+              in: "path",
+              required: true,
+              description: "User specialization profile ID",
+              schema: { type: "integer", example: 1 },
+            },
+          ],
+          responses: {
+            "200": {
+              description: "User specialization profile deleted successfully",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    properties: {
+                      success: { type: "boolean" },
+                      message: { type: "string" },
+                    },
+                  },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized - Invalid or missing token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "User specialization profile not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/user/specializations": {
+        get: {
+          summary: "Get All Specializations",
+          description: "Retrieve all specializations in a flat list",
+          tags: ["Specializations"],
+          responses: {
+            "200": {
+              description: "Specializations retrieved successfully",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    properties: {
+                      success: { type: "boolean" },
+                      data: {
+                        type: "array",
+                        items: { $ref: "#/components/schemas/Specialization" }
+                      }
+                    }
+                  }
+                }
+              }
+            },
+            "400": {
+              description: "Error retrieving specializations",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            }
+          }
+        },
+        post: {
+          summary: "Create Specialization",
+          description: "Create a new specialization",
+          tags: ["Specializations"],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    name: {
+                      type: "string",
+                      description: "Specialization name",
+                      example: "Doctor"
+                    },
+                    parentId: {
+                      type: "integer",
+                      nullable: true,
+                      description: "Parent specialization ID (null for root)",
+                      example: null
+                    },
+                    description: {
+                      type: "string",
+                      nullable: true,
+                      description: "Specialization description",
+                      example: "Medical doctor specialization"
+                    },
+                    imageUrl: {
+                      type: "string",
+                      nullable: true,
+                      description: "Specialization image URL",
+                      example: "https://example.com/images/doctor.png"
+                    }
+                  },
+                  required: ["name"]
+                }
+              }
+            }
+          },
+          responses: {
+            "201": {
+              description: "Specialization created successfully",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    properties: {
+                      success: { type: "boolean" },
+                      data: { $ref: "#/components/schemas/Specialization" }
+                    }
+                  }
+                }
+              }
+            },
+            "400": {
+              description: "Validation error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            }
+          }
+        }
+      },
+      "/api/user/specializations/tree": {
+        get: {
+          summary: "Get Specializations Tree",
+          description: "Retrieve specializations in hierarchical tree structure",
+          tags: ["Specializations"],
+          responses: {
+            "200": {
+              description: "Specializations tree retrieved successfully",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    properties: {
+                      success: { type: "boolean" },
+                      data: {
+                        type: "array",
+                        items: { $ref: "#/components/schemas/SpecializationTree" }
+                      }
+                    }
+                  }
+                }
+              }
+            },
+            "400": {
+              description: "Error retrieving specializations",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            }
+          }
+        }
+      },
+      "/api/user/specializations/{id}": {
+        get: {
+          summary: "Get Specialization by ID",
+          description: "Retrieve a specific specialization by its ID",
+          tags: ["Specializations"],
+          parameters: [
+            {
+              name: "id",
+              in: "path",
+              required: true,
+              description: "Specialization ID",
+              schema: { type: "integer", example: 1 }
+            }
+          ],
+          responses: {
+            "200": {
+              description: "Specialization retrieved successfully",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    properties: {
+                      success: { type: "boolean" },
+                      data: { $ref: "#/components/schemas/Specialization" }
+                    }
+                  }
+                }
+              }
+            },
+            "404": {
+              description: "Specialization not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            },
+            "400": {
+              description: "Error retrieving specialization",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            }
+          }
+        },
+        put: {
+          summary: "Update Specialization",
+          description: "Update a specialization",
+          tags: ["Specializations"],
+          parameters: [
+            {
+              name: "id",
+              in: "path",
+              required: true,
+              description: "Specialization ID",
+              schema: { type: "integer", example: 1 }
+            }
+          ],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    name: {
+                      type: "string",
+                      description: "Specialization name",
+                      example: "Dentist"
+                    },
+                    parentId: {
+                      type: "integer",
+                      nullable: true,
+                      description: "Parent specialization ID",
+                      example: 1
+                    },
+                    description: {
+                      type: "string",
+                      nullable: true,
+                      description: "Specialization description",
+                      example: "Dental specialization"
+                    },
+                    imageUrl: {
+                      type: "string",
+                      nullable: true,
+                      description: "Specialization image URL",
+                      example: "https://example.com/images/dentist.png"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          responses: {
+            "200": {
+              description: "Specialization updated successfully",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    properties: {
+                      success: { type: "boolean" },
+                      data: { $ref: "#/components/schemas/Specialization" }
+                    }
+                  }
+                }
+              }
+            },
+            "404": {
+              description: "Specialization not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            },
+            "400": {
+              description: "Validation or update error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            }
+          }
+        },
+        delete: {
+          summary: "Delete Specialization",
+          description: "Delete a specialization (cannot delete if has children)",
+          tags: ["Specializations"],
+          parameters: [
+            {
+              name: "id",
+              in: "path",
+              required: true,
+              description: "Specialization ID",
+              schema: { type: "integer", example: 1 }
+            }
+          ],
+          responses: {
+            "200": {
+              description: "Specialization deleted successfully",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    properties: {
+                      success: { type: "boolean" },
+                      message: { type: "string" }
+                    }
+                  }
+                }
+              }
+            },
+            "404": {
+              description: "Specialization not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            },
+            "400": {
+              description: "Cannot delete specialization with children or other error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            }
+          }
+        }
+      },
+      "/api/user/metadata": {
+        get: {
+          summary: "Get All Metadata",
+          description: "Retrieve all metadata for the authenticated user. Returns the entire metadata JSON object.",
+          tags: ["User Metadata"],
+          security: [{ bearerAuth: [] }],
+          responses: {
+            "200": {
+              description: "Metadata retrieved successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/UserMetadataResponse" }
+                }
+              }
+            },
+            "401": {
+              description: "Unauthorized - Invalid or missing token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            },
+            "404": {
+              description: "User profile not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            }
+          }
+        },
+        post: {
+          summary: "Set Metadata",
+          description: "Set entire metadata object (overwrites all existing metadata). Use PATCH to merge instead.",
+          tags: ["User Metadata"],
+          security: [{ bearerAuth: [] }],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    metadata: {
+                      $ref: "#/components/schemas/UserMetadata"
+                    }
+                  },
+                  required: ["metadata"]
+                }
+              }
+            }
+          },
+          responses: {
+            "200": {
+              description: "Metadata set successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/UserMetadataResponse" }
+                }
+              }
+            },
+            "400": {
+              description: "Validation error - metadata must be a valid object",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            },
+            "401": {
+              description: "Unauthorized - Invalid or missing token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            },
+            "404": {
+              description: "User profile not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            }
+          }
+        },
+        patch: {
+          summary: "Update Metadata",
+          description: "Merge updates into existing metadata. Only specified fields are updated, others are preserved.",
+          tags: ["User Metadata"],
+          security: [{ bearerAuth: [] }],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    updates: {
+                      type: "object",
+                      description: "Partial metadata object with fields to update",
+                      additionalProperties: true,
+                      example: { theme: "light", language: "fr" }
+                    }
+                  },
+                  required: ["updates"]
+                }
+              }
+            }
+          },
+          responses: {
+            "200": {
+              description: "Metadata merged successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/UserMetadataResponse" }
+                }
+              }
+            },
+            "400": {
+              description: "Validation error - updates must be a valid object",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            },
+            "401": {
+              description: "Unauthorized - Invalid or missing token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            },
+            "404": {
+              description: "User profile not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            }
+          }
+        },
+        delete: {
+          summary: "Clear All Metadata",
+          description: "Delete all metadata for the authenticated user. Sets metadata to null.",
+          tags: ["User Metadata"],
+          security: [{ bearerAuth: [] }],
+          responses: {
+            "200": {
+              description: "All metadata cleared successfully",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    properties: {
+                      success: { type: "boolean", example: true },
+                      message: { type: "string", example: "All metadata cleared successfully" }
+                    }
+                  }
+                }
+              }
+            },
+            "401": {
+              description: "Unauthorized - Invalid or missing token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            },
+            "404": {
+              description: "User profile not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            }
+          }
+        }
+      },
+      "/api/user/metadata/{key}": {
+        get: {
+          summary: "Get Metadata Field",
+          description: "Retrieve a specific metadata field value by key.",
+          tags: ["User Metadata"],
+          security: [{ bearerAuth: [] }],
+          parameters: [
+            {
+              name: "key",
+              in: "path",
+              required: true,
+              description: "Metadata field key",
+              schema: { type: "string", example: "theme" }
+            }
+          ],
+          responses: {
+            "200": {
+              description: "Metadata field retrieved successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/UserMetadataResponse" }
+                }
+              }
+            },
+            "401": {
+              description: "Unauthorized - Invalid or missing token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            },
+            "404": {
+              description: "Metadata field not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            }
+          }
+        },
+        post: {
+          summary: "Set Metadata Field",
+          description: "Set or update a specific metadata field. Creates or overwrites the field value.",
+          tags: ["User Metadata"],
+          security: [{ bearerAuth: [] }],
+          parameters: [
+            {
+              name: "key",
+              in: "path",
+              required: true,
+              description: "Metadata field key",
+              schema: { type: "string", example: "theme" }
+            }
+          ],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    value: {
+                      description: "Value to set for the metadata field (any type)",
+                      example: "dark"
+                    }
+                  },
+                  required: ["value"]
+                }
+              }
+            }
+          },
+          responses: {
+            "200": {
+              description: "Metadata field updated successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/UserMetadataResponse" }
+                }
+              }
+            },
+            "401": {
+              description: "Unauthorized - Invalid or missing token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            },
+            "404": {
+              description: "User profile not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            }
+          }
+        },
+        delete: {
+          summary: "Delete Metadata Field",
+          description: "Remove a specific metadata field by key.",
+          tags: ["User Metadata"],
+          security: [{ bearerAuth: [] }],
+          parameters: [
+            {
+              name: "key",
+              in: "path",
+              required: true,
+              description: "Metadata field key to delete",
+              schema: { type: "string", example: "theme" }
+            }
+          ],
+          responses: {
+            "200": {
+              description: "Metadata field deleted successfully",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    properties: {
+                      success: { type: "boolean", example: true },
+                      message: { type: "string", example: "Metadata field 'theme' deleted successfully" },
+                      data: {
+                        $ref: "#/components/schemas/UserMetadata",
+                        description: "Remaining metadata after deletion"
+                      }
+                    }
+                  }
+                }
+              }
+            },
+            "401": {
+              description: "Unauthorized - Invalid or missing token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            },
+            "404": {
+              description: "Metadata field not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" }
+                }
+              }
+            }
+          }
+        }
+      },
+      "/api/media/avatar/upload": {
+        post: {
+          summary: "Upload Avatar",
+          description: "Upload a user avatar image. Authentication required.",
+          tags: ["Media"],
+          security: [{ bearerAuth: [] }],
+          requestBody: {
+            required: true,
+            content: {
+              "multipart/form-data": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    images: {
+                      type: "array",
+                      items: {
+                        type: "string",
+                        format: "binary",
+                      },
+                      description: "Avatar image files to upload (max 10)",
+                    },
+                  },
+                  required: ["images"],
+                },
+              },
+            },
+          },
+          responses: {
+            "201": {
+              description: "Avatar uploaded successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/MediaResponse" },
+                },
+              },
+            },
+            "400": {
+              description: "Invalid file or validation error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized - Authentication required",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "413": {
+              description: "File too large",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/media/avatar/{filename}": {
+        get: {
+          summary: "Get Avatar Image",
+          description:
+            "Retrieve a user avatar image by filename. Authentication required.",
+          tags: ["Media"],
+          security: [{ bearerAuth: [] }],
+          parameters: [
+            {
+              name: "filename",
+              in: "path",
+              required: true,
+              description: "Avatar filename",
+              schema: { type: "string", example: "avatar-1609459200000.png" },
+            },
+          ],
+          responses: {
+            "200": {
+              description: "Avatar image retrieved successfully",
+              content: { "image/*": {} },
+            },
+            "401": {
+              description: "Unauthorized - Authentication required",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "Avatar not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+        delete: {
+          summary: "Delete Avatar",
+          description:
+            "Delete a user avatar by filename. Authentication required.",
+          tags: ["Media"],
+          security: [{ bearerAuth: [] }],
+          parameters: [
+            {
+              name: "filename",
+              in: "path",
+              required: true,
+              description: "Avatar filename",
+              schema: { type: "string", example: "avatar-1609459200000.png" },
+            },
+          ],
+          responses: {
+            "200": {
+              description: "Avatar deleted successfully",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    properties: {
+                      success: { type: "boolean" },
+                      message: { type: "string" },
+                    },
+                  },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized - Authentication required",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "Avatar not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/media/private/upload": {
+        post: {
+          summary: "Upload Private File",
+          description: "Upload a private file. Authentication required.",
+          tags: ["Media"],
+          security: [{ bearerAuth: [] }],
+          requestBody: {
+            required: true,
+            content: {
+              "multipart/form-data": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    images: {
+                      type: "array",
+                      items: {
+                        type: "string",
+                        format: "binary",
+                      },
+                      description: "Files to upload (max 10)",
+                    },
+                  },
+                  required: ["images"],
+                },
+              },
+            },
+          },
+          responses: {
+            "201": {
+              description: "File uploaded successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/MediaResponse" },
+                },
+              },
+            },
+            "400": {
+              description: "Invalid file or validation error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized - Authentication required",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "413": {
+              description: "File too large",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/media/private/{filename}": {
+        get: {
+          summary: "Get Private File",
+          description:
+            "Retrieve a private file by filename. Authentication required.",
+          tags: ["Media"],
+          security: [{ bearerAuth: [] }],
+          parameters: [
+            {
+              name: "filename",
+              in: "path",
+              required: true,
+              description: "File filename",
+              schema: { type: "string", example: "document-1609459200000.pdf" },
+            },
+          ],
+          responses: {
+            "200": {
+              description: "File retrieved successfully",
+              content: { "application/*": {} },
+            },
+            "401": {
+              description: "Unauthorized - Authentication required",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "File not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+        delete: {
+          summary: "Delete Private File",
+          description:
+            "Delete a private file by filename. Authentication required.",
+          tags: ["Media"],
+          security: [{ bearerAuth: [] }],
+          parameters: [
+            {
+              name: "filename",
+              in: "path",
+              required: true,
+              description: "File filename",
+              schema: { type: "string", example: "document-1609459200000.pdf" },
+            },
+          ],
+          responses: {
+            "200": {
+              description: "File deleted successfully",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    properties: {
+                      success: { type: "boolean" },
+                      message: { type: "string" },
+                    },
+                  },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized - Authentication required",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "File not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/user/admin/roles": {
+        get: {
+          summary: "Get All Application Roles (Admin Only)",
+          description: "Retrieve all available application roles. Admin access required.",
+          tags: ["Admin"],
+          security: [{ bearerAuth: [] }],
+          responses: {
+            "200": {
+              description: "Roles retrieved successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/AdminRoleResponse" },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized - Authentication required",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "403": {
+              description: "Forbidden - Admin access required",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+        post: {
+          summary: "Create New Application Role (Super Admin Only)",
+          description: "Create a new application role with specified permissions. Super Admin access required.",
+          tags: ["Admin"],
+          security: [{ bearerAuth: [] }],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/CreateAppRoleRequest" },
+              },
+            },
+          },
+          responses: {
+            "201": {
+              description: "Role created successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/AdminRoleResponse" },
+                },
+              },
+            },
+            "400": {
+              description: "Validation error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized - Authentication required",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "403": {
+              description: "Forbidden - Super Admin access required",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/user/admin/roles/active": {
+        get: {
+          summary: "Get Active Application Roles (Admin Only)",
+          description: "Retrieve only active application roles. Admin access required.",
+          tags: ["Admin"],
+          security: [{ bearerAuth: [] }],
+          responses: {
+            "200": {
+              description: "Active roles retrieved successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/AdminRoleResponse" },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized - Authentication required",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "403": {
+              description: "Forbidden - Admin access required",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/user/admin/roles/{id}": {
+        get: {
+          summary: "Get Application Role by ID (Admin Only)",
+          description: "Retrieve a specific application role by its ID. Admin access required.",
+          tags: ["Admin"],
+          security: [{ bearerAuth: [] }],
+          parameters: [
+            {
+              name: "id",
+              in: "path",
+              required: true,
+              description: "Role ID",
+              schema: { type: "integer", example: 1 },
+            },
+          ],
+          responses: {
+            "200": {
+              description: "Role retrieved successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/AdminRoleResponse" },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized - Authentication required",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "403": {
+              description: "Forbidden - Admin access required",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "Role not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+        put: {
+          summary: "Update Application Role (Super Admin Only)",
+          description: "Update an existing application role. Super Admin access required.",
+          tags: ["Admin"],
+          security: [{ bearerAuth: [] }],
+          parameters: [
+            {
+              name: "id",
+              in: "path",
+              required: true,
+              description: "Role ID",
+              schema: { type: "integer", example: 1 },
+            },
+          ],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/UpdateAppRoleRequest" },
+              },
+            },
+          },
+          responses: {
+            "200": {
+              description: "Role updated successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/AdminRoleResponse" },
+                },
+              },
+            },
+            "400": {
+              description: "Validation error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized - Authentication required",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "403": {
+              description: "Forbidden - Super Admin access required",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "Role not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+        delete: {
+          summary: "Delete Application Role (Super Admin Only)",
+          description: "Delete an application role. Super Admin access required.",
+          tags: ["Admin"],
+          security: [{ bearerAuth: [] }],
+          parameters: [
+            {
+              name: "id",
+              in: "path",
+              required: true,
+              description: "Role ID",
+              schema: { type: "integer", example: 1 },
+            },
+          ],
+          responses: {
+            "200": {
+              description: "Role deleted successfully",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    properties: {
+                      success: { type: "boolean" },
+                      message: { type: "string" },
+                    },
+                  },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized - Authentication required",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "403": {
+              description: "Forbidden - Super Admin access required",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "Role not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/marketing/contacts": {
+        post: {
+          summary: "Create Marketing Contact",
+          description: "Create a new marketing contact (email or phone required).",
+          tags: ["Marketing"],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/CreateMarketingContactRequest" },
+              },
+            },
+          },
+          responses: {
+            "201": {
+              description: "Contact created successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/MarketingContactResponse" },
+                },
+              },
+            },
+            "400": {
+              description: "Validation error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/marketing/consents": {
+        post: {
+          summary: "Create Marketing Consent",
+          description: "Create a consent record for a contact.",
+          tags: ["Marketing"],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/CreateMarketingConsentRequest" },
+              },
+            },
+          },
+          responses: {
+            "201": {
+              description: "Consent created successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/MarketingConsentResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "Contact not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "400": {
+              description: "Validation error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/marketing/segments": {
+        post: {
+          summary: "Create Marketing Segment",
+          description: "Create a new segment definition.",
+          tags: ["Marketing"],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/CreateMarketingSegmentRequest" },
+              },
+            },
+          },
+          responses: {
+            "201": {
+              description: "Segment created successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/MarketingSegmentResponse" },
+                },
+              },
+            },
+            "400": {
+              description: "Invalid segment definition",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/marketing/campaigns": {
+        post: {
+          summary: "Create Marketing Campaign",
+          description: "Create a new marketing campaign.",
+          tags: ["Marketing"],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/CreateMarketingCampaignRequest" },
+              },
+            },
+          },
+          responses: {
+            "201": {
+              description: "Campaign created successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/MarketingCampaignResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "Segment not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "400": {
+              description: "Validation error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/marketing/campaigns/{campaignId}/execute": {
+        post: {
+          summary: "Execute Marketing Campaign",
+          description: "Trigger execution of a campaign and create a run record.",
+          tags: ["Marketing"],
+          parameters: [
+            {
+              name: "campaignId",
+              in: "path",
+              required: true,
+              description: "Campaign ID",
+              schema: { type: "integer", example: 1 },
+            },
+          ],
+          responses: {
+            "202": {
+              description: "Campaign execution queued",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/MarketingCampaignRunResponse" },
+                },
+              },
+            },
+            "400": {
+              description: "Invalid campaign id",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "Campaign or segment not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/messaging/send": {
+        post: {
+          summary: "Send Message",
+          description: "Send a message for immediate processing.",
+          tags: ["Messaging"],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/CreateMessagingMessageRequest" },
+              },
+            },
+          },
+          responses: {
+            "202": {
+              description: "Message accepted for processing",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/MessagingAcceptedResponse" },
+                },
+              },
+            },
+            "400": {
+              description: "Validation error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/messaging/schedule": {
+        post: {
+          summary: "Schedule Message",
+          description: "Schedule a message for future processing.",
+          tags: ["Messaging"],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/ScheduleMessagingMessageRequest" },
+              },
+            },
+          },
+          responses: {
+            "202": {
+              description: "Message scheduled for processing",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/MessagingAcceptedResponse" },
+                },
+              },
+            },
+            "400": {
+              description: "Validation error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/api/messaging/{messageId}": {
+        get: {
+          summary: "Get Message Status",
+          description: "Fetch a message and its delivery status by ID.",
+          tags: ["Messaging"],
+          parameters: [
+            {
+              name: "messageId",
+              in: "path",
+              required: true,
+              description: "Message ID",
+              schema: { type: "string", example: "1" },
+            },
+          ],
+          responses: {
+            "200": {
+              description: "Message retrieved successfully",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/MessagingMessageResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "Message not found",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    tags: [
+      {
+        name: "Health",
+        description: "Health check and service status endpoints",
+      },
+      {
+        name: "Authentication",
+        description: "User authentication and authorization endpoints",
+      },
+      {
+        name: "User",
+        description: "User management endpoints",
+      },
+      {
+        name: "Specializations",
+        description: "Specialization hierarchy management endpoints",
+      },
+      {
+        name: "Media",
+        description:
+          "Media management endpoints for uploads, retrieval, and deletion",
+      },
+      {
+        name: "Marketing",
+        description: "Marketing service endpoints for contacts, consents, segments, and campaigns",
+      },
+      {
+        name: "Messaging",
+        description: "Messaging service endpoints for sending and tracking messages",
+      },
+      {
+        name: "User Metadata",
+        description: "Endpoints for managing user-specific metadata",
+      },
+      {
+        name: "User Specializations Profile",
+        description: "Endpoints for managing user specializations profiles",
+      },
+      {
+        name: "Admin",
+        description: "Admin-only endpoints for managing application roles and permissions. Requires authentication and admin/super-admin role.",
+      },
+    ],
+  },
+  apis: [
+    "./apps/api-gateway-service/src/routes/*.ts",
+    "./apps/auth-service/src/routes/*.ts",
+    "./apps/user-service/src/routes/*.ts",
+    "./apps/media-service/src/routes/*.ts",
+    "./apps/marketing-service/src/routes/*.ts",
+    "./apps/messaging-service/src/routes/*.ts",
+    "./apps/api-gateway-service/src/routes/*.js",
+    "./apps/auth-service/src/routes/*.js",
+    "./apps/user-service/src/routes/*.js",
+    "./apps/media-service/src/routes/*.js",
+    "./apps/marketing-service/src/routes/*.js",
+    "./apps/messaging-service/src/routes/*.js",
+  ],
+};
+
+export const swaggerSpec = swaggerJsdoc(options);
+
+export const swaggerUiOptions = {
+  customCss: `
+      /* Main background and text */
+      body {
+        background-color: #1a1a1a;
+        color: #f0f0f0 !important;
+      }
+
+      .swagger-ui {
+        background-color: #1a1a1a;
+        color: #f0f0f0 !important;
+      }
+
+      /* Force ALL text to be white */
+      .swagger-ui *,
+      .swagger-ui .opblock-tag,
+      .swagger-ui .opblock .opblock-summary-operation-id,
+      .swagger-ui .opblock .opblock-summary-path,
+      .swagger-ui .opblock .opblock-summary-path span,
+      .swagger-ui .opblock .opblock-summary-description,
+      .swagger-ui .model-title,
+      .swagger-ui label,
+      .swagger-ui span,
+      .swagger-ui h1, .swagger-ui h2, .swagger-ui h3, .swagger-ui h4, .swagger-ui h5, .swagger-ui h6,
+      .swagger-ui .parameter__name,
+      .swagger-ui .parameter__type,
+      .swagger-ui table thead tr th,
+      .swagger-ui table tbody tr td,
+      .swagger-ui .response-col_status,
+      .swagger-ui .response-col_description,
+      .swagger-ui .tab li,
+      .swagger-ui section.models h4,
+      .swagger-ui section.models h5,
+      .swagger-ui .servers > label {
+        color: #f0f0f0 !important;
+      }
+
+      /* Override any SVGs or special elements */
+      .swagger-ui svg {
+        fill: #f0f0f0 !important;
+      }
+
+      .swagger-ui .scheme-container {
+        background-color: #1a1a1a;
+      }
+
+      .swagger-ui .opblock .opblock-section-header {
+        background-color: #1a1a1a;
+      }
+
+      .swagger-ui .dialog-ux .modal-ux {
+        background-color: #1a1a1a;
+      }
+
+      /* Operation blocks */
+      .swagger-ui .opblock {
+        background-color: #2d2d2d;
+        border-color: #444;
+      }
+
+      /* Input fields */
+      .swagger-ui input[type=text],
+      .swagger-ui textarea {
+        background-color: rgb(12, 12, 12);
+        color: white !important;
+      }
+
+      .swagger-ui input,
+      .swagger-ui select,
+      .swagger-ui textarea {
+        background-color: #333;
+        color: white !important;
+      }
+
+      /* Code blocks */
+      .swagger-ui .highlight-code,
+      .swagger-ui .microlight {
+        background-color:rgb(69, 69, 68) !important;
+        color: #f8f8f2 !important;
+      }
+    `,
+  customSiteTitle: "GGCoach API Documentation",
+  customfavIcon: "/favicon.ico",
+};
+
+export const swaggerHandler = (_req: Request, res: Response) => {
+  res.setHeader("Content-Type", "application/json");
+  res.send(swaggerSpec);
+};