{
  "feature": "service-zones",
  "version": "1.0.0",
  "description": "Define geographic service areas and subdivide them into operational zones, used to scope fleet operations, restrict order pickup and drop-off, and assign drivers to specific areas.",
  "category": "data",
  "tags": [
    "geospatial",
    "zones",
    "service-areas",
    "polygons",
    "operations"
  ],
  "actors": [
    {
      "id": "operator",
      "name": "Fleet Operator",
      "type": "human",
      "description": "Defines service areas and zones using polygon geometries."
    },
    {
      "id": "platform",
      "name": "Platform",
      "type": "system",
      "description": "Enforces zone containment checks for orders and driver assignments."
    }
  ],
  "fields": [
    {
      "name": "service_area_id",
      "type": "text",
      "required": false,
      "label": "Public identifier of the service area."
    },
    {
      "name": "service_area_name",
      "type": "text",
      "required": true,
      "label": "Human-readable name of the service area (e.g., \"Greater Cape Town\")."
    },
    {
      "name": "service_area_type",
      "type": "select",
      "required": false,
      "label": "Geometry type for the service area border.",
      "options": [
        {
          "value": "polygon",
          "label": "Polygon"
        },
        {
          "value": "multi_polygon",
          "label": "Multi Polygon"
        }
      ]
    },
    {
      "name": "border",
      "type": "json",
      "required": true,
      "label": "GeoJSON polygon or multi-polygon defining the geographic boundary."
    },
    {
      "name": "color",
      "type": "text",
      "required": false,
      "label": "Fill color used to render the area on maps."
    },
    {
      "name": "stroke_color",
      "type": "text",
      "required": false,
      "label": "Border/outline color for map rendering."
    },
    {
      "name": "status",
      "type": "select",
      "required": false,
      "label": "Whether this service area is active.",
      "options": [
        {
          "value": "active",
          "label": "Active"
        },
        {
          "value": "inactive",
          "label": "Inactive"
        }
      ]
    },
    {
      "name": "zone_id",
      "type": "text",
      "required": false,
      "label": "Public identifier of a sub-zone."
    },
    {
      "name": "zone_name",
      "type": "text",
      "required": true,
      "label": "Name of the zone (e.g., \"City Bowl\", \"Northern Suburbs\")."
    },
    {
      "name": "zone_description",
      "type": "text",
      "required": false,
      "label": "Description of what the zone covers."
    },
    {
      "name": "zone_border",
      "type": "json",
      "required": true,
      "label": "GeoJSON polygon defining the zone's boundary within the service area."
    }
  ],
  "rules": {
    "rule_01": "Service areas use multi-polygon geometry to support non-contiguous regions.",
    "rule_02": "Zones use single polygon geometry and are always nested within a parent service area.",
    "rule_03": "All service area and zone records are scoped to the organization.",
    "rule_04": "Zones can be assigned to fleets to restrict or organize operational coverage.",
    "rule_05": "Orders may be validated against service area boundaries; orders outside all active service areas can be rejected.",
    "rule_06": "Zone entry and exit detection (driver crossing a zone boundary) is supported via location change events.",
    "rule_07": "Service areas and zones support visual differentiation via color and stroke_color for map display."
  },
  "outcomes": {
    "service_area_created": {
      "priority": 1,
      "given": [
        "operator provides a name and valid polygon geometry"
      ],
      "then": [
        {
          "action": "create_record",
          "description": "Service area is stored with spatial index for efficient containment queries.",
          "type": "service_area"
        }
      ],
      "result": "Service area is active and available for zone nesting, fleet scoping, and order validation."
    },
    "zone_created": {
      "priority": 2,
      "given": [
        "operator provides a zone name, polygon geometry, and a parent service area reference"
      ],
      "then": [
        {
          "action": "create_record",
          "description": "Zone is stored as a sub-region of the service area.",
          "type": "zone"
        }
      ],
      "result": "Zone is available for fleet assignment and driver geo-fencing."
    },
    "fleet_scoped_to_zone": {
      "priority": 3,
      "given": [
        "dispatcher assigns a fleet to a service area and/or zone"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "fleet.service_area_id",
          "description": "Fleet is associated with the service area."
        },
        {
          "action": "set_field",
          "target": "fleet.zone_id",
          "description": "Fleet is associated with the specific zone."
        }
      ],
      "result": "Fleet operations are logically restricted to the assigned zone."
    },
    "zone_containment_checked": {
      "priority": 4,
      "given": [
        "a point (driver or order location) is tested against zone boundaries"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "response.inside_zone",
          "description": "Boolean result indicating if the point falls within any zone boundary."
        }
      ],
      "result": "Platform can enforce or report whether a given location is within an operational zone."
    }
  },
  "errors": [
    {
      "code": "SERVICE_AREA_NOT_FOUND",
      "status": 404,
      "message": "The specified service area could not be found."
    },
    {
      "code": "ZONE_NOT_FOUND",
      "status": 404,
      "message": "The specified zone could not be found."
    },
    {
      "code": "INVALID_GEOMETRY",
      "status": 400,
      "message": "The provided border geometry is not a valid polygon."
    }
  ],
  "events": [
    {
      "name": "zone.driver_entered",
      "description": "Driver's location update places them inside a zone boundary.",
      "payload": [
        "zone_id",
        "driver_id",
        "latitude",
        "longitude"
      ]
    },
    {
      "name": "zone.driver_exited",
      "description": "Driver's location update places them outside a zone they were previously in.",
      "payload": [
        "zone_id",
        "driver_id",
        "latitude",
        "longitude"
      ]
    }
  ],
  "related": [
    {
      "feature": "fleet-vehicle-registry",
      "type": "recommended",
      "reason": "Fleets can be scoped to specific service areas and zones."
    },
    {
      "feature": "driver-location-streaming",
      "type": "recommended",
      "reason": "Driver location updates enable real-time zone entry/exit detection."
    },
    {
      "feature": "driver-assignment-dispatch",
      "type": "optional",
      "reason": "Dispatch can be filtered to drivers within a specific zone."
    }
  ],
  "agi": {
    "goals": [
      {
        "id": "reliable_service_zones",
        "description": "Define geographic service areas and subdivide them into operational zones, used to scope fleet operations, restrict order pickup and drop-off, and assign drivers to specific areas.",
        "success_metrics": [
          {
            "metric": "data_accuracy",
            "target": "100%",
            "measurement": "Records matching source of truth"
          },
          {
            "metric": "duplicate_rate",
            "target": "0%",
            "measurement": "Duplicate records detected post-creation"
          }
        ],
        "constraints": [
          {
            "type": "performance",
            "description": "Data consistency must be maintained across concurrent operations",
            "negotiable": false
          }
        ]
      }
    ],
    "autonomy": {
      "level": "supervised",
      "human_checkpoints": [
        "before making irreversible changes"
      ],
      "escalation_triggers": [
        "error_rate > 5"
      ]
    },
    "safety": {
      "action_permissions": [
        {
          "action": "service_area_created",
          "permission": "supervised"
        },
        {
          "action": "zone_created",
          "permission": "supervised"
        },
        {
          "action": "fleet_scoped_to_zone",
          "permission": "autonomous"
        },
        {
          "action": "zone_containment_checked",
          "permission": "autonomous"
        }
      ]
    },
    "tradeoffs": [
      {
        "prefer": "data_integrity",
        "over": "performance",
        "reason": "data consistency must be maintained across all operations"
      }
    ]
  },
  "extensions": {
    "source": {
      "repo": "https://github.com/fleetbase/fleetbase",
      "project": "Fleetbase",
      "tech_stack": "PHP / Laravel",
      "files_traced": 4,
      "entry_points": [
        "src/Models/ServiceArea.php",
        "src/Models/Zone.php",
        "src/Http/Controllers/Api/v1/ServiceAreaController.php",
        "src/Http/Controllers/Api/v1/ZoneController.php"
      ]
    }
  }
}