openapi: 3.0.0
info:
  title: Anonymous Desire Aggregator API
  version: 2.0.0
  description: API for facilitating real-time, private, anonymous decision-making sessions.

paths:
  /sessions:
    post:
      summary: Get a new unique session ID
      operationId: createSession
      responses:
        '201':
          description: Session ID created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessionId:
                    type: string
                    format: uuid
                    description: The unique ID for the session. Clients will use this to join the WebSocket channel.

  /sessions/{sessionId}/analyze:
    post:
      summary: Trigger the semantic analysis for a session
      operationId: triggerAnalysis
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                allDesires:
                  type: array
                  description: A complete list of all desire sets from all participants, collected by the client.
                  items:
                    type: object
                    properties:
                      wants:
                        type: array
                        items:
                          type: string
                      accepts:
                        type: array
                        items:
                          type: string
                      noGoes:
                        type: array
                        items:
                          type: string
      responses:
        '202':
          description: Analysis has been successfully triggered. Results will be broadcast over the WebSocket.
        '404':
          description: Session not found.

# WebSocket Protocol (/sessions/{sessionId})
# The primary communication for this application is via WebSockets. The backend acts as a message relay and orchestrator.
#
# Client-to-Server Messages:
#
# - type: 'SHARE_STATE'
#   payload: { session: Session } # Client sends its entire session object to sync with others.
#
# - type: 'SUBMIT_DESIRES'
#   payload: { desireSet: DesireSet } # A single user submits their desires.
#
# Server-to-Client Messages:
#
# - type: 'USER_JOINED'
#   payload: { participantId: string }
#
# - type: 'STATE_UPDATE'
#   payload: { session: Session } # Broadcasts the latest session state to all clients.
#
# - type: 'ANALYSIS_COMPLETE'
#   payload: { decision: Decision } # Broadcasts the final results.
#
# - type: 'SESSION_LOCKED'
#   payload: {}