@tailor-platform/erp-kit 0.3.0 → 0.4.0

package/src/modules/organization/docs/commands/UpdateDepartment.md

@@ -0,0 +1,64 @@
+# UpdateDepartment
+
+## Overview
+
+UpdateDepartment modifies the name or parent department of an existing department. The department code and company are immutable. Parent department changes are validated to prevent self-references and circular hierarchies. Updating is allowed on both ACTIVE and INACTIVE departments.
+
+This command supports organizational restructuring and department renaming.
+
+## Business Rules
+
+- Department must exist
+- Name, if provided, must be non-empty
+- Department code cannot be changed
+- companyId cannot be changed
+- Parent department, if provided, must exist and belong to the same company
+- A department cannot reference itself as its own parent
+- Circular parent references are rejected
+- Updating parent department is allowed on both ACTIVE and INACTIVE departments
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Department exists?}
+    B -->|No| C[Return error: DEPARTMENT_NOT_FOUND]
+    B -->|Yes| D{Name provided and empty?}
+    D -->|Yes| E[Return error: INVALID_NAME]
+    D -->|No| F{Parent change requested?}
+    F -->|Yes| G{Self-reference?}
+    G -->|Yes| H[Return error: SELF_REFERENCE]
+    G -->|No| I{Parent exists in same company?}
+    I -->|No| J[Return error: PARENT_NOT_FOUND]
+    I -->|Yes| K{Circular reference?}
+    K -->|Yes| L[Return error: CIRCULAR_REFERENCE]
+    K -->|No| M[Update department record]
+    F -->|No| M
+    M --> N[Return updated department]
+```
+
+## External Dependencies
+
+- [organization::detectDepartmentCircularReference](../queries/DetectDepartmentCircularReference.md) - Validates that reparenting would not create a cycle
+
+## Error Scenarios
+
+- **DEPARTMENT_NOT_FOUND**: Specified department ID does not exist
+- **INVALID_NAME**: Department name is empty
+- **SELF_REFERENCE**: Department references itself as parent
+- **PARENT_NOT_FOUND**: Referenced parent department does not exist or belongs to a different company
+- **CIRCULAR_REFERENCE**: Reparenting would create a circular hierarchy
+
+## Test Cases
+
+- updates department name
+- updates parent department
+- removes parent department (promotes to top-level)
+- throws when department does not exist
+- throws when name is empty
+- throws when name is whitespace-only
+- throws when setting self as parent
+- throws when parent does not exist
+- throws when parent belongs to different company
+- throws when reparenting creates circular reference
+- updates parent on INACTIVE department

package/src/modules/organization/docs/commands/UpdateSite.md

@@ -0,0 +1,80 @@
+# UpdateSite
+
+## Overview
+
+UpdateSite modifies fields on an existing site. Updatable fields include name, type, address fields, country, and timezone. The companyId is immutable after creation. Updating is permitted on both ACTIVE and INACTIVE sites.
+
+This command supports address corrections, type reclassification, and timezone updates.
+
+## Business Rules
+
+- Site must exist
+- Name, if provided, must be non-empty
+- Name, if changed, must remain unique within the same company
+- Type, if provided, must be one of the allowed classifications
+- companyId cannot be changed
+- Timezone, if provided, must be a valid IANA timezone identifier
+- Country, if provided, must reference a valid country code
+- Address fields can be individually updated
+- Required address fields (street, city, postalCode, country), if provided, must be non-empty
+- State/province is optional and may be set or cleared
+- Updating is allowed on both ACTIVE and INACTIVE sites
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Site exists?}
+    B -->|No| C[Return error: SITE_NOT_FOUND]
+    B -->|Yes| D{Name provided and empty?}
+    D -->|Yes| E[Return error: INVALID_NAME]
+    D -->|No| F{Name changed?}
+    F -->|Yes| G{Name unique in company?}
+    G -->|No| H[Return error: DUPLICATE_NAME]
+    G -->|Yes| I{Type valid?}
+    F -->|No| I
+    I -->|Invalid| J[Return error: INVALID_TYPE]
+    I -->|Valid or unchanged| I2{Required address field set to empty?}
+    I2 -->|Yes| I3[Return error: MISSING_REQUIRED_FIELDS]
+    I2 -->|No| K{Country valid?}
+    K -->|Invalid| K2[Return error: INVALID_COUNTRY]
+    K -->|Valid or unchanged| L{Timezone valid?}
+    L -->|Invalid| L2[Return error: INVALID_TIMEZONE]
+    L -->|Valid or unchanged| M[Update site record]
+    M --> N[Return updated site]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **SITE_NOT_FOUND**: Specified site ID does not exist
+- **INVALID_NAME**: Site name is empty
+- **DUPLICATE_NAME**: Site with same name already exists in the same company
+- **INVALID_TYPE**: Site type is not one of the allowed classifications
+- **MISSING_REQUIRED_FIELDS**: A required address field (street, city, postalCode, or country) was set to empty
+- **INVALID_COUNTRY**: Country code is not a valid country code
+- **INVALID_TIMEZONE**: Timezone is not a valid IANA timezone identifier
+
+## Test Cases
+
+- updates site name
+- updates site address fields
+- updates site type
+- updates site timezone
+- throws when site does not exist
+- throws when name is empty
+- throws when name already exists in same company
+- throws when type is invalid
+- throws when country code is invalid
+- throws when timezone is invalid
+- updates site country
+- throws when street is set to empty
+- throws when city is set to empty
+- throws when postalCode is set to empty
+- throws when country is set to empty
+- updates state/province field
+- clears state/province field
+- updates address fields on INACTIVE site

package/src/modules/organization/docs/features/company-lifecycle.md

@@ -0,0 +1,76 @@
+# Company Lifecycle
+
+## Overview
+
+Companies are the root organizational entity in the Organization module. A company represents a legal entity — identified by its legal name, tax identification number, and registration number, along with its registered address and base currency assignment. Companies serve as the scoping entity for all transactional modules; every accounting entry, sales order, purchase order, and inventory movement belongs to exactly one company. Each company has a lifecycle state machine (DRAFT → ACTIVE ↔ INACTIVE) that controls when transactional operations and downstream module integrations are permitted. Fiscal calendar management (fiscal year, periods, cutoff dates) is owned by the accounting module — organization only provides the structural identity that accounting attaches fiscal configuration to.
+
+## Business Purpose
+
+Companies model real-world legal entities that enter contracts, hold tax identities, and prepare financial statements. This enables:
+
+- Multi-company support with data isolation: each transactional record is scoped by companyId
+- Separation of legal entity setup from day-to-day operations — companies are fully configured before going live
+- Assignment of a base/functional currency per company (referencing the primitives module's Currency), ensuring consistent monetary calculations. Currency master data (ISO codes, symbols, exchange rates) is owned by the primitives module; organization only stores which currency a company uses as its base currency
+
+The lifecycle ensures:
+
+- Companies are reviewed and fully configured before downstream modules can reference them (DRAFT → ACTIVE). Activation means the structural identity (legal name, tax ID, registered address, base currency) is complete — it does not imply transactional readiness. Downstream master-data modules (e.g., CoA management) and transactional modules each enforce their own readiness gates on top of company ACTIVE status
+- Inactive companies stop accepting new transactions while preserving all historical data
+- Only DRAFT companies can be permanently deleted; ACTIVE/INACTIVE companies are preserved for audit and legal compliance
+
+## Process Flow
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createCompany
+    Draft --> Active: activateCompany
+    Active --> Inactive: deactivateCompany
+    Inactive --> Active: reactivateCompany
+    Draft --> [*]: deleteCompany
+```
+
+The company creation and setup flow follows this pattern:
+
+```mermaid
+flowchart TD
+    A[Create Company] --> B[Set Legal Details]
+    B --> C[Configure Registered Address]
+    C --> D[Assign Base Currency]
+    D --> E{Ready to go live?}
+    E -->|Yes| F[Activate Company]
+    E -->|No| G[Continue editing]
+    G --> B
+    F --> H[Available for Transactions]
+```
+
+## Scenario Patterns
+
+- **New Company Setup**: A company is created in DRAFT with its legal name and tax identification number. The registered address and base currency are configured, then the company is activated to confirm its structural identity is complete. After activation, master-data modules (e.g., CoA management) can begin building financial configuration on top of the company. Transactional readiness (e.g., journal posting) requires additional setup: an active Chart of Accounts and fiscal calendar configuration
+- **Company Deactivation**: A legal entity ceases operations. The company moves to INACTIVE status, preventing new transactions from being created against it, but all historical records remain accessible for reporting and audit
+- **Company Reactivation**: A previously inactive company resumes operations and is reactivated, allowing new transactions to be recorded against it
+- **Draft Cleanup**: Incomplete company records in DRAFT are deleted before activation when a planned legal entity is no longer needed
+- **Multi-Company Expansion**: A new subsidiary is added to the system as a separate company with its own base currency, enabling consolidated reporting across legal entities. Fiscal calendar for the subsidiary is configured independently via the accounting module
+
+## Test Cases
+
+- Company lifecycle follows DRAFT → ACTIVE ↔ INACTIVE state machine
+- Companies can only be created in DRAFT status
+- Only DRAFT companies can be deleted; ACTIVE and INACTIVE companies cannot
+- Legal name is required and must be non-empty
+- Tax identification number is stored and queryable per company
+- Registration number is stored per company
+- Base currency is optional at creation but must be set and reference a valid Currency from the primitives module before activation
+- Base currency is immutable after activation to preserve transactional consistency
+- Registered address fields are required before activation
+- Activating a company without required fields (legal name, base currency, registered address) is rejected
+- Deactivating a company does not affect existing historical transactions
+- Reactivating an INACTIVE company returns it to ACTIVE status
+- Each company has a unique companyId used for data isolation across transactional modules
+- Deleting an ACTIVE or INACTIVE company returns an error
+
+## Reference Links
+
+- [SAP Business One Company Setup](https://help.sap.com/docs/SAP_BUSINESS_ONE)
+- [Odoo Multi-Company](https://www.odoo.com/documentation/19.0/applications/general/companies.html)
+- [Dynamics 365 Legal Entities](https://learn.microsoft.com/en-us/dynamics365/fin-ops-core/fin-ops/organization-administration/plan-organizational-hierarchy)
+- [Oracle Financials Legal Entity Configuration](https://docs.oracle.com/en/cloud/saas/financials/24d/faigl/legal-entities.html)

package/src/modules/organization/docs/features/department-management.md

@@ -0,0 +1,66 @@
+# Department Management
+
+## Overview
+
+Departments represent functional organizational units within a company — such as Sales, Engineering, Finance, and Human Resources. Each department belongs to exactly one company and is identified by a unique code scoped to that company. Departments form a self-referential hierarchy through an optional parent department reference, enabling the modeling of organizational trees (e.g., Engineering > Backend Engineering > Platform Team). Each department carries a lifecycle state of ACTIVE or INACTIVE and a human-readable name. Departments serve as the primary structural unit for grouping business functions and are referenced by downstream modules. Manager assignment is owned by a future HR/employee module where the manager is an employee/worker reference, not a login identity.
+
+## Business Purpose
+
+Departments provide the foundational organizational structure that other modules build upon. This enables:
+
+- Modeling the functional structure of a company as a hierarchical tree
+- Scoping operational data (budgets, headcount, approvals) to specific organizational units
+- Deactivating departments that are no longer in use without losing historical references
+- Enforcing unique department codes per company for reliable cross-system integration
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Create Department] --> B{Has parent?}
+    B -->|Yes| C[Set parent department]
+    B -->|No| D[Top-level department]
+    C --> E[Department ACTIVE]
+    D --> E
+    E --> F{Restructure needed?}
+    F -->|Reassign parent| G[Update parent reference]
+    G --> E
+    F -->|No longer needed| H{Has active sub-departments?}
+    H -->|Yes| I[Block deactivation]
+    I --> F
+    H -->|No| J[Deactivate Department]
+    J --> K[Department INACTIVE]
+    K --> L{Reactivate?}
+    L -->|Yes| E
+    L -->|No| M[Remains INACTIVE]
+```
+
+## Scenario Patterns
+
+- **Initial Org Structure Setup**: A company is created and its top-level departments (Sales, Engineering, Finance, HR) are added as ACTIVE departments with no parent. Sub-departments are then created beneath them to reflect the real organizational hierarchy.
+- **Department Restructuring**: A reorganization moves the "DevOps" department from under "Engineering" to under "Infrastructure" by updating its parent department reference. All sub-departments of DevOps move with it implicitly through the hierarchy.
+- **Department Deactivation**: The "Legacy Products" department is no longer needed. After confirming it has no active sub-departments, it is set to INACTIVE. Historical records that reference this department remain intact.
+- **Department Reactivation**: A previously deactivated "Partnerships" department is reactivated when the company re-enters a market segment, restoring it to ACTIVE status for new assignments.
+- **Cross-Company Isolation**: Two companies in the same tenant each have a department with code "ENG". The codes are unique per company but do not conflict across companies.
+
+## Test Cases
+
+- A department is created in ACTIVE status by default
+- Department code is required, unique per company, and immutable after creation
+- Department name is required and must be non-empty
+- A department must reference an existing, valid company
+- Setting a parent department creates a hierarchical relationship
+- A department cannot reference itself as its own parent
+- A department cannot be deactivated while it has active sub-departments
+- Deactivating a department sets its state to INACTIVE
+- Reactivating an INACTIVE department sets its state to ACTIVE
+- Updating a department's parent department is allowed on both ACTIVE and INACTIVE departments
+- Department codes from different companies do not conflict (company-scoped uniqueness)
+- Circular parent references are rejected (A -> B -> C -> A)
+- Deleting a company is restricted (rejected) if it has existing department references
+
+## Reference Links
+
+- [SAP Organizational Units](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/5765fa03d4c34ae7b8965e7a41d7c077/af204256a1f84457b2c3f16825e6af89.html)
+- [Odoo Departments (HR)](https://www.odoo.com/documentation/19.0/applications/hr/employees/departments.html)
+- [Dynamics 365 Operating Units](https://learn.microsoft.com/en-us/dynamics365/fin-ops-core/fin-ops/organization-administration/organizations-organizational-hierarchies)

package/src/modules/organization/docs/features/site-management.md

@@ -0,0 +1,86 @@
+# 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; storage layout concerns (zones, bins, aisles) belong to future warehouse modules that use `Warehouse`/`StorageLocation` entities referencing a site. Organization uses "Site" to mean a company-owned physical facility; warehouse modules use "Warehouse" and "StorageLocation" for internal storage layout 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)

package/src/modules/organization/docs/models/Company.md

@@ -0,0 +1,60 @@
+# Company
+
+## Description
+
+Company represents a legal entity in the ERP system — identified by its legal name, tax identification number, registration number, and registered address. Each company is assigned a base currency from the primitives module and serves as the root scoping entity for all transactional modules. Every accounting entry, sales order, purchase order, and inventory movement belongs to exactly one company. Companies follow a lifecycle state machine (DRAFT → ACTIVE ↔ INACTIVE) that controls when transactional operations are permitted.
+
+Examples: "Acme Corp" (active manufacturing company), "Beta Ltd" (draft subsidiary being configured).
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createCompany
+    Draft --> Active: activateCompany
+    Active --> Inactive: deactivateCompany
+    Inactive --> Active: reactivateCompany
+    Draft --> [*]: deleteCompany
+    note right of Draft: Only DRAFT companies can be deleted
+    note right of Active: Base currency is immutable after activation
+```
+
+### Command Definitions
+
+- [createCompany](../commands/CreateCompany.md) - Create a new company in DRAFT status
+- [updateCompany](../commands/UpdateCompany.md) - Modify company fields (legal name, address, tax ID, etc.)
+- [activateCompany](../commands/ActivateCompany.md) - Transition company from DRAFT to ACTIVE
+- [deactivateCompany](../commands/DeactivateCompany.md) - Transition company from ACTIVE to INACTIVE
+- [reactivateCompany](../commands/ReactivateCompany.md) - Transition company from INACTIVE to ACTIVE
+- [deleteCompany](../commands/DeleteCompany.md) - Permanently remove a DRAFT company
+
+### Query Definitions
+
+- [getCompany](../queries/GetCompany.md) - Retrieve a company by ID
+
+### Models
+
+- Company
+
+### Invariants
+
+- Legal name is required and must be non-empty
+- Base currency is optional at creation but must reference a valid Currency from the primitives module before activation
+- Base currency is immutable after activation (ACTIVE or INACTIVE state)
+- Only DRAFT companies can be permanently deleted; ACTIVE and INACTIVE companies are preserved for audit
+- Deleting a DRAFT company is rejected (restrict) if it has existing departments or sites referencing it
+- Registered address fields (street, city, postalCode, country) are required before activation
+- Each company has a unique system-generated ID used for data isolation across transactional modules
+
+### Relationships
+
+- **References Currency (cross-module)**: Company references a Currency from the primitives module as its base currency via baseCurrencyId
+- **Referenced By Department**: Departments belong to exactly one company via companyId
+- **Referenced By Site**: Sites belong to exactly one company via companyId
+- **Referenced By Transactions**: Company is used as scoping entity across all transactional modules (accounting, sales, purchasing, inventory)

package/src/modules/organization/docs/models/Department.md

@@ -0,0 +1,57 @@
+# Department
+
+## Description
+
+Department represents a functional organizational unit within a company — such as Sales, Engineering, Finance, or Human Resources. Each department belongs to exactly one company and is identified by a unique code scoped to that company. Departments form a self-referential hierarchy through an optional parent department reference, enabling the modeling of organizational trees (e.g., Engineering > Backend Engineering > Platform Team). Manager assignment is deferred to a future HR/employee module.
+
+Examples: "ENG" (Engineering), "FIN" (Finance), "ENG-BE" (Backend Engineering under Engineering).
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active: createDepartment
+    Active --> Inactive: deactivateDepartment
+    Inactive --> Active: reactivateDepartment
+```
+
+### Command Definitions
+
+- [createDepartment](../commands/CreateDepartment.md) - Create a new department in ACTIVE status
+- [updateDepartment](../commands/UpdateDepartment.md) - Update department name or parent department
+- [deactivateDepartment](../commands/DeactivateDepartment.md) - Transition department from ACTIVE to INACTIVE
+- [reactivateDepartment](../commands/ReactivateDepartment.md) - Transition department from INACTIVE to ACTIVE
+
+### Query Definitions
+
+- [getDepartment](../queries/GetDepartment.md) - Retrieve a department by ID or code
+- [getDepartmentChildren](../queries/GetDepartmentChildren.md) - Retrieve direct child departments of a given department
+- [detectDepartmentCircularReference](../queries/DetectDepartmentCircularReference.md) - Validate that reparenting would not create a cycle
+- [listDepartmentsByCompany](../queries/ListDepartmentsByCompany.md) - List all departments for a given company
+
+### Models
+
+- Department
+
+### Invariants
+
+- Department code is required, unique per company, and immutable after creation
+- Department name is required and must be non-empty
+- A department must reference an existing, valid company
+- A department cannot reference itself as its own parent
+- Circular parent references are rejected (A → B → C → A)
+- A department cannot be deactivated while it has active sub-departments
+- Updating a department's parent is allowed in both ACTIVE and INACTIVE states
+- Department codes from different companies do not conflict (company-scoped uniqueness)
+
+### Relationships
+
+- **Belongs To Company**: Each department references exactly one Company via companyId
+- **Self-Referential Parent-Child**: Each department optionally references another Department as its parent via parentDepartmentId, forming a tree hierarchy
+- **Referenced By Downstream Modules**: Departments are referenced by future modules for cost allocation, approval workflows, and reporting

package/src/modules/organization/docs/models/Site.md

@@ -0,0 +1,57 @@
+# 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
+```
+
+### Command Definitions
+
+- [createSite](../commands/CreateSite.md) - Create a new site in ACTIVE status
+- [updateSite](../commands/UpdateSite.md) - Update site name, address, type, or timezone
+- [deactivateSite](../commands/DeactivateSite.md) - Transition site from ACTIVE to INACTIVE
+- [reactivateSite](../commands/ReactivateSite.md) - Transition site from INACTIVE to ACTIVE
+
+### Query Definitions
+
+- [getSite](../queries/GetSite.md) - Retrieve a site by ID
+- [listSitesByCompany](../queries/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 Warehouse (future)**: Future warehouse modules will reference sites for storage layout (Warehouse/StorageLocation entities)
+- **Referenced By Inventory**: Sites are referenced by inventory for stock-on-hand tracking
+- **Referenced By Sales/Purchasing**: Sites are referenced as ship-from and delivery destinations

package/src/modules/organization/docs/queries/DetectDepartmentCircularReference.md

@@ -0,0 +1,50 @@
+# DetectDepartmentCircularReference
+
+## Overview
+
+DetectDepartmentCircularReference validates that reparenting a department would not create a circular reference in the hierarchy. It walks up the ancestor chain from the proposed new parent, checking whether the department being moved appears as an ancestor. If the moved department is found in the ancestor chain, the move would create a cycle.
+
+## Business Rules
+
+- A department cannot be moved to become a descendant of itself
+- Self-referencing is explicitly rejected: newParentId === departmentId
+- Ancestor chain is traversed from the new parent upward to the root
+- If the moved department's ID is found in the ancestor chain, the move is circular
+- Traversal stops at root (parentDepartmentId = null) or broken chain (parent not found)
+- Only relevant when newParentId is non-null (promoting to root cannot create a cycle)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive departmentId + newParentId] --> B{newParentId === departmentId?}
+    B -->|Yes| C[Return isCircular: true]
+    B -->|No| D[Set ancestorId = newParentId]
+    D --> E[SELECT ancestor where id = ancestorId]
+    E --> F{Ancestor found?}
+    F -->|No| G[Return isCircular: false]
+    F -->|Yes| H[Set ancestorId = ancestor.parentDepartmentId]
+    H --> I{ancestorId === departmentId?}
+    I -->|Yes| C
+    I -->|No| J{ancestorId is null?}
+    J -->|Yes| G
+    J -->|No| E
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **CIRCULAR_REFERENCE**: The moved department appears in the ancestor chain of the new parent — returns isCircular: true
+- **SELF_REFERENCE**: Department is moved to itself as parent — returns isCircular: true
+
+## Test Cases
+
+- detects self-reference as circular
+- detects moving department under its child as circular
+- detects moving department under its grandchild as circular
+- returns not circular for valid move
+- returns not circular when new parent is root
+- handles broken ancestor chain gracefully (not circular)

package/src/modules/organization/docs/queries/GetCompany.md

@@ -0,0 +1,40 @@
+# GetCompany
+
+## Overview
+
+GetCompany retrieves a single company by its unique identifier. Returns the full company record including status, legal details, address, and base currency reference, or null if no matching company exists.
+
+This function supports company validation and lookup operations across all modules that reference companies.
+
+## Business Rules
+
+- Lookup by `id` performs an exact UUID match
+- Returns the full company record including status, legal name, tax ID, registration number, address, and base currency
+- Does not filter by status — returns DRAFT, ACTIVE, and INACTIVE companies
+- Returns null when no matching company is found
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive lookup request] --> B[Query Company by id]
+    B --> C{Found?}
+    C -->|Yes| D[Return company]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- None (returns null when not found instead of throwing)
+
+## Test Cases
+
+- returns company when found by id
+- returns null when company not found
+- returns DRAFT company
+- returns ACTIVE company
+- returns INACTIVE company