Six Core Entities

Overview

The six core entities form the Entity Layer of the wiki/concepts/four-layer-architecture. They represent the fundamental data objects in the wiki/entities/b2bpaper marketplace. All matching, notification, and container assembly logic operates on these entities.

Entity Definitions

1. Products

The master catalog of paper product types. This is reference data that rarely changes.

Key fields: type, GSM range, standard widths, primary use, characteristics

Role: Products provide the taxonomy against which surplus and buyer specs are classified. Without a clean product catalog, matching cannot work.

2. Surplus Availability

Current mill surplus inventory. This is the highest-frequency entity -- new surplus arrives daily as mills email their Excel spreadsheets.

Key fields: mill (FK), paper type, GSM, width, diameter, quantity, grade, price, currency, incoterm, available_from, location

Relationships: Many-to-one with Mills (a mill has many surplus items)

Role: This is the supply side of the marketplace. The wiki/concepts/zero-friction-mill-pattern feeds this entity via AI-parsed Excel data.

3. Mills

Paper manufacturing facilities that produce surplus inventory.

Key fields: name, location, country, product types, capacity, contact info, onboarding status

Relationships: One-to-many with Surplus Availability, one-to-many with Mills Surplus Visibility

Role: Mills are the suppliers. Their onboarding status tracks whether they are actively submitting surplus data.

4. Mills Surplus Visibility

Geographic visibility configuration per mill. This controls which regions can see a mill's surplus inventory.

Key fields: mill (FK), visible regions (Europe, Americas, Asia, etc.)

Important distinction: Visibility is per-region, NOT per-buyer. All buyers in a visible region can see the surplus. This is a deliberate design choice for simplicity and because mills think in terms of markets (regions), not individual buyers.

Business logic: Some mills only want to sell surplus in certain markets, either for price differentiation or market protection reasons.

5. Buyers

Purchasing companies that want to buy paper surplus.

Key fields: name, location, country, company type (converter, trader, end-user), volume needs

Relationships: One-to-many with Buyer Specifics

Role: Buyers are the demand side. Their profiles determine what notifications they receive.

6. Buyer Specifics

Detailed buyer requirements and purchase preferences. This is the specification against which surplus is matched.

Key fields: paper types, GSM ranges, width ranges, quality grades, volume ranges, preferred incoterms, delivery locations

Relationships: Many-to-one with Buyers (a buyer can have multiple spec sets)

Role: This is the matching target. The matching algorithm compares Surplus Availability fields against Buyer Specifics fields to generate relevance scores.

Entity Relationships

Products (reference)
    ↓ classifies
Surplus Availability ← belongs to → Mills
    ↓                                   ↓
    ↓ matched against              Mills Surplus Visibility
    ↓                              (regional controls)
Buyer Specifics ← belongs to → Buyers

Matching Flow

The core matching operation joins Surplus Availability with Buyer Specifics:

1. New surplus arrives (parsed from Excel)
2. System checks Mills Surplus Visibility to determine visible regions
3. System queries Buyer Specifics for buyers in visible regions
4. Spec-based matching: paper type, GSM (with tolerance), width (with tolerance), grade, geography
5. Each match gets a relevance score
6. Matches above threshold trigger notifications or exclusivity windows

Sources

• raw/notes/systemPatterns -- entity definitions, field lists, and relationships

Related

• wiki/concepts/four-layer-architecture -- these entities form the Entity Layer
• wiki/concepts/eight-core-actions -- actions that operate on these entities
• wiki/concepts/service-layer-pattern -- how business logic on entities is organized
• wiki/concepts/zero-friction-mill-pattern -- how Surplus Availability gets populated
• wiki/entities/b2bpaper -- the platform these entities power
• wiki/summaries/systempatterns-summary -- full system patterns summary