{
  "openapi": "3.0.3",
  "info": {
    "title": "Operio REST API Documentation",
    "description": "Comprehensive OpenAPI documentation for Operio construction workforce management & multi-tenant APIs. Implements a 4-tier Role-Based Access Control (RBAC) hierarchy: Level 1: Super Admin (Global Platform Admin), Level 2: Tenant Admin (Organization Admin under Super Admin), Level 3: Supervisor (Operations & Field Supervisor), Level 4: Field Worker (On-site Worker & Companion App User).",
    "version": "1.2.0",
    "contact": {
      "name": "Operio Engineering Team",
      "email": "support@operio.io"
    }
  },
  "servers": [
    {
      "url": "http://127.0.0.1:8080",
      "description": "Local Development Server"
    }
  ],
  "paths": {
    "/api/v1/health": {
      "get": {
        "summary": "API & System Health Check",
        "description": "Returns system health status, database connection latency, cache driver operation, storage writeability, and runtime diagnostics.",
        "tags": ["Health Check"],
        "responses": {
          "200": {
            "description": "System is healthy",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok",
                  "service": "operio-backend",
                  "version": "1.0.0",
                  "timestamp": "2026-09-09T14:20:00+00:00",
                  "checks": {
                    "database": { "status": "healthy", "driver": "sqlite", "latency_ms": 1.04 },
                    "cache": { "status": "healthy", "driver": "database" },
                    "storage": { "status": "healthy", "writable": true },
                    "system": { "php_version": "8.5.9", "laravel_version": "13.31.0", "environment": "local", "memory_usage_mb": 2, "execution_time_ms": 4.89 }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/auth/roles": {
      "get": {
        "summary": "List System Roles Taxonomy & Capabilities",
        "description": "Returns the complete 4-tier role hierarchy (Super Admin, Tenant Admin, Supervisor, Field Worker), authorization scopes, and capability definitions.",
        "tags": ["Role Taxonomy"],
        "responses": {
          "200": {
            "description": "4-tier role hierarchy taxonomy",
            "content": {
              "application/json": {
                "example": {
                  "status": "success",
                  "roles": [
                    { "key": "Super Admin", "name": "Super Admin", "level": 1, "description": "Global Operio platform administrator with oversight across all tenant organizations.", "scope": "Platform Global" },
                    { "key": "Tenant Admin", "name": "Tenant Admin", "level": 2, "description": "Organization-level administrator managing company settings, users, payroll, and projects under the Super Admin.", "scope": "Tenant Organization" },
                    { "key": "Supervisor", "name": "Supervisor", "level": 3, "description": "Field operations supervisor overseeing assigned crews, site clock-ins, daily logs, and geofence exception approvals.", "scope": "Assigned Crews & Sites" },
                    { "key": "Field Worker", "name": "Field Worker", "level": 4, "description": "On-site field worker or crew member using mobile companion app for clocking in/out and submitting progress photos.", "scope": "Personal Workspace & Companion App" }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/auth/login": {
      "post": {
        "summary": "User Login",
        "description": "Authenticates user credentials across any of the 4 role levels and issues a Sanctum Bearer API access token.",
        "tags": ["Authentication"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email", "password"],
                "properties": {
                  "email": { "type": "string", "example": "superadmin@operio.io" },
                  "password": { "type": "string", "example": "password123" },
                  "device_name": { "type": "string", "example": "operio-client-portal" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Authentication successful",
            "content": {
              "application/json": {
                "example": {
                  "status": "success",
                  "message": "Authentication successful.",
                  "access_token": "4|eO6Tk9jELpYKMvglmE86TvsqueUze9IBqIF0S8ln326c0081",
                  "token_type": "Bearer",
                  "user": {
                    "id": 6,
                    "name": "Super Administrator",
                    "email": "superadmin@operio.io",
                    "role": "Super Admin",
                    "normalized_role": "Super Admin",
                    "is_super_admin": true,
                    "permissions": {
                      "manage_platform": true,
                      "manage_all_tenants": true,
                      "manage_tenant_settings": true,
                      "manage_users": true,
                      "manage_crews": true,
                      "approve_overrides": true,
                      "run_payroll": true,
                      "view_financials": true,
                      "submit_daily_logs": true
                    },
                    "tenant": null
                  }
                }
              }
            }
          },
          "401": { "description": "Invalid credentials or password" }
        }
      }
    },
    "/api/v1/auth/register": {
      "post": {
        "summary": "Organization & User Registration",
        "description": "Registers a new tenant organization and initial user account under one of the system roles.",
        "tags": ["Authentication"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "organization_name", "email", "password"],
                "properties": {
                  "name": { "type": "string", "example": "Chinedu Obi" },
                  "organization_name": { "type": "string", "example": "New Horizon Ltd" },
                  "email": { "type": "string", "example": "chinedu@newhorizon.com" },
                  "role": { "type": "string", "enum": ["Super Admin", "Tenant Admin", "Supervisor", "Field Worker"], "example": "Tenant Admin" },
                  "password": { "type": "string", "example": "password123" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Organization and account created" },
          "422": { "description": "Validation error" }
        }
      }
    },
    "/api/v1/auth/me": {
      "get": {
        "summary": "Get Authenticated Profile",
        "description": "Retrieves authenticated user details, normalized role, capability matrix, and active tenant data.",
        "tags": ["Authentication"],
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": {
            "description": "User profile",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/UserResponse" }
              }
            }
          },
          "401": { "description": "Unauthenticated" }
        }
      }
    },
    "/api/v1/auth/switch-role": {
      "post": {
        "summary": "Switch User Role",
        "description": "Switches the active user role and recalculates system capability permissions.",
        "tags": ["Authentication"],
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["role"],
                "properties": {
                  "role": { "type": "string", "enum": ["Super Admin", "Tenant Admin", "Supervisor", "Field Worker"], "example": "Supervisor" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Role updated successfully" }
        }
      }
    },
    "/api/v1/auth/logout": {
      "post": {
        "summary": "User Logout",
        "description": "Revokes active Sanctum API access token.",
        "tags": ["Authentication"],
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": { "description": "Logged out successfully" }
        }
      }
    },
    "/api/v1/tenants": {
      "get": {
        "summary": "List Tenant Organizations",
        "description": "Lists tenant organizations across the platform. Super Admin sees all platform tenants; Tenant Admin sees their own tenant.",
        "tags": ["Tenant Management"],
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": {
            "description": "Tenants array",
            "content": {
              "application/json": {
                "example": {
                  "status": "success",
                  "count": 2,
                  "tenants": [
                    { "id": 1, "name": "Anchor Infrastructure", "slug": "anchor", "domain": "anchor.operio.io", "plan": "enterprise", "status": "active", "currency": "USD", "country": "Nigeria", "flag": "🇳🇬", "users_count": 4 },
                    { "id": 2, "name": "Beacon Heights Corp", "slug": "beacon", "domain": "beacon.operio.io", "plan": "growth", "status": "active", "currency": "USD", "country": "Jamaica", "flag": "🇯🇲", "users_count": 0 }
                  ]
                }
              }
            }
          },
          "403": { "description": "Unauthorized" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Sanctum Token"
      }
    },
    "schemas": {
      "UserResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "example": "success" },
          "user": { "$ref": "#/components/schemas/User" }
        }
      },
      "User": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "example": 1 },
          "name": { "type": "string", "example": "Super Administrator" },
          "email": { "type": "string", "example": "superadmin@operio.io" },
          "role": { "type": "string", "example": "Super Admin" },
          "normalized_role": { "type": "string", "enum": ["Super Admin", "Tenant Admin", "Supervisor", "Field Worker"], "example": "Super Admin" },
          "is_super_admin": { "type": "boolean", "example": true },
          "permissions": { "$ref": "#/components/schemas/Permissions" },
          "phone": { "type": "string", "example": "+1 800 555 0199" },
          "status": { "type": "string", "example": "active" },
          "tenant": { "$ref": "#/components/schemas/Tenant" }
        }
      },
      "Tenant": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "example": 1 },
          "name": { "type": "string", "example": "Anchor Infrastructure" },
          "slug": { "type": "string", "example": "anchor" },
          "plan": { "type": "string", "example": "enterprise" },
          "currency": { "type": "string", "example": "USD" },
          "flag": { "type": "string", "example": "🇳🇬" }
        }
      },
      "Permissions": {
        "type": "object",
        "properties": {
          "manage_platform": { "type": "boolean", "example": true },
          "manage_all_tenants": { "type": "boolean", "example": true },
          "manage_tenant_settings": { "type": "boolean", "example": true },
          "manage_users": { "type": "boolean", "example": true },
          "manage_crews": { "type": "boolean", "example": true },
          "approve_overrides": { "type": "boolean", "example": true },
          "run_payroll": { "type": "boolean", "example": true },
          "view_financials": { "type": "boolean", "example": true },
          "submit_daily_logs": { "type": "boolean", "example": true }
        }
      }
    }
  }
}