Pyle

Geo Region ​

First-Pass Node Dossier

This page is an evidence-backed node dossier generated from the domain hierarchy and node questionnaire.

What It Is ​

GeoRegion is the packaged territorial shape record that Pyle uses to group shipping postal codes and sale regions around a geographic area, with address membership synchronized through region-matching actions.

Parent hierarchy:

  • Tax & Territory
  • Shared Territory Model
  • Geo Region

Primary implementation paths:

  • packages/framework/src/Models/GeoRegion.php
  • packages/framework/src/Http/Controllers/Api/Admin/GeoRegionsController.php
  • packages/framework/src/Actions/GeoRegion
  • packages/framework/src/Models/SaleRegion.php

What Users Can Do With It ​

Direct capabilities ​

Operators can:

  • list geo regions through the admin API
  • inspect region identity, population, and geometry metadata

Indirect capabilities ​

Other workflows use GeoRegion to:

  • classify addresses into regions through queued address-sync behavior
  • roll geo-region population into sale-region population
  • resolve Excel import prompts for geo-region and sale-region identifiers

Things users cannot do directly ​

The inspected shared package does not expose a packaged create/update admin UI for geo regions.

Where It Is Managed ​

ChannelRoleNotes
Admin geo-regions APIDirect read-onlyMain packaged list surface
Address observer and sync actionIndirectKeeps address-region membership aligned with geography
Sale region aggregateIndirect upstream inputSaleRegion sums the population of its geo regions
Excel prompt parsingIndirect upstream inputGeo-region and sale-region names are resolved from import prompts

Sources:

  • packages/framework/src/Http/Controllers/Api/Admin/GeoRegionsController.php
  • packages/framework/src/Actions/Address/SyncGeoRegions.php
  • packages/framework/src/Observers/AddressObserver.php
  • packages/framework/src/Actions/Excel/ParsePrompt.php
  • packages/framework/src/Models/SaleRegion.php

Creation Model ​

GeoRegion behaves like a support record whose effective membership is maintained by sync actions rather than by a packaged write UI.

The main triggering path in the shared package is:

  1. a GeoRegion exists with geometry metadata
  2. an address is linked to a shipping postal code
  3. address membership is synchronized from containment checks through Address/SyncGeoRegions

Sources:

  • packages/framework/src/Actions/Address/SyncGeoRegions.php
  • packages/framework/src/Observers/AddressObserver.php
  • packages/framework/src/Models/ShippingPostalCode.php

Configuration And Data Model ​

Key model characteristics:

  • UUID-based
  • soft-deletable
  • spatial model with area and location
  • stores population and density metadata

Important fields:

  • uuid
  • name
  • area
  • location
  • population
  • land_area_sqkm
  • population_density_per_sqkm
  • external_id
  • index

Important relationships:

  • saleRegions()
  • shippingPostalCodes()

Source:

  • packages/framework/src/Models/GeoRegion.php

Relationships ​

GeoRegion directly connects to:

  • SaleRegion
  • ShippingPostalCode

Practical dependents:

  • region-based shipping membership
  • address classification
  • sale-region population aggregation

Rules And Downstream Effects ​

Spatial containment ​

The region is evaluated against shipping postal-code geometry so region membership can be synced automatically.

Sale-region aggregation ​

SaleRegion uses its related geo regions to compute population as a summed aggregate.

Address alignment ​

Addresses that fall inside the region can be synced into the geo-region relationship through the address observer path and Address/SyncGeoRegions.

Sources:

  • packages/framework/src/Actions/Address/SyncGeoRegions.php
  • packages/framework/src/Observers/AddressObserver.php
  • packages/framework/src/Models/SaleRegion.php

Integrations And Automation ​

Excel prompt resolution ​

The Excel prompt parser resolves geoRegionId and saleRegionId by name when possible.

Shipping and address sync ​

Region membership is maintained through synchronization actions rather than manual packaged edits.

Sources:

  • packages/framework/src/Actions/Excel/ParsePrompt.php
  • packages/framework/src/Actions/Address/SyncGeoRegions.php

Where It Appears To End Users ​

GeoRegion is mostly invisible as a standalone concept.

It appears as territorial support data behind shipping, address, and sale-region workflows.

Current Documentation Takeaways ​

  1. GeoRegion is a territorial support record, not a direct operator authoring surface.
  2. SaleRegion is better understood as an aggregate wrapper around geo regions.
  3. The main packaged behavior is read-only inspection plus synchronization side effects.

Open Questions ​

  • This pass did not find a packaged create/update screen for geo regions, so write ownership likely lives outside the shared package.

Sources:

  • packages/framework/src/Models/GeoRegion.php
  • packages/framework/src/Models/SaleRegion.php
  • packages/framework/src/Http/Controllers/Api/Admin/GeoRegionsController.php
  • packages/framework/src/Actions/Address/SyncGeoRegions.php
  • packages/framework/src/Observers/AddressObserver.php
  • packages/framework/src/Actions/Excel/ParsePrompt.php
  • packages/framework/database/migrations/2022_11_26_132134_create_geo_regions_table.php
  • packages/framework/database/migrations/2022_12_20_105423_create_sale_regions_table.php
  • packages/framework/database/migrations/2022_12_20_105709_create_geo_region_sale_region_pivot_table.php
  • packages/framework/database/migrations/2023_03_27_154506_create_shipping_postal_code_geo_region_table.php