# Site Management

## Overview

Sites represent physical facilities owned or operated by a company — offices, warehouses, stores, factories, and distribution centers. Each site is scoped to a single company (companyId) and stores a structured address (street, city, postalCode, country, and optional state/province), a type classification, timezone, and a lifecycle state. Sites provide the geographic foundation that downstream modules depend on: inventory uses sites to determine where stock is held, sales and purchasing reference sites for ship-from and ship-to addresses, and tax modules reference sites for jurisdiction determination.

Unlike business-partner addresses (which represent external parties' billing and shipping details), sites model company-owned facilities only. The organization module owns the physical site definition; operational storage buckets belong to the inventory module's `StorageLocation` entity which references a site directly. Organization uses "Site" to mean a company-owned physical facility; the inventory module uses "StorageLocation" for operational storage buckets within a site.

## Business Purpose

Sites bridge the gap between the legal entity (company) and its physical presence. This enables:

- Geographic scoping of operations: each warehouse, office, or store is a distinct addressable entity
- Structured address storage for consistent formatting, postal validation, and country-specific address rules
- Type classification (office, warehouse, store, factory, distribution center) to distinguish facility purposes
- Timezone assignment per site for scheduling, cutoff times, and local reporting
- Country assignment for tax jurisdiction determination and regulatory compliance
- A reference point for inventory (stock-on-hand at a site), shipping (origin/destination), and purchasing (delivery destination)

The lifecycle ensures:

- Sites are either ACTIVE (available for operational reference) or INACTIVE (no longer in use but preserved for historical records)
- Inactivating a site prevents new inventory movements and order references while preserving all historical data
- Sites have no DRAFT state — they are operational entities created ready for use

## Process Flow

```mermaid
stateDiagram-v2
    [*] --> Active: createSite
    Active --> Inactive: deactivateSite
    Inactive --> Active: reactivateSite
```

The site creation and configuration flow follows this pattern:

```mermaid
flowchart TD
    A[Create Site] --> B[Set Name & Type]
    B --> C[Enter Structured Address]
    C --> D[Assign Country & Timezone]
    D --> E[Activate for Operations]
    E --> F{Site no longer needed?}
    F -->|Yes| G[Deactivate Site]
    F -->|No| H[Site remains ACTIVE]
    G --> I{Reopen facility?}
    I -->|Yes| J[Reactivate Site]
    I -->|No| K[Site remains INACTIVE]
```

## Scenario Patterns

- **New Warehouse Site**: A company opens a new distribution warehouse. A site is created with type WAREHOUSE, the full structured address, country, and the local timezone. Once created, inventory and shipping modules can reference it as a stock-holding and ship-from facility
- **Office Registration**: A company registers its headquarters as a site with type OFFICE. The address and country are recorded for legal correspondence and tax jurisdiction purposes
- **Store Opening**: A retail company opens a new storefront. A site of type STORE is created with the store's physical address, enabling point-of-sale and local inventory tracking
- **Facility Closure**: A factory is shut down permanently. The site is deactivated, preventing new inventory or orders from referencing it, while all historical transactions tied to the site remain intact
- **Facility Reopening**: A previously closed warehouse site is reopened for seasonal demand. The site is reactivated, making it available again for inventory and shipping operations
- **Multi-Site Expansion**: A company expands internationally by adding sites in new countries, each with the appropriate country code and timezone, enabling localized tax and regulatory compliance
- **Address Correction**: A site's street address or postal code is updated to correct a data entry error. The structured address fields are individually updatable without affecting the site's identity or references

## Test Cases

- Sites are created in ACTIVE status (no DRAFT state)
- Site lifecycle follows ACTIVE ↔ INACTIVE state machine
- Site name is required and must be non-empty
- Site type is required and must be one of the allowed classifications (e.g., OFFICE, WAREHOUSE, STORE, FACTORY, DISTRIBUTION_CENTER)
- Each site is scoped to exactly one companyId
- The referenced company must exist and be in ACTIVE status
- Structured address fields (street, city, postal code, country) are required at creation
- Country field is required and must reference a valid country code
- Timezone is required and must be a valid IANA timezone identifier
- A site's companyId is immutable after creation
- Updating address fields on an ACTIVE site is permitted
- Deactivating a site does not delete or modify historical transactions referencing it
- Reactivating an INACTIVE site returns it to ACTIVE status
- Attempting to create a site under a non-existent or INACTIVE company is rejected
- Site deletion is not supported; sites are deactivated instead to preserve referential integrity with downstream records (inventory, orders)
- Multiple sites can exist for the same company
- Site name uniqueness is enforced within the same companyId scope

## Reference Links

- [Odoo Branches / Multi-Location](https://www.odoo.com/documentation/19.0/applications/general/companies.html)
- [Dynamics 365 Sites and Warehouses](https://learn.microsoft.com/en-us/dynamics365/supply-chain/warehousing/warehouse-configuration)
- [SAP Business One Warehouses](https://help.sap.com/docs/SAP_BUSINESS_ONE)
- [Oracle SCM Locations](https://docs.oracle.com/en/cloud/saas/supply-chain-management/24d/fadmm/manage-locations.html)