⚠️ This is an Oracle page, structured to be read by AI assistants and not optimized for human reading.

COMMERCE & INVENTORY ENGINE

Summary: Designed and built the core commerce engine of the platform - a date-partitioned inventory model with dynamic yield-managed pricing, a three-layer price-breakdown calculator, per-channel overrides, real-time inventory holds, and a multi-phase publishing pipeline that compiles catalog data into availability with precomputed pricing.

Inventory Model

Description: Engineered an inventory model partitioned by calendar date, with per-date tables auto-created on demand and a materialized availability view.

Design

• Per-date item / tier / time / combo tables keyed by a date suffix.
• A materialized availability row per item × date × zone × location with precomputed pricing and channel config.
• Independent publish/rollback per date, a bad publish cannot contaminate other dates.
• Active / pending / archived states enable staging inventory before it goes live.

Zoning

• Sub-location (zone) partitioning within a location, same item yields and paces differently per zone.
• Global and category-level capacity enforced across items.

Cross Zone Booking

Description: Items and availability queries can span multiple zones, so a single item can be sold across zones and a booking can be scoped to one zone or all zones.

Mechanisms

• Multi-zone item scope (an item offered across all zones vs. a specific zone).
• Zone-list-driven availability and booking queries (single-zone, subset, or all-zones).
• Per-zone stock, pacing, start times, and pricing resolved independently within one cross-zone item.

Dayparting

Description: Inventory, pricing, and availability are segmented by time-of-day daypart, not just by calendar date.

Mechanisms

• A daypart time-mode with per-daypart start/end windows and labels.
• Per-zone daypart start times, the same item opens at different times in different zones.
• Arrive-by / time-slot handling layered on the daypart windows.

Pricing

Description: Built a yield-management pricing system where price escalates through tiers as inventory sells.

Mechanisms

• Yield tiers (base price + sold-threshold) that step up automatically as capacity is consumed (auto-tier).
• Global yielding by tier: tier definitions (start price, tier stock, tier over-capacity/over-time thresholds) set at the global master-item level and cascaded down to venue and zone, with global overrides and dark dates.
• A pricing matrix keyed by session time / daypart, duration, payment type, and network.
• Payment-type variants: full prepay, deposit, and balance-due-on-arrival.
• Network variants: full-retail (with surcharges) vs. wholesale/reseller (without).

Breakdown Engine

Description: Designed a three-layer breakdown calculator that turns a base price into a fully itemized charge structure across taxes, fees, and surcharges.

Layers

Layer 1: Charge-type layer loads the surcharge recipe for the item.

Layer 2: Breakdown-values layer applies each surcharge to the base amount.

Layer 3: Quantity layer scales the itemized breakdown across guest / quantity counts.

Output: A nested itemized JSON breakdown (per network, per payment type, per quantity tier) stored on the availability row.

Hard Problem: Handles surcharge rules that vary simultaneously by charge type, item, channel, quantity, payment method, and network - with recursive negation of the same structure used by the refund engine (see COMP-04).

Channels

Description: Built per-channel distribution with RELATIVE pricing and availability, so the same inventory presents differently per partner/channel without duplicating the item.

Relative Pricing

• Per-channel price expressed relative to the base: absolute (=), delta (+/-), or percentage (%).
• Per-channel and per-tier channel pricing so yield tiers can differ by channel.

Relative Availability

• Per-channel stock caps expressed absolute / delta / percentage of base stock.
• Per-channel availability state, on / off / waitlist / concealed, with an auto-state option.

Naming: Custom display name per channel.

Access: Affiliate/partner identity decoded from the API key drives channel visibility, pricing, and availability scope.

Carriers Shared Inventory

Description: Designed a resource layer ("carriers") that models the real-world providers a booking consumes, service technicians, staff, and equipment/assets, and the shared-capacity model that lets many bookable items draw from one pooled resource.

Carriers

• Carriers are typed resources with a capacity and tags (e.g., a service technician, a staff member, an asset).
• Carriers are grouped into carrier types; a bookable item declares the carrier type(s) it requires (a pipe-encoded type:stock map).
• Date-partitioned carrier stock (per-date carrier tables) mirroring the dated inventory model.
• Each booking is linked to the specific carrier(s) it consumed (a party-to-carrier link table) for scheduling and reconciliation.
• Carriers map to external service-provider resources (e.g., a technician in an external spa/reservation system).

Shared Inventory

Description: A single carrier(-type) pool is shared across multiple items, and across venues, so consuming capacity through one item decrements the availability of every item backed by that pool.

Mechanisms

• One carrier type → many master items (a many-to-many resource-to-item map).
• Carrier types can span venues, enabling shared capacity across locations.
• Availability for an item is constrained by the intersection of its own stock and the shared carrier-pool capacity.
• Shared carrier stock is decremented as any backed item sells, guarding against over-allocation of a shared resource.

Holds

Description: Engineered a hold-based booking lifecycle that protects capacity against race conditions between selection and payment.

Lifecycle

• Create hold → add items → create payment intent → charge → finalize booking → release hold.
• Holds carry an expiry timestamp; cron jobs release abandoned capacity.
• Active holds decrement available stock (recomputed from bookings + holds) to guard against overbooking; a checksum revalidation gate catches stale/oversold carts before payment.

Integrity

• Every cart item carries an engine-generated checksum revalidated before payment.
• Checksum mismatch soft-deletes the stale item and can trigger a full cart recreation.

Publishing

Description: Built the pipeline that compiles authored catalog data into live, priced availability.

Phases

Reload: Read templates / master items / categories → write the per-date tables.

Breakdown Compilation: Run the pricing + breakdown engine → write availability rows with precomputed breakdown and channel JSON.

Stock Calculation: Recompute available stock from current bookings and active holds.

Seating Map

Description: Built a visual floor-plan / seating-map engine where drawn locations back bookable inventory, so operators sell and manage a room from its map.

Capabilities

• A floor-plan/layout designer with sections and positioned locations (SVG geometry + shape types).
• Mapped locations bound to bookable inventory items, so a map position is a sellable/holdable unit.
• Per-map inventory + availability resolution (a location's state reflects its item's stock/holds/bookings).
• Real-time table/location state on the map (occupied / held / available), driven by the live-ops socket layer.

Cross Reference

You can view the raw source.