Zones - Zone-Driven Inventory & Merchandising

Domain: Zones Location: api/nextango/apps/zones/ Last Updated: 2025-12-21

Overview

The Zones app implements zone-driven inventory management where par levels define "what should be where" (ideal quantities) and inventory levels track "what is actually there" (actual quantities). Includes compliance tracking, merchandising standards, zone inventory, planogram management, and automatic infrastructure creation.

Documentation Quick Links

Core Documentation

File	Description
models.md	Zone, ZoneInventory, ParLevelItem, Planogram models
serializers.md	Sanity webhook processing with camelCase conversion
views.md	All 7 ViewSets with zone API endpoints
services.md	ZoneAssignmentService business logic
signals.md	Infrastructure automation signals
examples.md	Usage examples and patterns

Key Features

Zone-Driven Architecture

Par levels - Define "what should be where" (ideal quantities)
Inventory levels - Track "what is actually there" (actual quantities)
Automatic infrastructure - Signals auto-create InventoryLevel records
Zone types - Compliance, merchandising, inventory
SKU validation - Validate SKUs against ProductVariant records
Sanity webhook integration - Automatic camelCase to snake_case conversion

Zone Types

Compliance zones - Checklists, photo requirements, frequency
Merchandising zones - Display standards, required products
Inventory zones - Par levels, count frequency, inventory tracking

Automation Features

Auto-create InventoryLevel - When ParLevelItem is created (signal)
Auto-cleanup orphaned records - When last ParLevelItem deleted (signal)
Auto-create zone configurations - When Zone is created (signal)
Bulk sync infrastructure - Via ZoneAssignmentService

API Endpoints

Zone Management

Endpoint	Method	Description	Doc Reference
`/zones/`	GET, POST, PUT, PATCH, DELETE	Zone CRUD operations	views.md
`/zones/{id}/products/`	GET	Get all products in zone	views.md
`/zones/{id}/sync_inventory/`	POST	Create inventory infrastructure	views.md
`/zones/by_store/`	GET	Get zones by store location	views.md

Zone Type Management

Endpoint	Method	Description	Doc Reference
`/zones/compliance/`	GET, POST, PUT, PATCH, DELETE	Compliance configuration	views.md
`/zones/merchandising/`	GET, POST, PUT, PATCH, DELETE	Merchandising standards	views.md
`/zones/inventory/`	GET, POST, PUT, PATCH, DELETE	Inventory configuration	views.md
`/zones/inventory/{id}/validate_skus/`	POST	Validate all SKUs in zone	views.md

Par Level Management

Endpoint	Method	Description	Doc Reference
`/zones/par-levels/`	GET, POST, PUT, PATCH, DELETE	Par level CRUD	views.md
`/zones/par-levels/{id}/ensure_inventory_level/`	POST	Create InventoryLevel for par level	views.md
`/zones/par-levels/by_product/`	GET	Get par levels for product variant	views.md

Planogram Management

Endpoint	Method	Description	Doc Reference
`/planograms/`	GET, POST, PUT, PATCH, DELETE	Planogram CRUD	views.md
`/planograms/{id}/target_assignments/`	GET	Get target stores and zones	views.md
`/planograms/products/`	GET, POST, PUT, PATCH, DELETE	Planogram product CRUD	views.md

Full endpoint documentation: views.md

Architecture Highlights

Zone-Driven Inventory Flow

Zones → ZoneInventory → ParLevelItem → InventoryLevel
  ↓           ↓              ↓              ↓
Define     Configure    "Should have"   "Actually have"
 zone        type         10 units        5 units

Read more: models.md, services.md

Signal-Based Infrastructure Automation

Zones uses Django signals appropriately for infrastructure automation:

Auto-create InventoryLevel when ParLevelItem created
Auto-cleanup InventoryLevel when last ParLevelItem deleted
Auto-create zone type configurations when Zone created
Contrast with web_auth (service-based) approach

Read more: signals.md

Service Layer Business Logic

ZoneAssignmentService provides explicit business operations:

create_inventory_infrastructure_for_zone() - Bulk create InventoryLevels
validate_sku_assignments() - Validate SKUs match ProductVariants
get_products_for_zone() - Get all products assigned to zone
get_zone_assignments_for_product() - Find where product should be

Read more: services.md

Getting Started

1. Understand the Models

Start with models.md to understand:

Zone model (zone_name, store_location, zone_type)
ZoneInventory (count_frequency, last_count_date)
ParLevelItem (product, variant_sku, quantity)
Planogram (planogram_name, target_stores, target_zones)

2. Review the Data Flow

Read services.md to understand:

How zones define inventory organization
How par levels define ideal quantities
How InventoryLevel tracks actual quantities
How infrastructure is automatically created

3. Explore API Endpoints

Check views.md to learn:

Zone CRUD operations
Par level management
Planogram operations
SKU validation

4. Understand Sanity Integration

Review serializers.md for:

Webhook processing workflow
camelCase to snake_case conversion
Nested relationship handling
Field transformation patterns

Products - Product, ProductVariant, InventoryLevel models
Stores - Store locations for zones
Integrations - Sanity CMS webhook processing
Transactions - Zone-based transaction tracking

Key Architectural Decisions

Signals for infrastructure - Appropriate use of signals for automatic record creation
Service layer for business logic - Explicit operations via ZoneAssignmentService
Par levels vs inventory levels - Separate "should have" from "actually have"
Automatic infrastructure creation - Signals ensure InventoryLevel always exists
SKU validation - Prevent invalid product assignments

Common Use Cases

Zone setup - Create zones with compliance/merchandising/inventory configuration
Par level management - Define ideal product quantities per zone
Inventory sync - Auto-create InventoryLevel infrastructure
SKU validation - Ensure all par levels reference valid product variants
Planogram execution - Visual merchandising with product placement
Product distribution analysis - Find all locations where product should be stocked

Service Methods

ZoneAssignmentService

Infrastructure Management:

create_inventory_infrastructure_for_zone(zone) - Create all InventoryLevels for zone
sync_par_levels_to_inventory(store) - Bulk sync all par levels at store
cleanup_orphaned_inventory_levels(store) - Remove inventory without par levels

Product Assignment:

get_products_for_zone(zone) - Get all products assigned to zone
get_zone_assignments_for_product(product, variant_sku) - Find where product assigned

Validation:

validate_sku_assignments(zone_inventory) - Validate all SKUs in zone

Full documentation: services.md

Next Steps

Start with models.md - Understand the data structure
Then services.md - Learn the business logic
Review views.md - Explore API endpoints
Check signals.md - See infrastructure automation
Review serializers.md - Understand Sanity integration