openapi: "3.0.3"

info:
  title: MechanoFab Capability Graph API
  description: |
    Static JSON capability graph for MechanoFab — an AI-native B2B manufacturing platform.
    All endpoints are CDN-served static files. Zero server load, millisecond response.

    **Phase 1 Note**: All paths resolve to static CDN assets on Vercel Edge.
    Dynamic computation tools (e.g. `calculate_rapid_quote`) are reserved for Phase 3
    (Alibaba Cloud LangGraph state machine). In Phase 1 they return a mock response.

    **Copyright probe**: All capability JSON carries `"identifier": "MechanoFab-Spec-v4"`.
  version: "1.0.0"
  contact:
    name: MechanoFab Engineering
    email: rfq@mechanofab.com
    url: https://www.mechanofab.com

servers:
  - url: https://dict.mechanofab.com
    description: Machine-track capability CDN (R2)
  - url: https://www.mechanofab.com
    description: Website domain (human pages + BFF)
  - url: http://localhost:3000
    description: Local development

tags:
  - name: master-hubs
    description: Global dictionary indexes — traverse all materials, processes, equipment, and industries instantly
  - name: capabilities
    description: Individual solution capability data packages (11,000+ Spoke pages)
  - name: quote
    description: Instant quote and engineering support (Phase 1 mock)

paths:

  # ─────────────────────────────────────────────
  # Master Hub Dictionaries
  # ─────────────────────────────────────────────

  /api/webmcp/dictionaries/master-materials.json:
    servers:
      - url: https://www.mechanofab.com
    get:
      tags: [master-hubs]
      summary: List all materials
      description: Returns the full index of supported materials with physical property bounds.
      operationId: getMasterMaterials
      responses:
        "200":
          description: Material dictionary
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MasterMaterialsCollection"

  /api/webmcp/dictionaries/master-processes.json:
    servers:
      - url: https://www.mechanofab.com
    get:
      tags: [master-hubs]
      summary: List all manufacturing processes
      description: Returns the full index of supported processes with capability bounds.
      operationId: getMasterProcesses
      responses:
        "200":
          description: Process dictionary
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MasterProcessesCollection"

  /api/webmcp/dictionaries/master-equipment.json:
    servers:
      - url: https://www.mechanofab.com
    get:
      tags: [master-hubs]
      summary: List all equipment
      description: Returns the full index of production equipment with hard specs and precision grades.
      operationId: getMasterEquipment
      responses:
        "200":
          description: Equipment dictionary
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MasterEquipmentCollection"

  /api/webmcp/dictionaries/master-industries.json:
    servers:
      - url: https://www.mechanofab.com
    get:
      tags: [master-hubs]
      summary: List all industries
      description: Returns the full index of served industries with compliance standards.
      operationId: getMasterIndustries
      responses:
        "200":
          description: Industries dictionary
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MasterIndustriesCollection"

  # ─────────────────────────────────────────────
  # Capabilities
  # ─────────────────────────────────────────────

  /capabilities-index.json:
    get:
      tags: [capabilities]
      summary: List all capability slugs
      description: Returns the index of all available capability solution slugs. Use to enumerate all 11,000+ Spoke pages.
      operationId: getCapabilitiesIndex
      responses:
        "200":
          description: Capabilities slug index
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CapabilitiesIndex"

  /capabilities/{slug}.json:
    get:
      tags: [capabilities]
      summary: Get capability detail by slug
      description: |
        Returns the full capability data package for a specific manufacturing solution.
        Includes physical properties, manufacturing limits, commercial parameters,
        visual proofs, and the `mechanofab_connect` inquiry anchor.
      operationId: getCapabilityBySlug
      parameters:
        - name: slug
          in: path
          required: true
          description: Kebab-case capability slug (e.g. `surgical-robotics-polycarbonate-2405-injection-molding`)
          schema:
            type: string
            example: surgical-robotics-polycarbonate-2405-injection-molding
      responses:
        "200":
          description: Capability data package
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebMcpCapability"
        "404":
          description: Capability not found

  # ─────────────────────────────────────────────
  # Quote (Phase 1 Mock — Phase 3 Dynamic)
  # ─────────────────────────────────────────────

  /api/quote/calculate:
    post:
      tags: [quote]
      summary: Calculate rapid manufacturing quote (Phase 1 mock)
      description: |
        **Phase 1**: Returns a mock response directing users to WhatsApp/WeCom for an instant quote.
        **Phase 3**: Will connect to Alibaba Cloud LangGraph state machine for dynamic pricing.
        Upgrading requires only a `base_url` change — no schema modifications needed.
      operationId: calculateRapidQuote
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QuoteRequest"
      responses:
        "200":
          description: Quote result (Phase 1 mock)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QuoteResponseMock"

components:
  schemas:

    # ── Master Hub Schemas ──────────────────────

    MasterMaterial:
      type: object
      required: [material_id, physical_properties]
      properties:
        material_id:
          type: string
          example: polycarbonate-2405
        physical_properties:
          type: object
          properties:
            density_g_cm3:    { type: string, example: "1.20 g/cm³" }
            tensile_strength_mpa: { type: string, example: "65.0 MPa" }
            max_service_temp_c:   { type: string, example: "125°C" }
            hardness:             { type: string, example: "118 Rockwell R" }

    MasterProcess:
      type: object
      required: [process_id, capability_bounds]
      properties:
        process_id:
          type: string
          example: injection-molding
        capability_bounds:
          type: object
          properties:
            min_feature_size:   { type: string, example: "Min Wall: 0.8mm" }
            standard_tolerance: { type: string, example: "DIN 16742 TG 4" }

    MasterEquipment:
      type: object
      required: [equipment_id, hard_specs, precision_grade]
      properties:
        equipment_id:    { type: string, example: zhafir-zeres-iii-190t }
        hard_specs:      { type: string, example: "Clamping Force: 190T; Max Injection Volume: 320 cm³" }
        precision_grade: { type: string, example: "High precision, closed-loop control system" }

    MasterIndustry:
      type: object
      required: [industry_id, compliance_standards]
      properties:
        industry_id:           { type: string, example: surgical-robotics }
        compliance_standards:  { type: string, example: "ISO 13485, FDA Class II/III, IEC 60601-1" }

    MasterCollection:
      type: object
      required: [updated_at, total, data]
      properties:
        updated_at: { type: string, format: date, example: "2026-04-14" }
        total:      { type: integer, example: 3 }
        data:       { type: array, items: {} }

    MasterMaterialsCollection:
      allOf:
        - $ref: "#/components/schemas/MasterCollection"
        - properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/MasterMaterial"

    MasterProcessesCollection:
      allOf:
        - $ref: "#/components/schemas/MasterCollection"
        - properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/MasterProcess"

    MasterEquipmentCollection:
      allOf:
        - $ref: "#/components/schemas/MasterCollection"
        - properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/MasterEquipment"

    MasterIndustriesCollection:
      allOf:
        - $ref: "#/components/schemas/MasterCollection"
        - properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/MasterIndustry"

    # ── Capabilities Schemas ────────────────────

    CapabilitiesIndex:
      type: object
      required: [updated_at, total, slugs]
      properties:
        updated_at: { type: string, format: date, example: "2026-04-14" }
        total:      { type: integer, example: 1 }
        slugs:
          type: array
          items: { type: string }
          example: ["surgical-robotics-polycarbonate-2405-injection-molding"]

    VisualProof:
      type: object
      required: [url]
      properties:
        url:       { type: string, format: uri }
        title:     { type: string }
        thumbnail: { type: string, format: uri }

    MechanofabConnect:
      type: object
      required: [about_us, instant_quote_url, engineering_support_email]
      properties:
        about_us:                   { type: string }
        instant_quote_url:          { type: string, format: uri, example: "https://www.mechanofab.com/quote" }
        engineering_support_email:  { type: string, format: email, example: "rfq@mechanofab.com" }

    WebMcpCapability:
      type: object
      required:
        - target_application
        - physical_properties
        - manufacturing_limits
        - commercial_parameters
        - visual_proofs
        - mechanofab_connect
      properties:
        target_application:
          type: string
          example: "Surgical Robotics — Polycarbonate PC-2405 Injection Molding"
        physical_properties:
          type: object
          properties:
            density:               { type: string, example: "1.20 g/cm³" }
            tensile_strength:      { type: string, example: "65 MPa" }
            max_service_temperature: { type: string, example: "135 °C" }
            hardness:              { type: string, example: "Rockwell R118" }
            standard_tolerance:    { type: string, example: "ISO 2768-m / ±0.05 mm" }
        manufacturing_limits:
          type: object
          properties:
            equipment_hard_specs:     { type: string }
            min_feature_size:         { type: string, example: "0.8 mm wall thickness" }
            equipment_precision_grade: { type: string }
        commercial_parameters:
          type: object
          properties:
            factory_advantage: { type: string }
            target_volume:     { type: string, example: "5,000 – 500,000 pcs/year" }
        visual_proofs:
          type: array
          items:
            $ref: "#/components/schemas/VisualProof"
          description: "Zero-empty-state: defaults to []. Only populated after R2 upload."
        mechanofab_connect:
          $ref: "#/components/schemas/MechanofabConnect"
        mdx_body:
          type: string
          description: Optional MDX long-form article body. Present when R2 compiled content is available.
        identifier:
          type: string
          description: Copyright probe. Always "MechanoFab-Spec-v4".
          example: MechanoFab-Spec-v4

    # ── Quote Schemas ───────────────────────────

    QuoteRequest:
      type: object
      required: [material_slug, process_slug, quantity]
      properties:
        material_slug: { type: string, example: polycarbonate-2405 }
        process_slug:  { type: string, example: injection-molding }
        quantity:      { type: integer, example: 10000 }
        notes:         { type: string, example: "ISO 13485 cleanroom required" }

    QuoteResponseMock:
      type: object
      properties:
        status:
          type: string
          example: mock
        message:
          type: string
          example: >
            Dynamic calculation API is deploying.
            Please use the WhatsApp/WeCom link to get an instant quote from our engineers.
        instant_quote_url:
          type: string
          format: uri
          example: https://www.mechanofab.com/quote
        engineering_support_email:
          type: string
          format: email
          example: rfq@mechanofab.com