openapi: 3.0.1
info:
  title: React BFF Gateway API
  description: |
    Frontend-oriented API contract for the React dashboard. The BFF owns JWT validation,
    downstream aggregation, service response adaptation, and resilience fallbacks so the browser
    can consume one stable dashboard payload.
  contact:
    name: react-bff-gateway maintainers
  license:
    name: MIT
  version: 0.1.0
servers:
- url: http://localhost:8080
  description: Generated server url
tags:
- name: Dashboard
  description: Authenticated dashboard aggregation endpoints for the React application.
- name: Dashboard
  description: Frontend-oriented dashboard aggregation API.
paths:
  /api/dashboard:
    get:
      tags:
      - Dashboard
      summary: Get dashboard data
      description: |
        Returns the stable dashboard model consumed by the React app. The BFF derives the user id from the
        authenticated JWT, calls the downstream user and product services through WebClient, and shields the
        frontend from downstream response shapes. If the user service fails, a safe placeholder profile is
        returned. If the product service fails, recommendations are returned as an empty list.
      operationId: dashboard
      responses:
        "200":
          description: Dashboard data assembled for the authenticated user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DashboardResponse"
              examples:
                dashboard:
                  summary: Dashboard response
                  description: dashboard
                  value:
                    user:
                      id: user-123
                      displayName: Demo User
                      email: demo@example.com
                    recommendedProducts:
                    - id: prd-001
                      name: Premium Account
                      price: 9.99
        "401":
          description: "Bearer JWT is missing, expired, malformed, or fails validation."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                unauthorized:
                  summary: Missing token
                  description: unauthorized
                  value:
                    timestamp: 2026-05-23T11:24:56.339Z
                    status: 401
                    error: Unauthorized
                    message: Authentication is required
                    path: /api/dashboard
        "403":
          description: The authenticated principal is not allowed to access the resource.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                forbidden:
                  summary: Access denied
                  description: forbidden
                  value:
                    timestamp: 2026-05-23T11:24:56.339Z
                    status: 403
                    error: Forbidden
                    message: Access is denied
                    path: /api/dashboard
        "502":
          description: A downstream failure escaped the configured resilience fallback
            boundary.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
              examples:
                downstream-failure:
                  summary: Downstream abstraction
                  description: downstream-failure
                  value:
                    timestamp: 2026-05-23T11:24:56.339Z
                    status: 502
                    error: Bad Gateway
                    message: A downstream service could not complete the request
                    path: /api/dashboard
      security:
      - bearerAuth: []
components:
  schemas:
    DashboardResponse:
      type: object
      properties:
        user:
          $ref: "#/components/schemas/UserProfile"
        recommendedProducts:
          type: array
          description: Recommended products to render on the dashboard.
          items:
            $ref: "#/components/schemas/ProductRecommendation"
      description: Stable dashboard payload assembled for the React application.
    ProductRecommendation:
      type: object
      properties:
        id:
          type: string
          description: Stable product identifier.
          example: prd-001
        name:
          type: string
          description: Display name for the product recommendation.
          example: Premium Account
        price:
          type: number
          description: Current display price.
          example: 9.99
      description: Product recommendation card data exposed to the React dashboard.
    UserProfile:
      type: object
      properties:
        id:
          type: string
          description: Stable user identifier.
          example: user-123
        displayName:
          type: string
          description: Display-ready user name.
          example: Demo User
        email:
          type: string
          description: Email address shown in account UI.
          example: demo@example.com
      description: User identity fields exposed to the React dashboard.
    ApiError:
      type: object
      properties:
        timestamp:
          type: string
          description: Time the error response was produced.
          format: date-time
          example: 2026-05-23T11:24:56.339Z
        status:
          type: integer
          description: HTTP status code.
          format: int32
          example: 401
        error:
          type: string
          description: HTTP status reason phrase.
          example: Unauthorized
        message:
          type: string
          description: "Stable, human-readable summary."
          example: Authentication is required
        path:
          type: string
          description: Request path that failed.
          example: /api/dashboard
      description: Structured JSON error returned by the BFF for predictable client
        handling.
  securitySchemes:
    bearerAuth:
      type: http
      description: JWT Bearer token supplied in the Authorization header.
      scheme: bearer
      bearerFormat: JWT