# Site

## Description

Site represents a physical facility owned or operated by a company — offices, warehouses, stores, factories, and distribution centers. Each site is scoped to a single company and stores a structured address (street, city, state/province, postal code, country), type classification, timezone, and 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.

Examples: "Tokyo HQ" (OFFICE), "Osaka Warehouse" (WAREHOUSE), "Shibuya Store" (STORE).

## Domain Model Definitions

### Model type

Stateful

#### State Transitions

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

| Operation | From | To | Command |
|-----------|------|----|---------|
| deactivate | ACTIVE | INACTIVE | [deactivateSite](../command/DeactivateSite.md) |
| reactivate | INACTIVE | ACTIVE | [reactivateSite](../command/ReactivateSite.md) |

### Command Definitions

- [createSite](../command/CreateSite.md) - Create a new site in ACTIVE status
- [updateSite](../command/UpdateSite.md) - Update site name, address, type, or timezone
- [deactivateSite](../command/DeactivateSite.md) - Transition site from ACTIVE to INACTIVE
- [reactivateSite](../command/ReactivateSite.md) - Transition site from INACTIVE to ACTIVE

### Query Definitions

- [getSite](../query/GetSite.md) - Retrieve a site by ID
- [listSitesByCompany](../query/ListSitesByCompany.md) - List all sites for a given company

### Models

- Site

### Invariants

- Site name is required, non-empty, and unique within the same company
- Site type is required and must be one of: OFFICE, WAREHOUSE, STORE, FACTORY, DISTRIBUTION_CENTER
- Structured address fields (street, city, postalCode, country) are required at creation
- State/province is optional (not all countries use states or provinces)
- Country must reference a valid country code
- Timezone is required and must be a valid IANA timezone identifier
- companyId is immutable after creation
- The referenced company must exist and be in ACTIVE status at creation time
- Site deletion is not supported; deactivation is used instead to preserve referential integrity with downstream records

### Relationships

- **Belongs To Company**: Each site references exactly one Company via companyId
- **Referenced By Inventory**: Sites are referenced by inventory's StorageLocation entity as the parent of each location, and for stock-on-hand aggregation
- **Referenced By Sales/Purchasing**: Sites are referenced as ship-from and delivery destinations