{
  "openapi": "3.1.0",
  "info": {
    "title": "ELC Summer Internship Portal API",
    "version": "1.0.0",
    "description": "Backend API for the ELC Summer Internship Portal (TIET Patiala). Built with TypeScript for Cloudflare Workers and Node.js runtimes. Implements workflows defined in the ELC Portal Development Handbook.",
    "contact": {
      "name": "Experiential Learning Centre (ELC) × MLSC TIET",
      "email": "elc_management@thapar.edu"
    }
  },
  "servers": [
    {
      "url": "/",
      "description": "Current Environment / Local Server"
    },
    {
      "url": "https://elc-backend.mlsctiet.com",
      "description": "Production Cloudflare Worker"
    }
  ],
  "tags": [
    {
      "name": "System",
      "description": "System health, metadata, and status checks"
    },
    {
      "name": "Authentication",
      "description": "Institutional @thapar.edu Google login and session roles"
    },
    {
      "name": "Projects",
      "description": "Faculty proposals, seat counters, and live directory"
    },
    {
      "name": "Slots",
      "description": "Faculty slot management and student pre-screening"
    },
    {
      "name": "Offers",
      "description": "Lead mentor offer issuance and 24-hour student acceptance"
    },
    {
      "name": "Submissions",
      "description": "Team artifacts and individual student internship reports"
    },
    {
      "name": "Certificates",
      "description": "Shortlisting, administrative confirmation, and PDF generation"
    },
    {
      "name": "Verification",
      "description": "Public certificate verification (strictly no private data)"
    },
    {
      "name": "Admin",
      "description": "Global cycle dates, limits, rule exceptions, and CSV exports"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "System health check",
        "description": "Returns runtime health, uptime, environment, database connectivity, and documentation links.",
        "responses": {
          "200": {
            "description": "System is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "example": "ok"
                        },
                        "service": {
                          "type": "string",
                          "example": "elc-backend-worker"
                        },
                        "version": {
                          "type": "string",
                          "example": "1.0.0"
                        },
                        "environment": {
                          "type": "string",
                          "example": "production"
                        },
                        "uptimeSeconds": {
                          "type": "number",
                          "example": 42.5
                        },
                        "database": {
                          "type": "string",
                          "example": "connected"
                        },
                        "docsUrl": {
                          "type": "string",
                          "example": "/docs"
                        }
                      }
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/login": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Institutional sign-in",
        "description": "Authenticates a user using @thapar.edu Google OAuth token and determines user role (student, faculty, admin).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "token"
                ],
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "Google OAuth ID token"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Authentication successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "token": {
                          "type": "string"
                        },
                        "user": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "email": {
                              "type": "string"
                            },
                            "name": {
                              "type": "string"
                            },
                            "role": {
                              "type": "string",
                              "enum": [
                                "student",
                                "faculty",
                                "admin"
                              ]
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Non-thapar.edu email or invalid credentials"
          }
        }
      }
    },
    "/api/projects": {
      "get": {
        "tags": [
          "Projects"
        ],
        "summary": "List active projects",
        "description": "Returns live projects with real-time seat counters, department filters, and mentor credits.",
        "parameters": [
          {
            "name": "department",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by department"
          },
          {
            "name": "openOnly",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "Show only projects with open seats"
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated project directory",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "projectNumber": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "department": {
                            "type": "string"
                          },
                          "leadMentor": {
                            "type": "string"
                          },
                          "seatsTotal": {
                            "type": "integer"
                          },
                          "seatsOpen": {
                            "type": "integer"
                          },
                          "status": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/slots/book": {
      "post": {
        "tags": [
          "Slots"
        ],
        "summary": "Book screening slot",
        "description": "Students book an online or offline interview slot after completing pre-screening questions.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "projectId",
                  "slotId",
                  "answers"
                ],
                "properties": {
                  "projectId": {
                    "type": "string"
                  },
                  "slotId": {
                    "type": "string"
                  },
                  "answers": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Slot booked successfully"
          },
          "409": {
            "description": "Slot is full or student already booked"
          }
        }
      }
    },
    "/api/offers/accept": {
      "post": {
        "tags": [
          "Offers"
        ],
        "summary": "Accept faculty offer",
        "description": "Student accepts an offer within the 24-hour validity window. Automatically updates seat counter and marks other applications closed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "offerId"
                ],
                "properties": {
                  "offerId": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Offer accepted and enrolled"
          },
          "410": {
            "description": "Offer expired after 24 hours"
          }
        }
      }
    },
    "/api/verify/{certificateId}": {
      "get": {
        "tags": [
          "Verification"
        ],
        "summary": "Public certificate verification",
        "description": "Public, unauthenticated check for certificate authenticity via QR code scan or certificate ID. Never reveals private student details.",
        "parameters": [
          {
            "name": "certificateId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Certificate verification details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "valid": {
                          "type": "boolean"
                        },
                        "certificateNumber": {
                          "type": "string"
                        },
                        "studentName": {
                          "type": "string"
                        },
                        "projectTitle": {
                          "type": "string"
                        },
                        "completionDate": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Certificate ID not found or revoked"
          }
        }
      }
    }
  }
}