openapi: 3.0.0
info:
  title: Kyndlo API
  description: Complete API documentation for the Kyndlo dating application
  version: 3.0.0
  contact:
    name: Kyndlo Support
    email: support@kyndlo.com

servers:
  - url: http://localhost:3000/api/v1
    description: Development server
  - url: https://api.kyndlo.com/v1
    description: Production server

security:
  - bearerAuth: []

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    # Authentication Schemas
    PhoneVerification:
      type: object
      required:
        - phone
      properties:
        phone:
          type: string
          pattern: '^\+[1-9]\d{1,14}$'
          example: "+17203092726"

    VerificationCode:
      type: object
      required:
        - phone
        - code
      properties:
        phone:
          type: string
          pattern: '^\+[1-9]\d{1,14}$'
        code:
          type: string
          minLength: 6
          maxLength: 6

    AuthResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        data:
          type: object
          properties:
            token:
              type: string
            user:
              $ref: '#/components/schemas/User'

    # User Schemas
    User:
      type: object
      properties:
        _id:
          type: string
        phone:
          type: object
          properties:
            number:
              type: string
            verified:
              type: boolean
            attempts:
              type: integer
            twoFactorEnabled:
              type: boolean
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
          format: email
        birthdate:
          type: string
          format: date
        gender:
          type: string
          enum: [male, female, non-binary, prefer-not-to-say]
        address:
          type: object
          properties:
            street:
              type: string
            city:
              type: string
            state:
              type: string
            zipCode:
              type: string
            country:
              type: string
        zodiac:
          type: string
        chineseZodiac:
          type: string
        location:
          type: object
          properties:
            type:
              type: string
              enum: [Point]
            coordinates:
              type: array
              items:
                type: number
              minItems: 2
              maxItems: 2
        bio:
          type: string
        avatar:
          type: string
        animalSpirit:
          $ref: '#/components/schemas/AnimalSpirit'
        preferences:
          $ref: '#/components/schemas/UserPreferences'
        interests:
          type: array
          items:
            type: string
        xp:
          type: integer
        level:
          type: integer
        achievements:
          type: array
          items:
            type: string
        stats:
          type: object
          properties:
            activitiesAttended:
              type: integer
            activitiesOrganized:
              type: integer
            connectionsCount:
              type: integer
            reviewsGiven:
              type: integer
            reviewsReceived:
              type: integer
            averageRating:
              type: number
        isActive:
          type: boolean
        isVerified:
          type: boolean
        accountStatus:
          type: string
          enum: [active, deletion-pending, deleted]
          default: active
        deletionRequestedAt:
          type: string
          format: date-time
        deletionReason:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    AnimalSpirit:
      type: object
      properties:
        species:
          type: string
        name:
          type: string
        traits:
          type: array
          items:
            type: string
        evolutionStage:
          type: integer
        xp:
          type: integer
        abilities:
          type: array
          items:
            type: string
        imageUrl:
          type: string

    UserPreferences:
      type: object
      properties:
        activities:
          type: array
          items:
            type: string
        genres:
          type: array
          items:
            type: string
        ageRange:
          type: object
          properties:
            min:
              type: integer
              minimum: 18
              default: 18
            max:
              type: integer
              minimum: 18
              maximum: 100
              default: 65
        maxDistance:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
        budget:
          type: object
          properties:
            min:
              type: number
            max:
              type: number
            currency:
              type: string
        notifications:
          type: object
          properties:
            email:
              type: boolean
            push:
              type: boolean
            sms:
              type: boolean
            newMatches:
              type: boolean
            messages:
              type: boolean
            activities:
              type: boolean
            reminders:
              type: boolean
            marketing:
              type: boolean
        privacy:
          type: object
          properties:
            showProfile:
              type: boolean
            showActivity:
              type: boolean
            showLocation:
              type: boolean

    # Activity Schemas
    Activity:
      type: object
      properties:
        _id:
          type: string
        title:
          type: string
        description:
          type: string
        category:
          type: string
          enum: [social, sports, arts, food, adventure, wellness, education, entertainment, charity, other]
        location:
          type: object
          properties:
            type:
              type: string
              enum: [Point]
            coordinates:
              type: array
              items:
                type: number
            address:
              type: string
            city:
              type: string
            venue:
              type: string
        date:
          type: string
          format: date-time
        duration:
          type: integer
        capacity:
          type: object
          properties:
            min:
              type: integer
            max:
              type: integer
            current:
              type: integer
            waitlist:
              type: integer
        pricing:
          type: object
          properties:
            type:
              type: string
              enum: [free, paid, donation, sliding-scale]
            amount:
              type: number
            currency:
              type: string
            earlyBird:
              type: object
              properties:
                amount:
                  type: number
                deadline:
                  type: string
                  format: date-time
        requirements:
          type: object
          properties:
            minAge:
              type: integer
            maxAge:
              type: integer
            experience:
              type: string
              enum: [none, beginner, intermediate, advanced, expert]
            equipment:
              type: array
              items:
                type: string
            other:
              type: array
              items:
                type: string
        tags:
          type: array
          items:
            type: string
        images:
          type: array
          items:
            type: string
        virtualLink:
          type: string
        isVirtual:
          type: boolean
        isFeatured:
          type: boolean
        status:
          type: string
          enum: [draft, published, cancelled, completed]
        stats:
          type: object
          properties:
            views:
              type: integer
            interested:
              type: integer
            joined:
              type: integer
            rating:
              type: number
            reviews:
              type: integer
        createdBy:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    # Animal Schemas
    Animal:
      type: object
      properties:
        _id:
          type: string
        species:
          type: string
        scientificName:
          type: string
        commonName:
          type: string
        habitat:
          type: string
        characteristics:
          type: object
          properties:
            size:
              type: string
            weight:
              type: string
            lifespan:
              type: string
            diet:
              type: string
        behaviors:
          type: array
          items:
            type: string
        symbolism:
          type: array
          items:
            type: string
        abilities:
          type: array
          items:
            type: string
        compatibleWith:
          type: array
          items:
            type: string
        incompatibleWith:
          type: array
          items:
            type: string
        evolutionStages:
          type: array
          items:
            type: object
            properties:
              stage:
                type: integer
              name:
                type: string
              requirements:
                type: object
                properties:
                  xp:
                    type: integer
                  level:
                    type: integer
              imageUrl:
                type: string
        rarity:
          type: string
          enum: [common, uncommon, rare, epic, legendary]
        element:
          type: string
        stats:
          type: object
          properties:
            strength:
              type: integer
            wisdom:
              type: integer
            charisma:
              type: integer
            agility:
              type: integer
            creativity:
              type: integer
        images:
          type: object
          properties:
            profile:
              type: string
            avatar:
              type: string
            evolution:
              type: array
              items:
                type: string
        isActive:
          type: boolean
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    # Question Schemas
    Question:
      type: object
      properties:
        _id:
          type: string
        questionText:
          type: string
        category:
          type: string
          enum: [personality, lifestyle, values, goals, relationships, fun, deep, compatibility]
        dimension:
          type: string
          enum: [EI, SN, TF, JP]
        weight:
          type: integer
        optionType:
          type: string
          enum: [multiple-choice, scale, yes-no, text]
        options:
          type: array
          items:
            type: object
            properties:
              text:
                type: string
              value:
                type: string
              score:
                type: integer
        metadata:
          type: object
          properties:
            tags:
              type: array
              items:
                type: string
            difficulty:
              type: string
              enum: [easy, medium, hard]
            timeEstimate:
              type: integer
            followUpQuestions:
              type: array
              items:
                type: string
        isActive:
          type: boolean
        statistics:
          type: object
          properties:
            timesAnswered:
              type: integer
            averageScore:
              type: number
            skipRate:
              type: number
        createdBy:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    # Daily Message Schemas
    DailyMessage:
      type: object
      properties:
        _id:
          type: string
        content:
          type: string
        type:
          type: string
          enum: [inspirational, educational, fun-fact, challenge, reflection, community]
        mood:
          type: string
          enum: [uplifting, calming, energizing, thoughtful, playful, romantic]
        targetAudience:
          type: object
          properties:
            animalSpirits:
              type: array
              items:
                type: string
            mbtiTypes:
              type: array
              items:
                type: string
            ageRange:
              type: object
              properties:
                min:
                  type: integer
                max:
                  type: integer
            interests:
              type: array
              items:
                type: string
        media:
          type: object
          properties:
            imageUrl:
              type: string
            videoUrl:
              type: string
            audioUrl:
              type: string
        author:
          type: object
          properties:
            name:
              type: string
            title:
              type: string
            avatar:
              type: string
        scheduledFor:
          type: string
          format: date
        tags:
          type: array
          items:
            type: string
        priority:
          type: integer
        interactions:
          type: object
          properties:
            likes:
              type: integer
            shares:
              type: integer
            saves:
              type: integer
            views:
              type: integer
        isActive:
          type: boolean
        expiresAt:
          type: string
          format: date-time
        createdBy:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    # Assessment Schemas
    Assessment:
      type: object
      properties:
        _id:
          type: string
        name:
          type: string
        description:
          type: string
        type:
          type: string
          enum: [personality, compatibility, skills, interests, values, wellness]
        version:
          type: string
        questions:
          type: array
          items:
            type: string
        totalQuestions:
          type: integer
        estimatedTime:
          type: integer
        scoring:
          type: object
          properties:
            method:
              type: string
              enum: [sum, average, weighted, custom]
            ranges:
              type: array
              items:
                type: object
                properties:
                  min:
                    type: number
                  max:
                    type: number
                  label:
                    type: string
                  description:
                    type: string
        requirements:
          type: object
          properties:
            minAge:
              type: integer
            previousAssessments:
              type: array
              items:
                type: string
        isPublic:
          type: boolean
        isActive:
          type: boolean
        createdBy:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    AssessmentSession:
      type: object
      properties:
        _id:
          type: string
        assessmentId:
          type: string
        userId:
          type: string
        status:
          type: string
          enum: [in-progress, completed, abandoned]
        currentQuestionIndex:
          type: integer
        responses:
          type: array
          items:
            type: object
            properties:
              questionId:
                type: string
              answer:
                type: string
              score:
                type: number
              timestamp:
                type: string
                format: date-time
        results:
          type: object
          properties:
            totalScore:
              type: number
            percentile:
              type: number
            category:
              type: string
            insights:
              type: array
              items:
                type: string
            recommendations:
              type: array
              items:
                type: string
        startedAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
        timeSpent:
          type: integer

    # Product & Payment Schemas
    Product:
      type: object
      properties:
        _id:
          type: string
        name:
          type: string
        description:
          type: string
        category:
          type: string
          enum: [subscription, feature, activity, merchandise, credit]
        type:
          type: string
          enum: [physical, digital, service]
        stripeProductId:
          type: string
        price:
          type: object
          properties:
            amount:
              type: number
            currency:
              type: string
        pricingTiers:
          type: object
          properties:
            monthly:
              type: number
            quarterly:
              type: number
            yearly:
              type: number
        features:
          type: array
          items:
            type: string
        images:
          type: array
          items:
            type: string
        metadata:
          type: object
        stock:
          type: object
          properties:
            available:
              type: integer
            reserved:
              type: integer
            sold:
              type: integer
        isActive:
          type: boolean
        requiresVerification:
          type: boolean
        availableRegions:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    Transaction:
      type: object
      properties:
        _id:
          type: string
        userId:
          type: string
        productId:
          type: string
        type:
          type: string
          enum: [purchase, refund, subscription, renewal]
        amount:
          type: number
        currency:
          type: string
        status:
          type: string
          enum: [pending, processing, completed, failed, refunded]
        stripePaymentIntentId:
          type: string
        stripeChargeId:
          type: string
        paymentMethod:
          type: object
          properties:
            type:
              type: string
            last4:
              type: string
            brand:
              type: string
        metadata:
          type: object
        refundReason:
          type: string
        refundedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    # Admin Schemas
    Role:
      type: object
      properties:
        _id:
          type: string
        name:
          type: string
        slug:
          type: string
        description:
          type: string
        permissions:
          type: array
          items:
            type: string
        level:
          type: integer
          minimum: 1
          maximum: 10
        isSystemRole:
          type: boolean
        isActive:
          type: boolean
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    Permission:
      type: object
      properties:
        _id:
          type: string
        name:
          type: string
        description:
          type: string
        resource:
          type: string
          enum: [users, activities, animals, questions, messages, analytics, payments, settings]
        actions:
          type: array
          items:
            type: string
            enum: [create, read, update, delete, manage]
        isActive:
          type: boolean
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    AdminUser:
      type: object
      properties:
        _id:
          type: string
        userId:
          type: string
        roleId:
          type: string
        email:
          type: string
        role:
          type: string
        permissions:
          type: array
          items:
            type: string
        employeeId:
          type: string
        department:
          type: string
        title:
          type: string
        isActive:
          type: boolean
        isSuperAdmin:
          type: boolean
        lastLoginAt:
          type: string
          format: date-time
        allowedIPs:
          type: array
          items:
            type: string
        accessExpiresAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    # Common Response Schemas
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        data:
          type: object

    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
        error:
          type: object
          properties:
            code:
              type: string
            details:
              type: string

    PaginatedResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        data:
          type: object
          properties:
            items:
              type: array
              items:
                type: object
            pagination:
              type: object
              properties:
                page:
                  type: integer
                limit:
                  type: integer
                total:
                  type: integer
                totalPages:
                  type: integer
                hasNextPage:
                  type: boolean
                hasPrevPage:
                  type: boolean

paths:
  # Authentication Endpoints
  /auth/request-code:
    post:
      summary: Request SMS verification code
      tags: [Authentication]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneVerification'
      responses:
        200:
          description: Verification code sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        429:
          description: Too many requests

  /auth/verify-code:
    post:
      summary: Verify SMS code and get JWT token
      tags: [Authentication]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationCode'
      responses:
        200:
          description: Code verified successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        401:
          description: Invalid code

  # User Endpoints
  /users:
    get:
      summary: Get all users
      tags: [Users]
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
      responses:
        200:
          description: Users retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'

    post:
      summary: Create a new user
      tags: [Users]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        201:
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /users/me:
    get:
      summary: Get current user profile
      tags: [Users]
      responses:
        200:
          description: User profile retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /users/profile:
    put:
      summary: Update user profile
      tags: [Users]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        200:
          description: Profile updated successfully

  /users/{id}:
    get:
      summary: Get user by ID
      tags: [Users]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: User retrieved successfully

    put:
      summary: Update user
      tags: [Users]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        200:
          description: User updated successfully

    delete:
      summary: Delete user
      tags: [Users]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: User deleted successfully

  /users/activity:
    get:
      summary: Get user activity history
      tags: [Users]
      responses:
        200:
          description: Activity history retrieved

  /users/xp:
    post:
      summary: Add XP to user
      tags: [Users]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                amount:
                  type: integer
                reason:
                  type: string
      responses:
        200:
          description: XP added successfully

  /users/match:
    post:
      summary: Create a match between users
      tags: [Users]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                targetUserId:
                  type: string
      responses:
        200:
          description: Match created successfully

  /users/verify-phone:
    post:
      summary: Verify phone number
      tags: [Users]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationCode'
      responses:
        200:
          description: Phone verified successfully

  /users/resend-code:
    post:
      summary: Resend verification code
      tags: [Users]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                phone:
                  type: string
      responses:
        200:
          description: Code resent successfully

  # Activity Endpoints
  /activities:
    get:
      summary: Get all activities
      tags: [Activities]
      security: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
        - name: category
          in: query
          schema:
            type: string
        - name: location
          in: query
          schema:
            type: string
      responses:
        200:
          description: Activities retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'

    post:
      summary: Create a new activity
      tags: [Activities]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Activity'
      responses:
        201:
          description: Activity created successfully

  /activities/search:
    get:
      summary: Search activities
      tags: [Activities]
      security: []
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
        - name: filters
          in: query
          schema:
            type: object
      responses:
        200:
          description: Search results retrieved

  /activities/trending:
    get:
      summary: Get trending activities
      tags: [Activities]
      security: []
      responses:
        200:
          description: Trending activities retrieved

  /activities/upcoming:
    get:
      summary: Get upcoming activities
      tags: [Activities]
      security: []
      responses:
        200:
          description: Upcoming activities retrieved

  /activities/popular:
    get:
      summary: Get popular activities
      tags: [Activities]
      security: []
      responses:
        200:
          description: Popular activities retrieved

  /activities/available:
    get:
      summary: Get activities with available spots
      tags: [Activities]
      security: []
      responses:
        200:
          description: Available activities retrieved

  /activities/statistics:
    get:
      summary: Get overall activity statistics
      tags: [Activities]
      security: []
      responses:
        200:
          description: Statistics retrieved

  /activities/recommendations:
    get:
      summary: Get recommended activities for user
      tags: [Activities]
      responses:
        200:
          description: Recommendations retrieved

  /activities/category/{category}:
    get:
      summary: Get activities by category
      tags: [Activities]
      security: []
      parameters:
        - name: category
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Activities retrieved

  /activities/free:
    get:
      summary: Get free activities
      tags: [Activities]
      security: []
      responses:
        200:
          description: Free activities retrieved

  /activities/virtual:
    get:
      summary: Get virtual activities
      tags: [Activities]
      security: []
      responses:
        200:
          description: Virtual activities retrieved

  /activities/price-range:
    get:
      summary: Get activities by price range
      tags: [Activities]
      security: []
      parameters:
        - name: min
          in: query
          schema:
            type: number
        - name: max
          in: query
          schema:
            type: number
      responses:
        200:
          description: Activities retrieved

  /activities/date-range:
    get:
      summary: Get activities by date range
      tags: [Activities]
      security: []
      parameters:
        - name: start
          in: query
          schema:
            type: string
            format: date
        - name: end
          in: query
          schema:
            type: string
            format: date
      responses:
        200:
          description: Activities retrieved

  /activities/{id}:
    get:
      summary: Get activity by ID
      tags: [Activities]
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Activity retrieved

    put:
      summary: Update activity
      tags: [Activities]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Activity'
      responses:
        200:
          description: Activity updated

    delete:
      summary: Delete activity
      tags: [Activities]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Activity deleted

  /activities/location/{location}:
    get:
      summary: Get activities by location
      tags: [Activities]
      security: []
      parameters:
        - name: location
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Activities retrieved

  /activities/tags:
    post:
      summary: Get activities by tags
      tags: [Activities]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tags:
                  type: array
                  items:
                    type: string
      responses:
        200:
          description: Activities retrieved

  /activities/{id}/participants:
    get:
      summary: Get activity participants
      tags: [Activities]
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Participants retrieved

  /activities/{id}/statistics:
    get:
      summary: Get activity statistics
      tags: [Activities]
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Statistics retrieved

  /activities/{id}/pricing:
    get:
      summary: Get activity pricing details
      tags: [Activities]
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Pricing retrieved

  /activities/{id}/join-with-payment:
    post:
      summary: Join activity with payment
      tags: [Activities]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                paymentMethodId:
                  type: string
      responses:
        200:
          description: Successfully joined activity

  /activities/{id}/confirm-participation:
    post:
      summary: Confirm activity participation
      tags: [Activities]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Participation confirmed

  /activities/{id}/cancel:
    post:
      summary: Cancel activity participation
      tags: [Activities]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Participation cancelled

  /activities/{id}/capacity:
    put:
      summary: Update activity capacity
      tags: [Activities]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                min:
                  type: integer
                max:
                  type: integer
      responses:
        200:
          description: Capacity updated

  /activities/{id}/view:
    post:
      summary: Increment activity view count
      tags: [Activities]
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: View count incremented

  /activities/{id}/interested:
    post:
      summary: Mark interest in activity
      tags: [Activities]
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Interest marked

  # Animal Spirit Endpoints
  /animals:
    get:
      summary: Get all animals
      tags: [Animals]
      security: []
      responses:
        200:
          description: Animals retrieved

    post:
      summary: Create new animal
      tags: [Animals]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Animal'
      responses:
        201:
          description: Animal created

  /animals/search:
    get:
      summary: Search animals
      tags: [Animals]
      security: []
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
      responses:
        200:
          description: Search results retrieved

  /animals/random:
    get:
      summary: Get random animals
      tags: [Animals]
      security: []
      parameters:
        - name: count
          in: query
          schema:
            type: integer
            default: 5
      responses:
        200:
          description: Random animals retrieved

  /animals/by-species/{species}:
    get:
      summary: Get animals by species
      tags: [Animals]
      security: []
      parameters:
        - name: species
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Animals retrieved

  /animals/by-habitat/{habitat}:
    get:
      summary: Get animals by habitat
      tags: [Animals]
      security: []
      parameters:
        - name: habitat
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Animals retrieved

  /animals/spirit-match:
    get:
      summary: Get user's spirit animal match
      tags: [Animals]
      responses:
        200:
          description: Spirit match retrieved

  /animals/evolution-images:
    get:
      summary: Get evolution stage images
      tags: [Animals]
      security: []
      responses:
        200:
          description: Evolution images retrieved

  /animals/statistics:
    get:
      summary: Get spirit animal statistics
      tags: [Animals]
      security: []
      responses:
        200:
          description: Statistics retrieved

  /animals/{id}:
    get:
      summary: Get animal by ID
      tags: [Animals]
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Animal retrieved

    put:
      summary: Update animal
      tags: [Animals]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Animal'
      responses:
        200:
          description: Animal updated

    delete:
      summary: Delete animal
      tags: [Animals]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Animal deleted

  /animals/{spiritId}/compatible:
    get:
      summary: Get compatible spirits
      tags: [Animals]
      security: []
      parameters:
        - name: spiritId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Compatible spirits retrieved

  # Question Endpoints
  /questions:
    get:
      summary: Get all questions
      tags: [Questions]
      security: []
      responses:
        200:
          description: Questions retrieved

    post:
      summary: Create new question
      tags: [Questions]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Question'
      responses:
        201:
          description: Question created

  /questions/category/{category}:
    get:
      summary: Get questions by category
      tags: [Questions]
      security: []
      parameters:
        - name: category
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Questions retrieved

  /questions/{id}:
    get:
      summary: Get question by ID
      tags: [Questions]
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Question retrieved

    put:
      summary: Update question
      tags: [Questions]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Question'
      responses:
        200:
          description: Question updated

    delete:
      summary: Delete question
      tags: [Questions]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Question deleted

  /questions/quiz/generate:
    get:
      summary: Generate quiz
      tags: [Questions]
      security: []
      parameters:
        - name: count
          in: query
          schema:
            type: integer
            default: 10
        - name: category
          in: query
          schema:
            type: string
      responses:
        200:
          description: Quiz generated

  /questions/statistics:
    get:
      summary: Get question statistics
      tags: [Questions]
      security: []
      responses:
        200:
          description: Statistics retrieved

  # Daily Message Endpoints
  /dailyMessages:
    get:
      summary: Get all daily messages
      tags: [Daily Messages]
      security: []
      responses:
        200:
          description: Messages retrieved

    post:
      summary: Create daily message
      tags: [Daily Messages]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DailyMessage'
      responses:
        201:
          description: Message created

  /dailyMessages/today:
    get:
      summary: Get today's message
      tags: [Daily Messages]
      responses:
        200:
          description: Today's message retrieved

  /dailyMessages/random:
    get:
      summary: Get random message
      tags: [Daily Messages]
      security: []
      responses:
        200:
          description: Random message retrieved

  /dailyMessages/user/viewed:
    get:
      summary: Get user's viewed messages
      tags: [Daily Messages]
      responses:
        200:
          description: Viewed messages retrieved

  /dailyMessages/analytics:
    get:
      summary: Get message analytics
      tags: [Daily Messages]
      responses:
        200:
          description: Analytics retrieved

  /dailyMessages/search:
    get:
      summary: Search messages
      tags: [Daily Messages]
      security: []
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
      responses:
        200:
          description: Search results retrieved

  /dailyMessages/trending:
    get:
      summary: Get trending messages
      tags: [Daily Messages]
      security: []
      responses:
        200:
          description: Trending messages retrieved

  /dailyMessages/statistics:
    get:
      summary: Get message statistics
      tags: [Daily Messages]
      security: []
      responses:
        200:
          description: Statistics retrieved

  /dailyMessages/mood/{mood}:
    get:
      summary: Get messages by mood
      tags: [Daily Messages]
      security: []
      parameters:
        - name: mood
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Messages retrieved

  /dailyMessages/tags:
    post:
      summary: Get messages by tags
      tags: [Daily Messages]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tags:
                  type: array
                  items:
                    type: string
      responses:
        200:
          description: Messages retrieved

  /dailyMessages/targeted:
    post:
      summary: Get targeted messages
      tags: [Daily Messages]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                criteria:
                  type: object
      responses:
        200:
          description: Targeted messages retrieved

  /dailyMessages/bulk:
    post:
      summary: Bulk create messages
      tags: [Daily Messages]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/DailyMessage'
      responses:
        201:
          description: Messages created

  /dailyMessages/archive-expired:
    post:
      summary: Archive expired messages
      tags: [Daily Messages]
      responses:
        200:
          description: Messages archived

  /dailyMessages/{id}:
    get:
      summary: Get message by ID
      tags: [Daily Messages]
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Message retrieved

    put:
      summary: Update message
      tags: [Daily Messages]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DailyMessage'
      responses:
        200:
          description: Message updated

  /dailyMessages/{id}/like:
    post:
      summary: Like message
      tags: [Daily Messages]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Message liked

  /dailyMessages/{id}/priority:
    put:
      summary: Update message priority
      tags: [Daily Messages]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                priority:
                  type: integer
      responses:
        200:
          description: Priority updated

  /dailyMessages/read:
    post:
      summary: Mark message as read
      tags: [Daily Messages]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                messageId:
                  type: string
      responses:
        200:
          description: Message marked as read

  # Assessment Endpoints
  /assessments:
    get:
      summary: Get available assessments
      tags: [Assessments]
      security: []
      responses:
        200:
          description: Assessments retrieved

    post:
      summary: Create assessment
      tags: [Assessments]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Assessment'
      responses:
        201:
          description: Assessment created

  /assessments/start:
    post:
      summary: Start assessment session
      tags: [Assessments]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                assessmentId:
                  type: string
                userId:
                  type: string
      responses:
        200:
          description: Session started

  /assessments/response:
    post:
      summary: Submit assessment response
      tags: [Assessments]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sessionId:
                  type: string
                questionId:
                  type: string
                answer:
                  type: string
      responses:
        200:
          description: Response submitted

  /assessments/{sessionId}/complete:
    put:
      summary: Complete assessment
      tags: [Assessments]
      security: []
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Assessment completed

  /assessments/{sessionId}/abandon:
    put:
      summary: Abandon assessment
      tags: [Assessments]
      security: []
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Assessment abandoned

  /assessments/history:
    get:
      summary: Get user assessment history
      tags: [Assessments]
      security: []
      parameters:
        - name: userId
          in: query
          required: true
          schema:
            type: string
      responses:
        200:
          description: History retrieved

  /assessments/profile/latest:
    get:
      summary: Get latest personality profile
      tags: [Assessments]
      security: []
      parameters:
        - name: userId
          in: query
          required: true
          schema:
            type: string
      responses:
        200:
          description: Profile retrieved

  /assessments/analytics/completion:
    get:
      summary: Get completion analytics
      tags: [Assessments]
      security: []
      responses:
        200:
          description: Analytics retrieved

  # Product & Payment Endpoints
  /products:
    get:
      summary: Get all products
      tags: [Products]
      security: []
      responses:
        200:
          description: Products retrieved

    post:
      summary: Create product
      tags: [Products]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
      responses:
        201:
          description: Product created

  /products/{id}:
    get:
      summary: Get product by ID
      tags: [Products]
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Product retrieved

  /products/{productId}/prices:
    get:
      summary: Get product prices
      tags: [Products]
      security: []
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Prices retrieved

  /products/type/{type}:
    get:
      summary: Get products by type
      tags: [Products]
      security: []
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Products retrieved

  /products/category/{category}:
    get:
      summary: Get products by category
      tags: [Products]
      security: []
      parameters:
        - name: category
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Products retrieved

  /products/{productId}/pricing-tiers:
    get:
      summary: Get product pricing tiers
      tags: [Products]
      security: []
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Pricing tiers retrieved

  /products/{productId}/cheapest-price:
    get:
      summary: Get cheapest price for product
      tags: [Products]
      security: []
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Cheapest price retrieved

  /products/payment-intent:
    post:
      summary: Create payment intent
      tags: [Products]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                productId:
                  type: string
                amount:
                priceId:
                  type: string
      responses:
        200:
          description: Payment intent created

  /products/{productId}/purchase:
    post:
      summary: Purchase product
      tags: [Products]
      security: []
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                paymentMethodId:
                  type: string
      responses:
        200:
          description: Purchase completed

  /products/user/transactions:
    get:
      summary: Get user transactions
      tags: [Products]
      security: []
      responses:
        200:
          description: Transactions retrieved

  /products/user/payment-methods:
    get:
      summary: Get user payment methods
      tags: [Products]
      security: []
      responses:
        200:
          description: Payment methods retrieved

    post:
      summary: Add payment method
      tags: [Products]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                stripePaymentMethodId:
                  type: string
                type:
                  type: string
      responses:
        200:
          description: Payment method added

  /products/user/spending-stats:
    get:
      summary: Get user spending statistics
      tags: [Products]
      security: []
      responses:
        200:
          description: Statistics retrieved

  /products/user/payment-methods/{paymentMethodId}/default:
    put:
      summary: Set default payment method
      tags: [Products]
      security: []
      parameters:
        - name: paymentMethodId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Default method set

  /products/user/payment-methods/{paymentMethodId}:
    delete:
      summary: Delete payment method
      tags: [Products]
      security: []
      parameters:
        - name: paymentMethodId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Payment method deleted

  /products/prices:
    post:
      summary: Create price
      tags: [Products]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                productId:
                  type: string
                amount:
                  type: number
                currency:
                  type: string
      responses:
        201:
          description: Price created

  /products/analytics/payments:
    get:
      summary: Get payment analytics
      tags: [Products]
      security: []
      responses:
        200:
          description: Analytics retrieved

  /products/analytics/performance/{productId}:
    get:
      summary: Get product performance analytics
      tags: [Products]
      security: []
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Performance data retrieved

  /products/analytics/revenue:
    get:
      summary: Get revenue analytics
      tags: [Products]
      security: []
      responses:
        200:
          description: Revenue data retrieved

  /products/webhook/stripe:
    post:
      summary: Stripe webhook handler
      tags: [Products]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        200:
          description: Webhook processed

  # Admin Endpoints
  /admin/users:
    get:
      summary: Get all users (admin)
      tags: [Admin]
      parameters:
        - name: page
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
        - name: role
          in: query
          schema:
            type: string
      responses:
        200:
          description: Users retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'

  /admin/users/{userId}/role:
    get:
      summary: Get user role
      tags: [Admin]
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Role retrieved

  /admin/users/permission-check:
    post:
      summary: Check user permission
      tags: [Admin]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                resource:
                  type: string
                action:
                  type: string
                requireSuperAdmin:
                  type: boolean
      responses:
        200:
          description: Permission checked

  /admin/users/role:
    put:
      summary: Update user role
      tags: [Admin]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - userId
                - roleId
              properties:
                userId:
                  type: string
                roleId:
                  type: string
      responses:
        200:
          description: Role updated

  /admin/users/{userId}/deactivate:
    put:
      summary: Deactivate admin user
      tags: [Admin]
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: User deactivated

  /admin/users/{userId}/is-admin:
    get:
      summary: Check if user is admin
      tags: [Admin]
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Admin status checked

  /admin/users/{userId}/is-super-admin:
    get:
      summary: Check if user is super admin
      tags: [Admin]
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Super admin status checked

  /admin/users/admin:
    post:
      summary: Create admin user
      tags: [Admin]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                name:
                  type: string
                roleId:
                  type: string
      responses:
        201:
          description: Admin user created

  /admin/roles:
    get:
      summary: Get all roles
      tags: [Admin]
      responses:
        200:
          description: Roles retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      roles:
                        type: array
                        items:
                          $ref: '#/components/schemas/Role'

    post:
      summary: Create role
      tags: [Admin]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - slug
              properties:
                name:
                  type: string
                slug:
                  type: string
                description:
                  type: string
                permissions:
                  type: array
                  items:
                    type: string
                level:
                  type: integer
                  minimum: 1
                  maximum: 10
      responses:
        201:
          description: Role created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      role:
                        $ref: '#/components/schemas/Role'

  /admin/permissions:
    get:
      summary: Get all permissions
      tags: [Admin]
      responses:
        200:
          description: Permissions retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      permissions:
                        type: array
                        items:
                          $ref: '#/components/schemas/Permission'

    post:
      summary: Create permission
      tags: [Admin]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - resource
                - actions
              properties:
                name:
                  type: string
                description:
                  type: string
                resource:
                  type: string
                  enum: [users, activities, animals, questions, messages, analytics, payments, settings]
                actions:
                  type: array
                  items:
                    type: string
                    enum: [create, read, update, delete, manage]
      responses:
        201:
          description: Permission created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      permission:
                        $ref: '#/components/schemas/Permission'

tags:
  - name: Authentication
    description: Authentication endpoints
  - name: Users
    description: User management endpoints
  - name: Activities
    description: Activity management endpoints
  - name: Animals
    description: Animal spirit endpoints
  - name: Questions
    description: Question management endpoints
  - name: Daily Messages
    description: Daily message endpoints
  - name: Assessments
    description: Assessment endpoints
  - name: Products
    description: Product and payment endpoints
  - name: Admin
    description: Admin management endpoints