# HAV Seafood Business Architecture

This folder is the static business architecture for HAV Seafood, a fictional Faroese seafood manufacturer. It is the common source of truth used to design later business stories and operational datasets.

The project follows this sequence:

`Business architecture → Stories → Operational dataset`

Everything under this folder is Phase 1 architecture. It describes what exists, how the company is organized, which master data is authoritative, and how domains relate to one another. It does not contain operational history, transactions, event logs, or deliberate business-story anomalies.

## What the architecture contains

The architecture covers nine connected domains:

| Domain | Main subject matter |
|---|---|
| Shared Enterprise | Company identity, organization, employees, roles, positions, locations, systems, external parties, items, classifications, identifiers, ownership, and cross-domain relationships |
| Production | Factory structure, people, equipment, work centers, products, SKUs, materials, recipes, BOMs, routings, process steps, yields, capacity, shifts, storage, quality, cleaning, and maintenance requirements |
| HR & Organization | Employment, workforce establishment, positions and seats, contracts, compensation, working time, leave, competencies, training, performance, recruitment, policies, employee relations, and HR authority |
| Procurement & Supply Chain | Suppliers, procurement categories, sourcing, supplier governance, planning, inventory policy, inbound lanes, receiving, putaway, procurement processes, approvals, and controls |
| Sales & Commercial | Customers, markets, channels, territories, listings, pricing, commercial terms, agreements, demand planning, order rules, customer service, processes, authority, and controls |
| Logistics & Distribution | Ship-to locations, carriers, services, outbound lanes, fulfilment, dispatch, shipment and delivery design, POD, exceptions, returns, processes, authority, controls, and service metrics |
| Finance & Administration | Accounting dimensions, GL accounts, tax, currencies, financial documents, customer credit, billing, receivables, supplier payables, treasury, fixed assets, costing, budgets, reporting, administration, and internal control |
| IT & Systems | Enterprise applications, integrations, data objects, identity and access, security, infrastructure, endpoints, networks, continuity, services, changes, incidents, controls, and technical ownership |
| Marketing & Brand | Brand identity, positioning, audiences, claims, evidence requirements, messages, channels, content and asset types, lifecycle, governance, and approval rules |

Most domain workbooks have an accompanying Markdown reference file. The Markdown explains purpose, ownership, scope, intended joins, and excluded operational data; the workbook contains the structured architecture tables.

## Enterprise source-of-truth model

Shared Enterprise provides the identity spine. Domain workbooks extend those identities with domain-specific attributes and rules.

| Entity | Authoritative architecture | Domain extensions |
|---|---|---|
| Company, departments, organizational units, positions, locations | Shared Enterprise | HR, Production, Finance, IT, Logistics and other domain mappings |
| Employee identity, roles, position seats, incumbency | Shared Enterprise / HR | Production skills, shifts and operational staffing; domain responsibility references |
| External organizations and party roles | Shared Enterprise | Customers in Sales; suppliers and logistics partners in Procurement; carriers in Logistics |
| Products, product families, variants, SKUs and production items | Production | Enterprise item identity and classifications in Shared Enterprise; commercial, marketing, logistics and finance extensions |
| Raw materials, ingredients and packaging specifications | Production | Procurement sourcing and planning; inventory, costing, receiving and quality extensions |
| Production lines, work centers, factory areas, equipment and storage | Production | Enterprise location mappings, IT asset links, logistics and finance asset links |
| Systems, integrations and data objects | Shared Enterprise / IT | Domain process, data-use and system mappings |
| Customers and commercial relationships | Sales & Commercial | Shared external-organization identity, Finance credit/billing, Logistics ship-to, Marketing audience relationships |
| Suppliers and source relationships | Shared Enterprise / Procurement | Production technical requirements, Quality evidence, Finance payables, Supply Chain planning and inbound receiving |
| Financial dimensions and accounting structures | Finance & Administration | Shared organizational references; domain-specific cost, revenue, inventory and asset mappings |
| Brand, claims and marketing communication | Marketing & Brand | Production, Procurement, Quality and Sales provide the facts, evidence and product/customer context |

The same ID appearing in a bridge or reference table is not automatically a duplicate. Derived and domain-extension tables must not override the authoritative master. When a conflict exists, the documented authoritative source wins.

## Shared identifiers and common relationships

The identifier standards workbook defines stable cross-domain conventions. Important identifier families include:

- `EMP-*` employees;
- `DEPT-*` departments and `OU-*` organizational units;
- `POS-*` positions and `PSEAT-*` position seats;
- `R*` enterprise job roles;
- `LOC-*`, `FA-*`, `SL-*` enterprise, factory-area and storage locations;
- `ESYS-*` enterprise systems and `SINT-*` integrations;
- `ORG-EXT-*` external organizations and party identities;
- `SKU-*` / production SKU identifiers, `PF-*` product families, `VAR-*` variants;
- `RM-*`, `ING-*`, `PKG-*`, `INT-*` production materials and intermediates;
- `LINE-*`, `WC-*`, `EQ-*` production lines, work centers and equipment;
- `CUS-*` Sales customer accounts;
- `PCAT-*` procurement categories and `SRC-*` sourcing relationships;
- domain-specific prefixes for finance, logistics, marketing, controls, processes and reference objects.

The shared cross-domain relationship workbook and derived reference workbooks provide navigation paths such as:

`Employee → Department → Position → Manager → Location`

`Supplier / Customer / Carrier → External Organization → Party Role → Country / Address`

`Product Family → Variant → SKU → BOM / Routing → Work Center → Equipment / People`

`Business Process → System → Data Object → Owner → Department / Role`

## Domain overviews

### 1. Shared Enterprise

Shared Enterprise is the architectural backbone. Its workbooks define the company and organization structure, employee identity and organizational assignments, enterprise job roles and job families, enterprise locations, external-party identity, enterprise item identity, systems landscape, classifications, identifier standards, entity ownership, data ownership, and cross-domain relationship tables.

The current architecture documents a company headcount of 92 employees, 13 enterprise systems, 11 enterprise locations, 24 active retail SKUs, 25 external organizations, and the common organizational, item and reference-data layers used by other domains.

Start with `README_shared_enterprise_architecture.md`, then use:

- `hav_seafood_company_organization_structure_v1.xlsx`;
- `hav_seafood_employee_identity_organizational_reference_v1.xlsx`;
- `hav_seafood_enterprise_job_roles_job_families_v1.xlsx`;
- `hav_seafood_enterprise_locations_v1.xlsx`;
- `hav_seafood_external_party_organization_identity_model_v1.xlsx`;
- `hav_seafood_enterprise_item_identity_model_v1.xlsx`;
- `hav_seafood_enterprise_systems_landscape_v1.xlsx`;
- `hav_seafood_enterprise_identifier_standards_v1.xlsx`;
- `hav_seafood_enterprise_entity_ownership_matrix_v1.xlsx`;
- `hav_seafood_system_data_ownership_model_v1.xlsx`;
- `hav_seafood_cross_domain_relationship_tables_v1.xlsx`;
- `hav_seafood_shared_enterprise_reference_v1.xlsx`.

### 2. Production

Production defines the physical and technical manufacturing model. It connects people and factory areas to lines, work centers and equipment; connects raw materials, ingredients and packaging to recipes and BOMs; and connects products to routings, process steps, yields, storage, capacity, shifts, quality, cleaning and maintenance requirements.

The core production chain is:

`Materials + Packaging → Recipes / BOMs → Products / SKUs → Routings → Process Steps → Yields`

Capacity and staffing connect work centers, equipment, production people and shifts. Production remains authoritative for technical product and material facts, production structure, and production-specific workforce attributes.

Start with `README_production.md`. The principal workbooks are `seafood_products_skus_v1.xlsx`, `seafood_raw_materials_v1.xlsx`, `seafood_ingredients_v1.xlsx`, `seafood_packaging_materials_v1.xlsx`, `seafood_recipes_bom_v1.xlsx`, `seafood_production_routings_v1.xlsx`, `seafood_process_steps_v1.xlsx`, `seafood_production_lines_work_centers_v1.xlsx`, `seafood_machinery_equipment_v1.xlsx`, `seafood_line_capacity_staffing_v1.xlsx`, `seafood_shift_patterns_v1.xlsx`, `seafood_storage_locations_v1.xlsx`, `seafood_quality_food_safety_requirements_v1.xlsx`, `seafood_cleaning_changeover_requirements_v1.xlsx`, `seafood_maintenance_requirements_v1.xlsx`, and `seafood_production_reference_tables_v1.xlsx`.

### 3. HR & Organization

HR extends the shared employee and organizational spine with employment relationships, approved positions and workforce establishment, contract terms, compensation structures, working-time rules, leave and absence policy, competencies and training, performance and development, recruitment and onboarding, employee relations, and HR process authority.

Its structural model is:

`Job Role → Position Definition → Position Seat → Employee Incumbent`

The current reference architecture describes 92 employees, 56 enterprise job roles, 56 structural positions, 95 approved seats, 92 incumbents and 3 approved vacancies. Authority is primarily attached to roles and positions; named employees are current-state references rather than the definition of authority.

Start with `README_hr_organization_architecture.md` and the workbooks beginning `hav_seafood_hr_`.

### 4. Procurement & Supply Chain

Procurement defines who may supply which items and under what sourcing and governance conditions. Supply Chain defines how those items are planned, controlled, received and put away.

The principal relationship is:

`Supplier → Procurement Category → Item → Approved Source → Inbound Lane → Receiving Profile → Storage / Disposition`

The architecture contains 13 procurement suppliers, 25 procurement categories, 132 purchasable items, 188 approved supplier-item sourcing relationships, 8 planning profiles, 8 inventory-control profiles, 18 inbound lanes and 8 receiving profiles. Shared Enterprise owns supplier and item identity; Production owns technical material definitions; Procurement owns sourcing and supplier governance; Supply Chain owns planning, inventory policy, inbound and receiving logic.

Start with `README_procurement_supply_chain_architecture.md` and the `hav_seafood_procurement_` and `hav_seafood_supply_` workbooks.

### 5. Sales & Commercial

Sales defines the commercial customer extension and the rules for markets, channels, territories, customer assortment, product listing, pricing, terms, agreements, demand planning, orders and customer service.

Its main chain is:

`Customer → Market / Territory → Assortment / Listing → Price / Commercial Terms → Agreement → Demand / Order Rules`

The current architecture has 4 customer accounts, 9 market/region records, 2 Sales channels, 3 customer segments, 2 commercial territories, 24 active SKUs, 73 active customer-SKU listings, 4 price lists, 4 commercial-term profiles and 4 active primary agreements. Production remains authoritative for SKUs; Shared Enterprise remains authoritative for external organizations, countries, currencies, languages and systems; Finance owns credit, payment and accounting treatment; Logistics owns shipment execution.

Start with `README_sales_commercial_architecture.md` and the `hav_seafood_sales_` workbooks.

### 6. Logistics & Distribution

Logistics models how finished goods move from HAV Seafood's dispatch operation to customer delivery locations. It extends Sales customers and ship-to locations with logistics requirements, connects outbound lanes to carriers and services, and defines fulfilment, dispatch, shipment, delivery, POD, exception and return structures.

Its conceptual flow is:

`Sales Order → Shipment → Handling Unit → Transport Booking → Dispatch → Delivery → POD / Exception / Return`

Start with `README_logistics_distribution_architecture.md` and the four `hav_seafood_logistics_` workbooks. Logistics is authoritative for outbound transport, carrier, dispatch, delivery and logistics-service rules, but not for customer identity, SKU identity, financial settlement or technical product quality.

### 7. Finance & Administration

Finance provides the financial backbone and administrative control structures. It covers accounting foundations and dimensions, tax and currencies, financial documents, customer credit and receivables, supplier payables, treasury and banking, fixed assets and capital expenditure, inventory costing and manufacturing accounting, budgets and management reporting, administration and internal control.

The main financial model is:

`Business Source Object → Financial Document / Subledger → Tax / Currency → Posting Class → Ledger / Reporting Dimension`

The folder contains 10 architecture workbooks. Start with `README_finance_administration_architecture.md`, then use the accounting foundation workbook to resolve cost centers, GL accounts, dimensions and posting structures before interpreting the dependent Finance workbooks. Finance extends shared organizational and item identities; it does not replace those masters.

### 8. IT & Systems

IT defines the technology environment that supports every business domain. It covers enterprise systems and applications, integrations, system/data ownership, identity and access, security, infrastructure, endpoints, network zones, continuity, backup and recovery, services, changes, incidents, controls, authority and IT processes.

The IT boundary is explicit: operating a system does not make IT the owner of the business data stored in it. Access eligibility is separate from actual access grants; control requirements are separate from control executions; recovery targets are separate from outages and recovery events.

Start with `README_it_systems_architecture.md` and the `hav_seafood_it_` workbooks. Shared Enterprise remains authoritative for enterprise system identity and data ownership; IT owns technical architecture and technical controls; business domains own the business meanings and decisions represented in systems.

### 9. Marketing & Brand

Marketing defines HAV Seafood's brand and communication architecture: brand identity and positioning, audiences, brand pillars, claims, evidence requirements, messages, channels, content types, assets, lifecycle, review and approval governance.

The key distinctions are:

`Claim ≠ Evidence`; `Message ≠ Positioning`; `Channel ≠ Content ≠ Asset`; `Approval rule ≠ Approval event`

The current architecture contains one master brand, 24 retail SKUs, 10 governed claims, 7 message concepts, 4 message themes, 11 channels, 10 content types and 19 asset types. Faroese seafood origin is the central brand theme, but the architecture explicitly does not imply that every ingredient or packaging component is Faroese. Production, Procurement and Quality remain authoritative for the facts and evidence behind claims.

Start with `README_marketing_brand_architecture.md` and the four `hav_seafood_marketing_` workbooks.

## Cross-domain operating model

The architecture is designed for joins across domains without collapsing ownership boundaries:

1. Resolve the entity through Shared Enterprise or the explicitly authoritative domain master.
2. Use the documented identifier and datatype standards.
3. Add domain-specific attributes from the owning domain.
4. Use bridge/reference tables for relationships rather than copying or redefining masters.
5. Apply source-precedence and conflict rules when the same concept is visible in more than one workbook.
6. Keep static rules and profiles separate from future operational events.

Examples:

- A sales order should use the Sales customer account, Production SKU, Finance credit/billing rules, and Logistics fulfilment rules.
- A procurement receipt should use the Procurement supplier-item source, Production material specification, Supply Chain receiving profile, Quality requirements, Finance inventory treatment, and enterprise locations.
- A production event should use Production routing, work center, equipment, material, yield and quality structures, while employee identity and organizational authority resolve through Shared Enterprise and HR.
- A marketing claim should use Marketing's approved wording and governance, Production's product identity, Procurement's source relationships, and Quality's evidence requirements.
- An IT access or incident dataset should use Shared Enterprise employees, roles, positions and systems, IT's technical rules, and the relevant business domain's data ownership.

## Phase boundaries

The architecture intentionally excludes operational history, including:

- sales orders, invoices, forecasts and CRM activity;
- purchase orders, receipts, shipments, inventory balances and supplier performance;
- production orders, batches, consumption, downtime, maintenance work orders and QC results;
- attendance, leave events, payroll, recruitment cases, completed training and performance reviews;
- bank transactions, journal entries, payments, budgets, actuals and depreciation runs;
- user accounts, access grants, logins, incidents, changes, outages, backups and security events;
- campaigns, publications, asset files, approvals, spend and marketing performance;
- delivery events, tracking, POD, returns, carrier performance and logistics exceptions.

Static taxonomies, statuses, approval rules, control rules, process steps, profiles and expected relationships are architecture objects, not event records. Deliberate anomalies should be introduced only during later story and operational dataset design.

## Recommended reading order

1. This root overview.
2. `shared-enterprise/README_shared_enterprise_architecture.md` and the identifier, ownership and cross-domain reference workbooks.
3. `production/README_production.md` for the product, material and manufacturing spine.
4. The README for the domain being generated.
5. The domain's workbook-level `.md` reference files.
6. The authoritative workbook, followed by its derived reference workbook where one exists.

For validation results and known pre-generation warnings, see [architecture_validation_report.md](architecture_validation_report.md).
