Eight Core Actions

Overview

The eight core actions form the Action Layer of the wiki/concepts/four-layer-architecture. They operate on the wiki/concepts/six-core-entities and produce outputs (newsletters, proposals, notifications). Business logic for these actions is organized via the wiki/concepts/service-layer-pattern.

The Eight Actions

1. Extract Buyers

Purpose: Onboard and profile buyer companies.

• Collect buyer specifications and purchase preferences
• Populate Buyers and Buyer Specifics entities
• Sources: manual entry + automated extraction from inquiry emails
• This action feeds the demand side of matching

2. Extract Suppliers (Mills)

Purpose: Onboard and profile mill suppliers.

• Map product capabilities and typical surplus patterns
• Populate Mills entity with onboarding status
• Sources: manual entry + automated extraction from historical data
• Follows the wiki/concepts/zero-friction-mill-pattern -- minimal friction for mills

3. Exclusivity

Purpose: Manage 48-hour exclusive access windows for matched buyers.

• Triggered when a high-relevance match is found between surplus and buyer specs
• Buyer gets 48 hours of exclusive first-right-of-refusal
• During exclusivity window: surplus is hidden from other buyers
• Auto-expires after 48 hours if no response
• Only one active exclusivity per surplus item at a time
• Requires reliable Celery scheduling for timer management

4. Pre-Production

Purpose: Track surplus that will be available before production completes.

• Mills can list planned overruns and trial runs
• Enables early matching before surplus physically exists
• Gives buyers advance notice of upcoming availability
• Useful for planning and forward booking

5. Newsletter

Purpose: Generate and send automated newsletters to matched buyers.

• Contains matched surplus items with specs, pricing, and availability
• Frequency: weekly or on-demand when high-relevance matches are found
• HTML email format with structured data presentation
• Must respect the wiki/concepts/three-pillars Trust pillar -- curated, not spam

6. Container Assembly

Purpose: Optimize container loading from multiple surplus lots.

• Combine partial rolls from different lots into full containers
• Respect weight limits: 20ft (18-22MT), 40ft (24-26MT), 40ft HC (24-28MT)
• Consider roll dimensions, stacking, and dunnage requirements
• Implementation status: This is the most mature action, with a full service layer in apps/containers/services.py
• Scoring system: 0-100 based on paper type match (+20), GSM closeness (+15), price advantage (+15)
• Product compatibility checks: paper group, grade proximity (<=1), food contact
• Freight rate comparison: LCL vs FCL with fallback to hardcoded rates

7. Excel Ingestion

Purpose: Parse mill Excel surplus spreadsheets into structured data.

• AI-powered extraction handling varying formats per mill
• Must handle: different column names, units, formats, and languages
• Maps raw spreadsheet data to the Surplus Availability entity
• Core enabler of the wiki/concepts/zero-friction-mill-pattern
• Technology: openpyxl or pandas for parsing, AI for field mapping

8. Visibility Config

Purpose: Configure geographic visibility rules for mill surplus.

• Regional controls (not per-buyer): Europe, North America, South America, Asia, Middle East, Africa
• Business logic: market protection and price differentiation by region
• Managed by wiki/entities/morichal-trading admin team
• Affects which buyers see which surplus in the matching pipeline

Action Dependencies

Some actions depend on others:

• Matching (implicit in Newsletter + Exclusivity) depends on Extract Buyers + Extract Suppliers + Visibility Config
• Newsletter depends on matching results
• Exclusivity depends on matching results
• Container Assembly depends on matched surplus items
• Excel Ingestion feeds Surplus Availability, which triggers matching

Sources

• raw/notes/systemPatterns -- full action specifications with business logic details

Related

• wiki/concepts/four-layer-architecture -- these actions form the Action Layer
• wiki/concepts/six-core-entities -- the entities these actions operate on
• wiki/concepts/service-layer-pattern -- how action logic is implemented in code
• wiki/concepts/three-pillars -- the framework each action must respect
• wiki/concepts/zero-friction-mill-pattern -- the philosophy behind Extract Suppliers and Excel Ingestion
• wiki/summaries/systempatterns-summary -- full system patterns summary