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
• sync shipping postal codes that fall within a region
• 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

Channel	Role	Notes
Admin geo-regions API	Direct read-only	Main packaged list surface
Address observer and sync action	Indirect	Keeps address-region membership aligned with geography
Shipping postal code sync action	Indirect	Keeps shipping postal code membership aligned with geography
Sale region aggregate	Indirect upstream input	SaleRegion sums the population of its geo regions
Excel prompt parsing	Indirect upstream input	Geo-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/GeoRegion/SyncShippingPostalCodes.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 and shipping postal code memberships are synchronized from containment checks

Sources:

• packages/framework/src/Actions/Address/SyncGeoRegions.php
• packages/framework/src/Observers/AddressObserver.php
• packages/framework/src/Actions/GeoRegion/SyncShippingPostalCodes.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. A reverse helper named GeoRegion/SyncAddresses exists, but this pass did not confirm it as the main packaged ownership path.

Sources:

• packages/framework/src/Actions/Address/SyncGeoRegions.php
• packages/framework/src/Observers/AddressObserver.php
• packages/framework/src/Actions/GeoRegion/SyncAddresses.php
• packages/framework/src/Actions/GeoRegion/SyncShippingPostalCodes.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/GeoRegion/SyncAddresses.php
• packages/framework/src/Actions/Address/SyncGeoRegions.php
• packages/framework/src/Observers/AddressObserver.php
• packages/framework/src/Actions/GeoRegion/SyncShippingPostalCodes.php
• packages/framework/src/Actions/Excel/ParsePrompt.php
• packages/framework/src/Actions/Address/SyncGeoRegions.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