# Logistics & Distribution Architecture

## Purpose

This folder contains the static **Logistics & Distribution Architecture** for **HAV Seafood**, the fictional Faroese seafood manufacturer used in the synthetic business dataset.

The files define how HAV Seafood's outbound logistics and physical distribution are structurally designed: customer ship-to locations, carriers, transport services, outbound lanes, fulfilment rules, finished-goods dispatch, shipment lifecycle, delivery service, proof-of-delivery requirements, logistics exceptions, returns, processes, authority, controls and service metrics.

The architecture belongs to **Phase 1 — Business Architecture** of the project:

**1. Business architecture -> 2. Stories -> 3. Operational dataset**

It describes **what exists and how Logistics & Distribution are designed**. It intentionally does **not** contain operational or historical logistics activity such as shipments, transport bookings, pick events, pallet records, dispatches, deliveries, tracking events, proof-of-delivery records, delays, returns, freight invoices, carrier performance or logistics KPI history.

---

## Core architecture principles

The Logistics & Distribution Architecture follows these rules:

- Shared Enterprise customer-party, external-organization, country, market, enterprise-system and identifier structures are reused rather than redefined.
- Sales & Commercial remains authoritative for customer accounts, Customer + SKU commercial listings, sales orders, promised-date rules, allocation priority, partial-fulfilment permissions, split-shipment permissions and commercial freight terms.
- Production remains authoritative for SKU identity, technical product characteristics, shelf life, packaging technical masters, finished-goods storage locations and dispatch-staging locations.
- Quality remains authoritative for product release, technical quality decisions, food-safety assessment, technical return disposition and product-integrity concerns.
- HR remains authoritative for employees, roles, positions, position seats and incumbency.
- Logistics owns ship-to logistics extensions, outbound lanes, carrier/service applicability, physical fulfilment rules, shipment execution architecture, delivery-service rules, logistics exceptions, reverse-logistics flow and Logistics process/control architecture.
- Procurement & Supply Chain continues to own supplier inbound lanes, inbound transport and receiving. Outbound Logistics does not duplicate inbound architecture.
- Finance remains authoritative for freight accounting, carrier invoices, credit notes, financial claims, commercial compensation accounting and monetary settlement.
- Static rules and object definitions are separated from actual operational events.
- A Sales Order is separate from a Shipment.
- A Shipment is separate from a Transport Booking, Dispatch and Delivery.
- Derived reference workbooks never override authoritative source workbooks.
- No deliberate Phase 2 business-story anomalies are seeded during Phase 1.

---

## Architecture scope at a glance

The current Logistics & Distribution architecture includes:

- **4 customer ship-to locations**;
- **2 existing logistics/carrier partners**;
- **5 transport service classes**;
- **12 temperature-specific outbound lanes**;
- **24 Lane + Carrier eligibility relationships**;
- **10 reusable delivery/document requirements**;
- **24 active Production SKUs** connected to fulfilment architecture;
- **73 Customer + SKU logistics relationships** aligned to the existing Sales listings;
- **5 fulfilment profiles**;
- **12 storage-to-dispatch mappings**;
- **11 inventory-eligibility rules**;
- **6 shelf-life rules**;
- **5 picking rules**;
- **4 handling-unit types**;
- **15 dispatch-readiness requirements**;
- **12 future shipment/transport/delivery object definitions**;
- **12 shipment lifecycle statuses**;
- **20 permitted shipment-status transitions**;
- **20 Logistics exception types**;
- **9 return-handling rules**;
- **22 Logistics processes**;
- **110 static process steps**;
- **6 Logistics authority classes**;
- **24 consolidated Logistics controls**;
- **8 segregation-of-duties controls**;
- **5 escalation classes**;
- **10 service-metric definitions**;
- a complete derived Logistics & Distribution reference layer for AI navigation and cross-domain joining.

These values describe the current static synthetic architecture, not historical Logistics activity.

---

## Files in this folder

### `hav_seafood_logistics_distribution_network_carrier_framework_v1.xlsx`

Defines the authoritative **Distribution Network & Carrier Framework**.

Contains:

- customer ship-to logistics extensions;
- carrier/logistics-partner extensions of Shared Enterprise external organizations;
- transport service classes;
- carrier-to-service capability relationships;
- 12 outbound transport lanes;
- 24 Lane + Carrier eligibility relationships;
- delivery/document requirement structures;
- Customer + SKU logistics applicability;
- position responsibilities;
- system/data mappings;
- source precedence;
- architecture notes and data dictionary.

The principal relationship is:

`Customer -> Ship-To Location -> Outbound Lane -> Carrier -> Transport Service`

A product-centric view is:

`Customer + SKU -> Ship-To -> Storage Regime -> Outbound Lane -> Eligible Carrier / Service`

Shared Enterprise remains authoritative for external-organization identity. Sales remains authoritative for the customer and Customer + SKU commercial relationship. Production remains authoritative for the SKU.

This workbook does **not** contain transport bookings, shipments, tracking records, freight prices, carrier invoices, delivery events or carrier-performance history.

Companion reference:

`hav_seafood_logistics_distribution_network_carrier_framework_v1.md`

---

### `hav_seafood_logistics_outbound_fulfilment_dispatch_framework_v1.xlsx`

Defines the authoritative **Outbound Fulfilment & Dispatch Framework**.

Contains:

- 5 reusable fulfilment profiles;
- logistics reference for all 24 active Production SKUs;
- finished-goods storage-to-dispatch-staging mappings;
- inventory-eligibility rules;
- stock-rotation and allocation rules;
- shelf-life rules;
- picking rules;
- handling-unit definitions;
- pallet/loading rules;
- order-consolidation rules;
- 73 Customer + SKU fulfilment relationships;
- dispatch-readiness requirements;
- dispatch-document requirements;
- position responsibilities;
- system/data mappings;
- source precedence;
- architecture notes and data dictionary.

The core model is:

`Confirmed Sales Order`

`-> Eligible Released Inventory`

`-> Allocation / Rotation Rule`

`-> Pick`

`-> Handling Unit / Pallet Build`

`-> Dispatch Staging`

`-> Consolidation`

`-> Dispatch Readiness`

Production-owned finished-goods storage and dispatch-staging locations are reused rather than redefined.

Sales remains authoritative for commercial permissions such as partial fulfilment, split shipment and allocation priority. Logistics owns the physical fulfilment logic.

This workbook does **not** contain inventory balances, reservations, picks, handling-unit IDs, pallet records, staging events, loading events, dispatches or shortages.

Companion reference:

`hav_seafood_logistics_outbound_fulfilment_dispatch_framework_v1.md`

---

### `hav_seafood_logistics_process_service_control_framework_v1.xlsx`

Defines the authoritative **Logistics Process, Service & Control Framework**.

Contains:

- future shipment, transport, delivery, exception and return object definitions;
- 12 shipment lifecycle statuses;
- 20 permitted status transitions;
- transport-booking rules;
- delivery-service classes;
- delivery-completion rules;
- proof-of-delivery rules;
- 20 Logistics exception types;
- exception-severity structures;
- exception-routing rules;
- return-reason structures;
- 9 return-handling rules;
- 22 Logistics processes;
- 110 static process steps;
- 6 authority classes;
- position-to-authority mappings;
- process-authority rules;
- 24 Logistics controls;
- 8 segregation-of-duties controls;
- 5 escalation classes;
- 10 Logistics service-metric definitions;
- system/process mappings;
- cross-domain interfaces;
- source precedence;
- architecture notes and data dictionary.

The main lifecycle is:

`Dispatch-Ready Fulfilment`

`-> Shipment`

`-> Transport Booking`

`-> Loading / Dispatch`

`-> In Transit`

`-> Delivery`

`-> Proof of Delivery`

`-> Closure`

with alternative paths:

`Shipment / Delivery -> Exception -> Resolution / Escalation`

and:

`Delivered Product -> Return Authorization -> Physical Return -> Quality / Commercial Disposition`

Important conceptual boundaries include:

`Sales Order != Shipment`

`Shipment != Transport Booking`

`Shipment != Dispatch`

`Dispatch != Delivery`

`Delivery != Proof of Delivery`

`Exception Type != Exception Case`

`Return Reason != Root Cause`

`Physical Return != Quality Disposition`

`Metric Definition != Metric Result`

This workbook contains no actual shipment, exception, return, approval, control-execution or KPI records.

Companion reference:

`hav_seafood_logistics_process_service_control_framework_v1.md`

---

### `hav_seafood_logistics_distribution_reference_tables_v1.xlsx`

Provides the **derived, AI-friendly navigation and joining layer** across the complete Logistics & Distribution architecture.

Contains compact reference views for:

- ship-to locations;
- carrier/service capabilities;
- outbound lanes;
- lane/carrier relationships;
- all 73 Customer + SKU logistics relationships;
- all 24 active SKUs in Logistics context;
- fulfilment and dispatch rules;
- dispatch-readiness requirements;
- shipment/service architecture;
- Logistics exceptions and returns;
- Logistics processes and controls;
- responsibility and authority;
- service-metric definitions;
- systems and data ownership;
- relationship catalog;
- architecture sources and data dictionary.

The `Customer_SKU_Logistics_Ref` sheet is the main cross-functional navigation view. It connects the commercial Customer + SKU relationship to ship-to, lane, service, carrier eligibility, fulfilment profile, storage regime, picking structure, staging location and dispatch-readiness architecture.

This workbook is **derived and non-authoritative**.

If it conflicts with an authoritative Logistics, Sales, Production, Quality, HR or Shared Enterprise source, the authoritative source wins.

This workbook should normally be the **first Excel workbook inspected when fast AI context or cross-Logistics navigation is needed**.

Companion reference:

`hav_seafood_logistics_distribution_reference_tables_v1.md`

---

## How the Logistics & Distribution architecture fits together

At a high level:

`Shared Enterprise External Organization`

`-> Sales Customer`

`-> Logistics Ship-To`

`-> Outbound Lane`

`-> Carrier + Transport Service`

Then:

`Sales Order`

`+ Production Released Finished Goods`

`-> Fulfilment Rules`

`-> Pick / Handling Unit`

`-> Dispatch Staging`

`-> Dispatch Readiness`

Then:

`Dispatch-Ready Fulfilment`

`-> Shipment`

`-> Transport Booking`

`-> Dispatch`

`-> Delivery`

`-> Proof of Delivery / Exception / Return`

Finally:

`All Logistics domains -> Logistics Distribution Reference Tables`

A customer/product-centric view is:

`Customer + SKU`

`-> Commercial Listing`

`-> Ship-To`

`-> Outbound Lane`

`-> Carrier / Service Eligibility`

`-> Fulfilment Profile`

`-> Storage / Picking / Handling`

`-> Dispatch Readiness`

`-> Future Shipment / Delivery`

---

## Relationship with Shared Enterprise Architecture

Shared Enterprise remains the common enterprise backbone around Logistics.

Logistics reuses Shared Enterprise structures including:

- company identity;
- external organizations;
- countries;
- markets/regions;
- enterprise locations where applicable;
- enterprise systems;
- identifier conventions;
- shared classifications;
- entity ownership rules;
- system/data ownership rules.

Carrier identity is anchored to the Shared Enterprise external-organization model and then extended with Logistics-specific capability and service attributes.

Logistics does not create a competing external-party master.

---

## Relationship with Sales & Commercial Architecture

Sales & Commercial remains authoritative for:

- customer accounts;
- customer commercial organization;
- Customer + SKU listings;
- customer product codes;
- sales orders;
- requested/promised-date rules;
- commercial allocation priority;
- partial-fulfilment permission;
- split-shipment permission;
- commercial freight terms;
- customer agreements;
- customer-service handling.

Logistics owns the physical distribution layer after the commercial requirement exists.

The principal handoff is:

`Confirmed Sales Order -> Logistics Fulfilment / Shipment`

A Sales Order must never be treated as a Shipment.

Logistics delivery or exception status may later feed customer-service activity, but Sales remains authoritative for the customer-facing commercial relationship.

---

## Relationship with Production Architecture

Production remains authoritative for:

- SKU identity;
- technical product characteristics;
- packaging technical masters;
- shelf life;
- storage requirements;
- finished-goods storage locations;
- QA-hold locations;
- dispatch-staging locations;
- technical production and storage rules.

Logistics references these structures rather than redefining them.

Important bridges include:

`Production SKU -> Logistics Fulfilment Profile`

`Production Finished-Goods Storage -> Logistics Dispatch Staging`

`Released Finished Goods -> Logistics Eligibility`

`Production Packaging Master -> Logistics Handling / Pallet Rules`

---

## Relationship with Quality & Food Safety

Quality remains authoritative for technical quality and food-safety decisions.

Logistics may detect, route or physically control issues such as:

- temperature concerns;
- transport damage;
- product-integrity concerns;
- returned products;
- documentation concerns affecting release.

But Logistics does not independently decide whether affected food is safe, releasable, saleable or suitable for disposition.

Important relationships include:

`Quality Release -> Logistics Dispatch Eligibility`

`Logistics Product-Integrity Exception -> Quality Assessment`

`Returned Product -> Controlled Storage / Quarantine -> Quality Disposition`

---

## Relationship with HR & Organization Architecture

HR remains authoritative for:

- employees;
- roles;
- positions;
- position seats;
- incumbency;
- enterprise authority backbone.

Logistics uses position-based responsibility and authority rather than storing employee-specific operational authority inside the architecture.

Actual employee activity belongs to Phase 3.

---

## Relationship with Procurement & Supply Chain Architecture

Procurement & Supply Chain owns **inbound** physical supply-chain architecture.

This includes:

- supplier inbound lanes;
- supplier transport;
- inbound logistics partners;
- receiving;
- putaway of purchased materials.

Logistics & Distribution owns **outbound finished-goods distribution**.

The boundary is therefore:

`Supplier -> HAV Seafood = Procurement / Inbound Supply Chain`

`HAV Seafood -> Customer = Logistics & Distribution`

Existing logistics partners may be reused where the same external organization legitimately provides both inbound and outbound services.

---

## Finance boundary

Logistics may generate operational evidence that later affects Finance, but it does not own financial settlement.

Finance is expected to remain authoritative for:

- carrier invoices;
- freight-cost accounting;
- accruals;
- financial claims;
- credit notes;
- customer compensation accounting;
- inventory financial impact;
- monetary approvals;
- financial settlement.

A Logistics exception or carrier claim is therefore separate from the resulting accounting transaction.

---

## Systems boundary

The current architecture deliberately does **not** introduce a dedicated WMS or TMS.

The existing enterprise systems landscape is reused.

`ESYS-001 Core ERP` is the principal operational system for:

- inventory;
- warehouse pick/dispatch;
- shipment/dispatch records;
- core fulfilment execution.

Other systems may support:

- Quality evidence and technical cases;
- customer-facing CRM activity;
- controlled documentation;
- cold-chain monitoring;
- financial processing;
- reporting.

A reporting system does not become authoritative simply because it contains a copy of Logistics data.

---

## Authoritative versus derived files

The following Logistics & Distribution workbooks are authoritative for their Logistics subject areas:

- `hav_seafood_logistics_distribution_network_carrier_framework_v1.xlsx`
- `hav_seafood_logistics_outbound_fulfilment_dispatch_framework_v1.xlsx`
- `hav_seafood_logistics_process_service_control_framework_v1.xlsx`

The following workbook is deliberately **derived**:

- `hav_seafood_logistics_distribution_reference_tables_v1.xlsx`

The derived reference workbook exists to simplify navigation, joining, AI context and later dataset generation. It should be refreshed whenever an authoritative Logistics workbook materially changes and must never overrule an authoritative source.

Where the underlying fact originates outside Logistics, the upstream authoritative domain still wins.

---

## Companion Markdown files

Each Logistics workbook has a matching `.md` file containing a compact description of:

- purpose;
- principal entities and relationships;
- workbook contents;
- important architecture counts;
- ownership boundaries;
- source precedence;
- cross-domain relationships;
- assumptions;
- Phase 1 exclusions;
- recommended AI use.

These files provide fast semantic context without requiring every workbook to be opened first.

---

## Important conceptual boundaries

The architecture deliberately keeps the following concepts separate:

`Customer != Ship-To`

`Customer + SKU Listing != Logistics Applicability`

`Transport Service != Delivery Service`

`Carrier Capability != Carrier Booking`

`Outbound Lane != Shipment`

`Sales Order != Shipment`

`Inventory != Eligible Inventory`

`Eligible Inventory != Allocation`

`Allocation Rule != Allocation Event`

`Handling-Unit Type != Handling-Unit Record`

`Dispatch Readiness Rule != Dispatch-Readiness Check`

`Shipment != Transport Booking`

`Shipment != Dispatch`

`Dispatch != Delivery`

`Delivery != Proof of Delivery`

`Exception Type != Exception Case`

`Return Reason != Root Cause`

`Return Authorization != Credit Note`

`Physical Return != Quality Disposition`

`Process Rule != Process Event`

`Authority != Approval Event`

`Control Requirement != Control Execution`

`Metric Definition != Metric Result`

These distinctions should be preserved when Phase 3 operational data is generated.

---

## Architecture boundaries — operational data intentionally excluded

This folder does **not** contain historical or transactional Logistics records such as:

- shipment records;
- shipment lines;
- transport bookings;
- carrier confirmations;
- carrier capacity responses;
- pick lists;
- pick events;
- inventory allocations;
- inventory reservations;
- handling-unit records;
- pallet records;
- pallet-build events;
- staging events;
- loading events;
- dispatches;
- dispatch timestamps;
- actual shipment-status history;
- GPS or tracking events;
- collection events;
- actual transit times;
- actual delivery dates/times;
- delivery appointments;
- proof-of-delivery files;
- delivery signatures;
- actual temperature readings;
- temperature excursions;
- shipment damage;
- lost shipments;
- delivery refusals;
- quantity discrepancies;
- logistics exception cases;
- escalation cases;
- returned shipments;
- returned quantities;
- return authorizations;
- carrier claims;
- freight prices;
- freight invoices;
- freight costs;
- carrier scorecards;
- OTIF results;
- On-Time Delivery results;
- transport-performance history;
- actual approvals;
- control executions;
- control failures;
- operational emails or communications;
- customs declarations;
- actual shipping documents.

Those belong to Phase 3 after the Phase 2 stories and patterns have been deliberately designed.

---

## Story neutrality

The Logistics & Distribution architecture is intentionally designed to support future business stories without selecting them yet.

It does not deliberately seed outcomes such as:

- chronic late deliveries;
- carrier deterioration;
- repeated missed collections;
- warehouse picking errors;
- dispatch bottlenecks;
- shelf-life failures;
- inappropriate stock allocation;
- transport temperature excursions;
- shipment damage;
- delivery refusals;
- customer delivery disputes;
- incorrect ship-to usage;
- carrier-capacity problems;
- route disruptions;
- repeated returns;
- weak POD capture;
- poor OTIF;
- control bypasses;
- unauthorized carrier changes;
- segregation-of-duties failures;
- excessive freight costs.

Those patterns should be selected in **Phase 2 — Stories** and introduced deliberately when operational Logistics data is generated.

---

## Identifier conventions

Existing Shared Enterprise, Sales, Production and HR identifiers are preserved.

Logistics introduces domain-local identifiers for structures such as:

- ship-to logistics extensions;
- carrier extensions;
- transport service classes;
- outbound lanes;
- fulfilment profiles;
- logistics rules;
- handling-unit types;
- shipment statuses;
- delivery service classes;
- exception types;
- return rules;
- processes;
- authority classes;
- controls;
- escalation classes;
- metric definitions.

Future operational shipment, delivery, exception and return identifiers should follow the object model defined in the Process, Service & Control workbook rather than being improvised inside transactional files.

Where Logistics-local prefixes are not yet registered in the Shared Enterprise identifier standards, they should be registered when the enterprise standards are refreshed.

---

## Recommended use of the folder

For fast context, inspect files in this order:

1. `README_logistics_distribution_architecture.md` — overall Logistics architecture, ownership boundaries and file map.
2. `hav_seafood_logistics_distribution_reference_tables_v1.xlsx` — compact cross-Logistics joining and navigation layer.
3. The matching authoritative Logistics workbook for the subject being analyzed.
4. The relevant upstream Sales, Production, Quality, HR, Procurement or Shared Enterprise source whenever the underlying fact is owned outside Logistics.

### AI navigation shortcuts

- Customer delivery destination -> `Ship_To_Reference`.
- Which carrier/service can serve a destination? -> `Outbound_Lane_Reference` + `Lane_Carrier_Reference`.
- How is Customer X / SKU Y normally distributed? -> `Customer_SKU_Logistics_Ref`.
- SKU storage / fulfilment / staging question -> `SKU_Logistics_Reference`.
- Fulfilment and picking rules -> `Fulfilment_Dispatch_Ref`.
- What must happen before dispatch? -> `Dispatch_Requirements_Ref`.
- Shipment/service lifecycle question -> `Shipment_Service_Reference`.
- Logistics exception or return question -> `Exception_Return_Reference`.
- Logistics process/control question -> `Process_Control_Reference`.
- Who owns or approves something? -> `Responsibility_Authority`.
- Which metrics are defined? -> `Service_Metric_Reference`.
- Which system/domain owns the data? -> `System_Ownership_Bridges`.
- How entities join -> `Relationship_Catalog`.

---

## Use in later phases

### Phase 2 — Stories

This architecture provides the stable structures required to design cross-functional stories involving areas such as:

- warehouse fulfilment;
- stock allocation;
- shelf-life handling;
- picking and staging;
- shipment consolidation;
- carrier selection;
- transport booking;
- dispatch;
- late collection;
- transport delay;
- route disruption;
- temperature excursions;
- damaged shipments;
- delivery refusal;
- missing POD;
- customer delivery discrepancies;
- reverse logistics;
- returns;
- carrier performance;
- OTIF;
- Sales/Logistics coordination;
- Quality involvement in transport issues;
- Finance consequences of claims and freight;
- authority/control failures.

Stories should reference the existing IDs, profiles, lanes, rules, processes, controls and ownership structures rather than changing the architecture merely to make a pattern possible.

### Phase 3 — Operational dataset generation

Operational Logistics datasets should:

1. reuse the customer, ship-to, SKU, lane, carrier, service, fulfilment, handling, status, exception, return, process and control identifiers defined or referenced here;
2. preserve Shared Enterprise, Sales, Production, Quality and HR identifiers;
3. generate operational events according to the static rules in the authoritative Logistics workbooks;
4. preserve the distinction between Sales Order, Shipment, Transport Booking, Dispatch, Delivery, Exception and Return;
5. use the established system-of-record and ownership boundaries;
6. generate realistic ordinary activity and noise around deliberately selected Phase 2 stories;
7. avoid redefining master data inside transactional datasets;
8. create cross-functional records that join consistently with Sales, Production, Quality, Finance, HR, Procurement and Management datasets.

The eventual operational Logistics dataset can include realistic combinations of ERP exports, Excel dispatch plans, transport-booking files, carrier confirmations, shipment documents, pallet/handling-unit records, tracking exports, POD files, emails, exception logs, return records, temperature-monitoring exports and KPI reports while remaining anchored to this architecture.

---

## Overall role of this architecture

Together, these files form the **static outbound Logistics & Distribution master-data, fulfilment, execution-design, service and governance layer** for HAV Seafood.

They connect Sales customer demand and Production finished goods to ship-to locations, outbound transport lanes, carriers, fulfilment rules, picking and staging, shipment execution, delivery, exceptions, returns, controls and service metrics while preserving the ownership boundaries of Shared Enterprise, Sales, Production, Quality, HR, Procurement and Finance.

The architecture is deliberately compact. Its purpose is to ensure that later synthetic Logistics activity behaves like part of the same company, uses consistent customers, products, locations and systems, and can support cross-functional business stories without creating competing master data.
