type
concept
created
Tue Apr 07 2026 02:00:00 GMT+0200 (Central European Summer Time)
updated
Tue Apr 07 2026 02:00:00 GMT+0200 (Central European Summer Time)
sources
raw/articles/PRD
tags
visibility geographic distribution pricing mills

Geographic Visibility System

abstract
Mills control which geographic regions can see their surplus through allow/deny rules at region, country, and city scope, with per-destination price adjustments -- this is regional distribution control, not per-buyer access.

Overview

Surplus visibility is controlled at the geographic level, NOT the individual buyer level. This is a deliberate design decision reflecting how paper mills actually manage distribution. Mills think in terms of markets and regions, not individual companies. A Spanish mill might sell surplus at EUR450/MT in Iberia but EUR420/MT to North Africa. A Swedish mill might not want to sell surplus in their domestic market to avoid undercutting production prices.

From the Madrid meeting: "I'm a miller, so I don't want to sell the same product to everyone because I have a higher price in Mexico, Brazil pays less, Ecuador pays less. So they choose what they want."

Rule Structure

Each VisibilityRule has:

Scope Hierarchy

Rules are evaluated from most specific to least specific:

city > country > region

If a city-level rule matches the buyer's location, it takes precedence over country and region rules. If no city rule matches, the system checks country rules, then region rules.

The full geographic hierarchy:

GLOBAL
+-- EU (European Union)
|   +-- DE, ES, PL, CZ, SE, FI, PT, FR, IT, GR, NL, ...
+-- EUROPE_NON_EU
|   +-- GB, NO, CH, TR
+-- NORTH_AMERICA
|   +-- US, CA, MX
+-- SOUTH_AMERICA
|   +-- BR, VE, CO, PE, CL, AR, BO, EC, UY
+-- MIDDLE_EAST
|   +-- IL, AE, SA
+-- AFRICA
|   +-- MA, DZ, TN, EG, ZA
+-- ASIA
|   +-- CN, ID, IN, JP, KR
+-- OCEANIA
    +-- AU, NZ

Evaluation Logic

  1. Collect item-specific rules first, then mill-wide defaults
  2. For each rule set, check from most specific to least specific scope
  3. At each scope level: deny overrides allow (if both exist for same scope, deny wins)
  4. Item-specific rules take full precedence -- if an item-specific rule matches, mill-wide defaults are not consulted
  5. Secure by default: if no rules match the buyer's location, the surplus is NOT visible

Price Adjustment

Allow rules can carry a price adjustment that modifies the base price per MT for buyers in that geographic scope. Adjustments are additive: adjusted_price = base_price + price_adjustment_mt.

The most specific matching rule's adjustment is used. Example for a Swedish mill:

rule_type scope scope_value price_adjustment_mt Effect
allow region EU 0 Base price for EU buyers
allow country MA -30 Morocco buyers see EUR30 less per MT
allow country DZ -30 Algeria buyers see EUR30 less per MT
allow country TN -15 Tunisia buyers see EUR15 less per MT
deny country BR -- Brazil buyers cannot see this surplus at all

Real example from Mara's surplus list (Holland):

Integration Points

Visibility is checked in ALL downstream systems:

  1. Matching algorithm -- visibility check runs BEFORE scoring to avoid wasted computation (see wiki/concepts/matching-algorithm)
  2. Newsletter generation -- only visibility-passing matches appear in buyer newsletters (see wiki/concepts/newsletter-generation)
  3. Container assembly -- only visible surplus can be proposed in containers (see wiki/concepts/container-assembly)
  4. API endpoints -- buyer-facing surplus list endpoints apply VisibilityFilteredMixin to QuerySets
  5. Price display -- adjusted prices are shown based on buyer's geographic location

Default Rules and Overrides

Sources

Related