openapi: 3.1.0
info:
  # Do not change the title, if the title changes, the import paths will be broken
  title: Api
  version: 0.1.0
  description: API specification
servers:
  - url: /api
    description: Base API path
tags:
  - name: health
    description: Health operations
  - name: ideas
    description: Civic idea submission and management
  - name: synthesis
    description: AI synthesis of the people's voice
paths:
  /healthz:
    get:
      operationId: healthCheck
      tags: [health]
      summary: Health check
      description: Returns server health status
      responses:
        "200":
          description: Healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthStatus"

  /ideas:
    post:
      operationId: submitIdea
      tags: [ideas]
      summary: Submit a political idea
      description: Submit a civic idea to be filtered and included in the synthesis
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SubmitIdeaBody"
      responses:
        "201":
          description: Idea submitted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdeaResult"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    get:
      operationId: listIdeas
      tags: [ideas]
      summary: List all accepted ideas
      description: Returns all ideas that passed the democratic filter
      responses:
        "200":
          description: List of accepted ideas
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Idea"

  /ideas/stats:
    get:
      operationId: getIdeaStats
      tags: [ideas]
      summary: Get idea statistics
      description: Returns counts of total, accepted and rejected ideas
      responses:
        "200":
          description: Stats
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdeaStats"

  /synthesis:
    get:
      operationId: getSynthesis
      tags: [synthesis]
      summary: Get current synthesis
      description: Returns the latest synthesized text of the people's voice
      responses:
        "200":
          description: Current synthesis
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Synthesis"

components:
  schemas:
    HealthStatus:
      type: object
      properties:
        status:
          type: string
      required:
        - status

    SubmitIdeaBody:
      type: object
      properties:
        content:
          type: string
          minLength: 10
          maxLength: 1000
          description: The political idea text
        author:
          type: string
          maxLength: 100
          description: Optional pseudonym
      required:
        - content

    IdeaResult:
      type: object
      properties:
        id:
          type: integer
        accepted:
          type: boolean
        reason:
          type: string
          description: Reason if rejected
        idea:
          $ref: "#/components/schemas/Idea"
      required:
        - id
        - accepted

    Idea:
      type: object
      properties:
        id:
          type: integer
        content:
          type: string
        author:
          type: string
          nullable: true
        accepted:
          type: boolean
        rejectionReason:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - content
        - accepted
        - createdAt

    IdeaStats:
      type: object
      properties:
        total:
          type: integer
        accepted:
          type: integer
        rejected:
          type: integer
      required:
        - total
        - accepted
        - rejected

    Synthesis:
      type: object
      properties:
        text:
          type: string
          description: The synthesized voice of the people
        ideaCount:
          type: integer
          description: Number of ideas included in the synthesis
        updatedAt:
          type: string
          format: date-time
          nullable: true
      required:
        - text
        - ideaCount

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
      required:
        - error
        - message