type
summary
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/notes/systemPatterns
tags
architecture patterns entities actions service-layer matching

System Patterns Summary

abstract
The system follows a four-layer architecture (Data Bootstrap, Entity, Action, Output) with six core entities, eight core actions, and key design patterns including spec-based matching, geographic visibility, 48-hour exclusivity, and a pure-function service layer.

Four-Layer Architecture

The system is organized into four layers, from bottom to top:

  1. Data Bootstrap Layer -- initial data collection, onboarding, Excel import, email ingestion
  2. Entity Layer -- the six core data entities (Products, Surplus, Mills, Visibility, Buyers, BuyerSpecs)
  3. Action Layer -- matching, container assembly, exclusivity, newsletter generation, Excel ingestion, visibility config
  4. Output Layer -- newsletters, container proposals, reports, notifications

See wiki/concepts/four-layer-architecture for the full breakdown.

Six Core Entities

The data model is built on six interrelated entities:

Entity Purpose Update Frequency
Products Master catalog of paper product types Rarely changes
Surplus Availability Current mill surplus inventory Daily (high frequency)
Mills Paper manufacturing facilities Stable
Mills Surplus Visibility Geographic visibility config per mill Configured once, updated occasionally
Buyers Purchasing companies Stable
Buyer Specifics Detailed buyer requirements/preferences Updated as needs change

See wiki/concepts/six-core-entities for detailed field definitions and relationships.

Eight Core Actions

  1. Extract Buyers -- onboard and profile buyer companies
  2. Extract Suppliers -- onboard and profile mill suppliers
  3. Exclusivity -- 48-hour exclusive windows for matched buyers
  4. Pre-Production -- track surplus available before production completes
  5. Newsletter -- automated newsletter generation for matched buyers
  6. Container Assembly -- optimize container loading from multiple surplus lots
  7. Excel Ingestion -- AI-powered parsing of mill Excel spreadsheets
  8. Visibility Config -- configure geographic visibility rules

See wiki/concepts/eight-core-actions for full details on each action.

Key Design Patterns

Spec-Based Matching

All matching is on technical specifications (paper type, GSM, width, grade, geography), not free text. Each match receives a relevance score, and only matches above a minimum threshold are surfaced.

Geographic Visibility

Visibility is controlled at the regional level (Europe, Americas, Asia, etc.), NOT per-buyer. A mill chooses which regions can see its surplus, and all buyers in a visible region can see it.

48-Hour Exclusivity

When a high-relevance match is found, the buyer gets 48 hours of exclusive access. During that window, the surplus is hidden from other buyers. After expiry, it becomes visible to all matched buyers. Only one active exclusivity per surplus item at a time.

Service Layer Pattern

Business logic lives in apps/<app>/services.py as pure functions -- stateless and testable without HTTP context. Views call services, never the reverse. First implemented in containers/services.py with four core functions for fill optimization. See wiki/concepts/service-layer-pattern for details.

Zero-Friction Mill Pattern

Mills do not change their workflow. They email Excel files as they always have. AI handles all parsing and structuring. No dashboard login required from mills. See wiki/concepts/zero-friction-mill-pattern.

Sources

Related