openapi: 3.0.3
info:
  title: MyInpulse Backend API
  description: 'This serves as an OpenAPI documentation for the MyInpulse backend service, covering operations for Entrepreneurs, Admins, and shared functionalities.'
  version: 0.2.1
tags:
  - name: Entrepreneurs API
    description: API endpoints primarily for Entrepreneur users.
  - name: Admin API
    description: API endpoints restricted to Admin users for management tasks.
  - name: Shared API
    description: API endpoints accessible by both Entrepreneurs and Admins.
  - name: Unauth API
    description: API endpoints related to user account management.
components:
  schemas:
    user:
      type: object
      properties:
        idUser:
          type: integer
          description: Unique identifier for the user.
          example: 101
        userSurname:
          type: string
          description: User's surname (last name).
          example: Doe
        userName:
          type: string
          description: User's given name (first name).
          example: John
        primaryMail:
          type: string
          format: email
          description: User's primary email address.
          example: john.doe@example.com
        secondaryMail:
          type: string
          format: email
          description: User's secondary email address (optional).
          example: j.doe@personal.com
        phoneNumber:
          type: string
          description: User's phone number.
          example: '+33612345678'
    user-entrepreneur:
      allOf:
        - $ref: '#/components/schemas/user'
        - type: object
          properties:
            school:
              type: string
              description: The school the entrepreneur attends/attended.
              example: ENSEIRB-MATMECA
            course:
              type: string
              description: The specific course or program of study.
              example: Electronics
            sneeStatus:
              type: boolean
              description: Indicates if the user has SNEE status (Statut National d'Étudiant-Entrepreneur).
              example: true
      example:
        idUser: 101
        userSurname: Doe
        userName: John
        primaryMail: john.doe@example.com
        secondaryMail: j.doe@personal.com
        phoneNumber: '+33612345678'
        school: ENSEIRB-MATMECA
        course: Electronics
        sneeStatus: true
    user-admin:
      allOf:
        - $ref: '#/components/schemas/user'
      example:
        idUser: 55
        userSurname: Admin
        userName: Super
        primaryMail: admin@myinpulse.com
        phoneNumber: '+33512345678'
    sectionCell:
      type: object
      description: Represents a cell (like a sticky note) within a specific section of a project's Lean Canvas.
      properties:
        idSectionCell:
          type: integer
          description: Unique identifier for the section cell.
          example: 508
        sectionId:
          type: integer
          description: 'Identifier of the Lean Canvas section this cell belongs to (e.g., 1 for Problem, 2 for Solution).'
          example: 1
        contentSectionCell:
          type: string
          description: The text content of the section cell.
          example: Users find it hard to track project progress.
        modificationDate:
          type: string
          format: date
          description: The date when this cell was last modified.
          example: '2025-04-15'
    project:
      type: object
      description: Represents a project being managed or developed.
      properties:
        idProject:
          type: integer
          description: Unique identifier for the project.
          example: 12
        projectName:
          type: string
          description: The name of the project.
          example: MyInpulse Mobile App
        creationDate:
          type: string
          format: date
          description: The date when the project was created in the system.
          example: '2024-11-20'
        logo:
          type: string
          format: byte
          description: Base64 encoded string representing the project logo image.
          example: /*Base64 encoded string representing the project logo image*/
        status:
          type: string
          enum:
            - PENDING
            - ACTIVE
            - ENDED
            - ABORTED
            - REJECTED
          description: 'Corresponds to a status enum internal to the backend, it''s value in in requests incoming to the server should be ignored as the client shouldn''t be specifying them.'
          example: NaN
    report:
      type: object
      description: Represents a report associated with an appointment.
      properties:
        idReport:
          type: integer
          description: Unique identifier for the report.
          example: 987
        reportContent:
          type: string
          description: The textual content of the report. Could be plain text or Markdown (specify if known).
          example: Discussed roadmap milestones for Q3. Agreed on preliminary UI mockups.
    appointment:
      type: object
      description: Represents a scheduled meeting or appointment.
      properties:
        idAppointment:
          type: integer
          description: Unique identifier for the appointment.
          example: 303
        appointmentDate:
          type: string
          format: date
          description: The date of the appointment.
          example: '2025-05-10'
        appointmentTime:
          type: string
          format: time
          description: The time of the appointment (local time).
          example: '14:30:00'
        appointmentDuration:
          type: string
          description: 'Duration of the appointment in ISO 8601 duration format (e.g., PT1H30M for 1 hour 30 minutes).'
          example: PT1H
        appointmentPlace:
          type: string
          description: Location or meeting link for the appointment.
          example: 'Meeting Room 3 / https://meet.example.com/abc-def-ghi'
        appointmentSubject:
          type: string
          description: The main topic or subject of the appointment.
          example: Q3 Roadmap Planning
    joinRequest:
      type: object
      description: Represents a request from an entrepreneur to join an existing project.
      properties:
        projectId:
          type: integer
          description: The ID of the project the entrepreneur wants to join.
          example: 12
    projectDecision:
      type: object
      description: Represents a decision from an admin to accept a pending project.
      properties:
        projectId:
          type: integer
          description: The ID of the project the entrepreneur wants to join.
          example: 12
        adminId:
          type: integer
          description: The ID of the project the admin who will supervise the project in case of admission.
          example: 2
        isAccepted:
          type: boolean
          description: The boolean value of the decision.
          example: 'true'
  securitySchemes:
    MyINPulse:
      type: oauth2
      description: OAuth2 authentication using Keycloak.
      flows:
        implicit:
          authorizationUrl: '{keycloakBaseUrl}/realms/{keycloakRealm}/protocol/openid-connect/auth'
          scopes:
            MyINPulse-admin: Grants administrator access.
            MyINPulse-entrepreneur: Grants standard entrepreneur user access.
servers:
  - url: '{serverProtocol}://{serverHost}:{serverPort}'
    description: API Server Environment
    variables:
      serverProtocol:
        enum:
          - http
          - https
        default: http
      serverHost:
        default: localhost
      serverPort:
        enum:
          - '8081'
        default: '8081'
      keycloakBaseUrl:
        default: 'http://localhost:7080'
        description: Base URL for the Keycloak server.
      keycloakRealm:
        default: MyInpulseRealm
        description: Keycloak realm name.
paths:
  /unauth/finalize:
    post:
      summary: Finalize account setup using authentication token
      description: |-
        Completes the user account creation/setup process in the MyInpulse system.
        This endpoint requires the user to be authenticated via Keycloak (e.g., after initial login).
        User details (name, email, etc.) are extracted from the authenticated user's token (e.g., Keycloak JWT).
        No request body is needed. The account is marked as pending admin validation upon successful finalization.
      tags:
        - Unauth API
      responses:
        '201':
          description: Created - Account finalized and pending admin validation. Returns the user profile.
        '400':
          description: Bad Request - Problem processing the token or user data derived from it.
        '401':
          description: Unauthorized - Valid authentication token required.
  '/unauth/request-join/{projectId}':
    post:
      summary: Request to join an existing project
      description: Submits a request for the authenticated user (keycloack authenticated) to join the project specified by projectId. Their role is then changed to entrepreneur in server and Keycloak. This requires approval from a project admin.
      tags:
        - Unauth API
      parameters:
        - in: path
          name: projectId
          required: true
          schema:
            type: integer
          description: The ID of the project to request joining.
          example: 15
      responses:
        '202':
          description: Accepted - Join request submitted and pending approval.
        '400':
          description: Bad Request - Invalid project ID format or already member/request pending.
        '401':
          description: Unauthorized.
  /admin/pending-accounts:
    get:
      operationId: getPendingAccounts
      summary: Get accounts awaiting validation
      description: Retrieves a list of entrepreneur user accounts that are pending admin validation.
      tags:
        - Admin API
      security:
        - MyINPulse:
            - MyINPulse-admin
      responses:
        '200':
          description: OK - List of pending accounts returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/user-entrepreneur'
        '401':
          description: Unauthorized.
  '/admin/accounts/validate/{userId}':
    post:
      operationId: validateUserAccount
      summary: Validate a pending user account
      description: Marks the user account specified by userId as validated/active.
      tags:
        - Admin API
      security:
        - MyINPulse:
            - MyINPulse-admin
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: integer
          description: The ID of the user account to validate.
          example: 102
      responses:
        '204':
          description: No Content - Account validated successfully.
        '400':
          description: Bad Request - Invalid user ID format.
        '401':
          description: Unauthorized.
  /admin/projects:
    get:
      operationId: getAdminProjects
      summary: Get projects associated with the admin
      tags:
        - Admin API
      security:
        - MyINPulse:
            - MyINPulse-admin
      description: 'Retrieves a list of projects managed by the requesting admin, including key details for overview.'
      responses:
        '200':
          description: OK - List of projects returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/project'
        '400':
          description: 'Bad Request - Invalid project data provided (e.g., missing required fields).'
        '401':
          description: Unauthorized - Authentication required or invalid token.
    post:
      operationId: addProjectManually
      summary: Manually add a new project
      description: Creates a new project with the provided details.
      tags:
        - Admin API
      security:
        - MyINPulse:
            - MyINPulse-admin
      requestBody:
        required: true
        description: Project details to create. `idProject` and `creationDate` will be ignored if sent and set by the server.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/project'
      responses:
        '201':
          description: Created - Project added successfully. Returns the created project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/project'
        '400':
          description: 'Bad Request - Invalid project data provided (e.g., missing required fields).'
        '401':
          description: Unauthorized.
  /admin/projects/pending:
    get:
      operationId: getPendingProjects
      summary: Get projects awaiting validation
      tags:
        - Admin API
      security:
        - MyINPulse:
            - MyINPulse-admin
      description: Retrieves a list of projects submitted by entrepreneurs that are pending admin approval.
      responses:
        '200':
          description: OK - List of pending projects returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/project'
        '401':
          description: Unauthorized.
  '/admin/projects/pending/decision/{pendingProjectId}':
    post:
      operationId: decidePendingProject
      summary: Approve or reject a pending project
      tags:
        - Admin API
      description: |-
        Allows an admin to make a decision on a project awaiting validation.
        If approved (decision=true), the project status changes, and it's linked to the involved users.
        If rejected (decision=false), the pending project data might be archived or deleted based on business logic.
      security:
        - MyINPulse:
            - MyINPulse-admin
      parameters:
        - in: path
          name: pendingProjectId
          required: true
          schema:
            type: integer
          description: The ID of the pending project to decide upon.
          example: 7
      requestBody:
        required: true
        description: Decision payload.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/projectDecision'
      responses:
        '204':
          description: No Content - Decision processed successfully.
        '400':
          description: 'Bad Request - Invalid input (e.g., missing decision).'
        '401':
          description: Unauthorized.
  '/admin/appointments/report/{appointmentId}':
    post:
      operationId: createAppointmentReport
      summary: Create a report for an appointment
      description: 'Creates and links a new report (e.g., meeting minutes) to the specified appointment using the provided content.'
      tags:
        - Admin API
      security:
        - MyINPulse:
            - MyINPulse-admin
      parameters:
        - in: path
          name: appointmentId
          required: true
          schema:
            type: integer
          description: ID of the appointment to add a report to.
          example: 303
      requestBody:
        required: true
        description: Report content. `idReport` will be ignored if sent.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/report'
      responses:
        '201':
          description: Created - Report created and linked successfully. Returns the created report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/report'
        '400':
          description: 'Bad Request - Invalid input (e.g., missing content, invalid appointment ID format).'
        '401':
          description: Unauthorized.
    put:
      operationId: updateAppointmentReport
      summary: Update an existing appointment report
      description: Updates the content of an existing report linked to the specified appointment. Replaces the entire report content.
      tags:
        - Admin API
      security:
        - MyINPulse:
            - MyINPulse-admin
      parameters:
        - in: path
          name: appointmentId
          required: true
          schema:
            type: integer
          description: ID of the appointment whose report needs updating.
          example: 303
      requestBody:
        required: true
        description: New report content. `idReport` in the body should match the existing report's ID or will be ignored.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/report'
      responses:
        '200':
          description: OK - Report updated successfully. Returns the updated report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/report'
        '400':
          description: 'Bad Request - Invalid input (e.g., missing content).'
        '401':
          description: Unauthorized.
  '/admin/projects/{projectId}':
    delete:
      operationId: removeProject
      summary: Remove a project
      description: Permanently removes the project specified by projectId and potentially related data (use with caution).
      tags:
        - Admin API
      security:
        - MyINPulse:
            - MyINPulse-admin
      parameters:
        - in: path
          name: projectId
          required: true
          schema:
            type: integer
          description: The ID of the project to remove.
          example: 12
      responses:
        '204':
          description: No Content - Project removed successfully.
        '400':
          description: Bad Request - Invalid project ID format.
        '401':
          description: Unauthorized.
  '/admin/make-admin/{userId}':
    post:
      operationId: grantAdminRights
      summary: Grant admin rights to a user
      tags:
        - Admin API
      security:
        - MyINPulse:
            - MyINPulse-admin
      description: Elevates the specified user to also have administrator privileges. Assumes the user already exists.
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: integer
          description: The ID of the user to grant admin rights.
          example: 103
      responses:
        '204':
          description: No Content - Admin rights granted successfully.
        '400':
          description: Bad Request - Invalid user ID format or user is already an admin.
        '401':
          description: Unauthorized.
  /shared/appointments/upcoming:
    get:
      operationId: getUpcomingAppointments
      summary: Get upcoming appointments for the user
      tags:
        - Shared API
      security:
        - MyINPulse:
            - MyINPulse-entrepreneur
            - MyINPulse-admin
      description: Retrieves a list of appointments scheduled for the authenticated user (either entrepreneur or admin) in the future.
      responses:
        '200':
          description: OK - List of upcoming appointments.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/appointment'
        '401':
          description: Unauthorized.
  '/shared/projects/sectionCells/{projectId}/{sectionId}/{date}':
    get:
      operationId: getSectionCellsByDate
      summary: Get project section cells modified on a specific date
      tags:
        - Shared API
      security:
        - MyINPulse:
            - MyINPulse-entrepreneur
            - MyINPulse-admin
      description: 'Retrieves section cells belonging to a specific section of a project, filtered by the last modification date. Requires user to have access to the project.'
      parameters:
        - in: path
          name: projectId
          required: true
          schema:
            type: integer
          description: ID of the project.
        - in: path
          name: sectionId
          required: true
          schema:
            type: integer
          description: ID of the Lean Canvas section.
        - in: path
          name: date
          required: true
          schema:
            type: string
            format: date
          description: The modification date to filter by (YYYY-MM-DD).
      responses:
        '200':
          description: OK - List of section cells matching the criteria.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/sectionCell'
        '400':
          description: Bad Request - Invalid parameter format.
        '401':
          description: Unauthorized.
  '/shared/projects/entrepreneurs/{projectId}':
    get:
      operationId: getProjectEntrepreneurs
      summary: Get entrepreneurs associated with a project
      tags:
        - Shared API
      security:
        - MyINPulse:
            - MyINPulse-entrepreneur
            - MyINPulse-admin
      description: Retrieves a list of entrepreneur users associated with the specified project. Requires access to the project.
      parameters:
        - in: path
          name: projectId
          required: true
          schema:
            type: integer
          description: ID of the project.
      responses:
        '200':
          description: OK - List of entrepreneurs.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/user-entrepreneur'
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden - User does not have access to this project.
        '404':
          description: Not Found - Project not found.
  '/shared/projects/admin/{projectId}':
    get:
      operationId: getProjectAdmins
      summary: Get admins associated with a project
      tags:
        - Shared API
      security:
        - MyINPulse:
            - MyINPulse-entrepreneur
            - MyINPulse-admin
      description: Retrieves a list of admin users associated with the specified project. Requires access to the project.
      parameters:
        - in: path
          name: projectId
          required: true
          schema:
            type: integer
          description: ID of the project.
      responses:
        '200':
          description: OK - List of admins.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user-admin'
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden - User does not have access to this project.
        '404':
          description: Not Found - Project not found.
  '/shared/projects/appointments/{projectId}':
    get:
      operationId: getProjectAppointments
      summary: Get appointments related to a project
      tags:
        - Shared API
      security:
        - MyINPulse:
            - MyINPulse-entrepreneur
            - MyINPulse-admin
      description: Retrieves a list of appointments associated with the specified project. Requires access to the project.
      parameters:
        - in: path
          name: projectId
          required: true
          schema:
            type: integer
          description: ID of the project.
      responses:
        '200':
          description: OK - List of appointments.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/appointment'
        '401':
          description: Unauthorized.
  '/shared/appointments/report/{appointmentId}':
    get:
      operationId: getAppointmentReport
      summary: Get the report for an appointment
      tags:
        - Shared API
      security:
        - MyINPulse:
            - MyINPulse-entrepreneur
            - MyINPulse-admin
      description: Retrieves the report associated with a specific appointment. Requires user to have access to the appointment/project.
      parameters:
        - in: path
          name: appointmentId
          required: true
          schema:
            type: integer
          description: ID of the appointment.
      responses:
        '200':
          description: OK - Report content returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/report'
        '401':
          description: Unauthorized.
  /shared/appointments/request:
    post:
      operationId: requestAppointment
      summary: Request a new appointment
      tags:
        - Shared API
      security:
        - MyINPulse:
            - MyINPulse-entrepreneur
            - MyINPulse-admin
      description: 'Allows a user (entrepreneur or admin) to request a new appointment, potentially with another user or regarding a project. Details in the body. The request might need confirmation or create a pending appointment.'
      requestBody:
        required: true
        description: Details of the appointment request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/appointment'
            example:
              value:
                appointmentDate: '2025-06-01'
                appointmentTime: '10:00:00'
                appointmentDuration: PT1H
                appointmentPlace: Online
                appointmentSubject: Follow-up on prototype
      responses:
        '202':
          description: Accepted - Appointment request submitted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/appointment'
        '400':
          description: Bad Request - Invalid appointment details.
        '401':
          description: Unauthorized.
  /entrepreneur/projects/request:
    post:
      operationId: requestProjectCreation
      summary: Request creation and validation of a new project
      tags:
        - Entrepreneurs API
      description: |-
        Submits a request for a new project. The project details are provided in the request body.
        The requesting entrepreneur (identified by the token) will be associated to it.
        The project is created with a 'pending' status, awaiting admin approval.
      security:
        - MyINPulse:
            - MyINPulse-entrepreneur
      requestBody:
        required: true
        description: 'Project details for the request. `status`, `creationDate` are required by the model when being sent but is ignored by the server; primarily expects a valid `projectId`, `name`, `logo`.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/project'
      responses:
        '202':
          description: Accepted - Project creation request received and is pending validation.
        '400':
          description: 'Bad Request - Invalid input (e.g., missing name).'
        '401':
          description: Unauthorized.
  /entrepreneur/sectionCells:
    post:
      operationId: addSectionCell
      summary: Add a cell to a Lean Canvas section
      description: Adds a new cell (like a sticky note) with the provided content to a specific section of the entrepreneur's project's Lean Canvas. Assumes project context is known based on user's token. `idSectionCell` and `modificationDate` are server-generated so they're values in the request are ignored by the server.
      tags:
        - Entrepreneurs API
      security:
        - MyINPulse:
            - MyINPulse-entrepreneur
      requestBody:
        required: true
        description: Section cell details. `idSectionCell` and `modificationDate` will be ignored if sent.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/sectionCell'
      responses:
        '201':
          description: Created - Section cell added successfully. Returns the created cell.
        '400':
          description: 'Bad Request - Invalid input (e.g., missing content or sectionId).'
        '401':
          description: Unauthorized.
  '/entrepreneur/sectionCells/{sectionCellId}':
    put:
      operationId: modifySectionCell
      summary: Modify data in a Lean Canvas section cell
      description: Updates the content of an existing Lean Canvas section cell specified by `sectionCellId`. The server updates the `modificationDate`.
      tags:
        - Entrepreneurs API
      security:
        - MyINPulse:
            - MyINPulse-entrepreneur
      parameters:
        - in: path
          name: sectionCellId
          required: true
          schema:
            type: integer
          description: The ID of the section cell to modify.
          example: 508
      requestBody:
        required: true
        description: Updated section cell details. `idSectionCell` should match the path parameter. `modificationDate` will be updated by the server.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/sectionCell'
      responses:
        '200':
          description: OK - Section cell updated successfully. Returns the updated cell.
        '400':
          description: Bad Request - Invalid input or ID mismatch.
        '401':
          description: Unauthorized.
    delete:
      operationId: removeSectionCell
      summary: Remove a Lean Canvas section cell
      description: Deletes the Lean Canvas section cell specified by `sectionCellId`.
      tags:
        - Entrepreneurs API
      security:
        - MyINPulse:
            - MyINPulse-entrepreneur
      parameters:
        - in: path
          name: sectionCellId
          required: true
          schema:
            type: integer
          description: The ID of the section cell to remove.
          example: 509
      responses:
        '204':
          description: No Content - Section cell removed successfully.
        '400':
          description: Bad Request - Invalid ID format.
        '401':
          description: Unauthorized.