# =============================================================================
# COMPETENCY RECORD - Cedric Ancellin's demonstrated engineering skills and
# experience. Third-party technologies and vendors are named as the concrete
# skill surface. Professional background / track record.
# =============================================================================

# ============================================================
# COMMERCE & INVENTORY ENGINE - COMPETENCY RECORD
# ============================================================
# Core Purpose:
#   Demonstrated experience designing a real-time commerce and
#   inventory engine: date-partitioned availability, dynamic
#   tier-yielded pricing, a multi-layer price-breakdown engine,
#   channel-aware distribution, inventory holds, and a
#   publishing pipeline.
# ============================================================

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.


# ==================================================================
# 1. DATE-PARTITIONED INVENTORY MODEL
# ==================================================================

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."


# ==================================================================
# 2. DYNAMIC TIER-YIELDED PRICING
# ==================================================================

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)."


# ==================================================================
# 3. MULTI-LAYER PRICE-BREAKDOWN ENGINE
# ==================================================================

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).


# ==================================================================
# 4. CHANNEL-AWARE DISTRIBUTION
# ==================================================================

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."


# ==================================================================
# 5. CARRIERS & SHARED / POOLED INVENTORY
# ==================================================================

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."


# ==================================================================
# 6. INVENTORY HOLDS & BOOKING LIFECYCLE
# ==================================================================

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."


# ==================================================================
# 7. PUBLISHING PIPELINE
# ==================================================================

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."


# ==================================================================
# 8. VISUAL SEATING-MAP / FLOOR-PLAN ENGINE
# ==================================================================

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:
    $ref: "https://zc8.com/competencies/17_realtime_notifications"