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/notes/systemPatterns
tags
architecture layers data-bootstrap entity action output

Four-Layer Architecture

abstract
The system is organized into four layers -- Data Bootstrap, Entity, Action, and Output -- where data flows upward from ingestion through entities and business logic to user-facing outputs.

Overview

The Four-Layer Architecture is the structural backbone of the wiki/entities/b2bpaper platform. It was defined in the V1 System Diagram and organizes all system functionality into four distinct layers with clear responsibilities and data flow direction.

The Layers

Layer 1: Data Bootstrap Layer (Bottom)

Purpose: Get data into the system.

This layer handles the messy reality of paper surplus data: varying Excel formats, different languages, inconsistent column names. The wiki/concepts/zero-friction-mill-pattern lives here -- mills email spreadsheets, and this layer transforms them into structured data.

Layer 2: Entity Layer

Purpose: Store and manage structured data.

The six core entities live here (see wiki/concepts/six-core-entities):

Entity Role
Products Master catalog of paper product types
Surplus Availability Current mill surplus inventory
Mills Paper manufacturing facilities
Mills Surplus Visibility Geographic visibility configuration
Buyers Purchasing companies
Buyer Specifics Detailed buyer requirements

These are the Django models, the database tables, the serializers. Clean, structured, validated data.

Layer 3: Action Layer

Purpose: Execute business logic on entity data.

The eight core actions live here (see wiki/concepts/eight-core-actions):

Business logic is organized via the wiki/concepts/service-layer-pattern -- pure functions in services.py files, called by views, testable without HTTP context.

Layer 4: Output Layer (Top)

Purpose: Deliver results to users.

This is what users actually see and interact with. Everything below it is plumbing.

Data Flow

Data flows upward through the layers:

Mill emails Excel
    ↓
[Data Bootstrap] parses and structures
    ↓
[Entity Layer] stores as Surplus, linked to Mill
    ↓
[Action Layer] matches to Buyer Specifics, assembles containers
    ↓
[Output Layer] sends newsletter to matched Buyers

Each layer depends only on the layer below it. The Output Layer never directly touches the Data Bootstrap Layer.

Sources

Related