# README

## Overview

The Organization module manages the foundational organizational structure of the ERP system — legal entities (companies), departments, and physical sites. It defines "who we are" and "where we operate" as the structural backbone that all transactional modules reference for scoping and context.

Each company represents a legal entity with its own tax identity, registered address, and base currency assignment. Departments model the internal functional structure within a company, while sites represent the physical facilities (offices, warehouses, stores) where operations take place. Together, these entities provide the multi-company, multi-site foundation that downstream modules (accounting, sales, purchasing, inventory) depend on.

## Key Features

- **[Company Lifecycle](docs/feature/company-lifecycle.md)**: Create and manage legal entities with lifecycle state machine (DRAFT → ACTIVE ↔ INACTIVE). Companies store legal name, tax ID, registration number, registered address, and base currency assignment. Fiscal calendar is owned by accounting
- **[Department Management](docs/feature/department-management.md)**: Create and manage departments within a company with self-referential hierarchy (parent department), unique code per company, and lifecycle state (ACTIVE/INACTIVE). Manager assignment is deferred to the workforce module
- **[Site Management](docs/feature/site-management.md)**: Manage physical sites/facilities owned by a company — offices, warehouses, stores, factories. Each site has a structured address, type classification, country, timezone, and lifecycle state. Operational storage buckets (`StorageLocation`) are owned by the inventory module, which references Site directly

## Module Scope

### In Scope

- Company/legal entity master data management (create, update, delete, status transitions)
- Company lifecycle state machine (DRAFT → ACTIVE ↔ INACTIVE)
- Tax identification number and registration number storage per company
- Base currency assignment per company (currency master data owned by primitives module; organization stores only the company→currency reference)
- Department CRUD with hierarchical parent-child structure
- Department code uniqueness enforcement per company
- Physical site management with structured addresses
- Site type classification (office, warehouse, store, factory)
- Site country and timezone assignment

### Out of Scope

- User account management and authentication (user-management module)
- Employee profiles, HR attributes, and employment records (owned by the workforce module)
- Department manager assignment — requires employee/worker reference, not user ID (workforce module; not yet provided in workforce v1)
- Company-to-user membership and role mapping (future organization-membership or workforce module)
- Organizational hierarchy with multiple purposes and effective dates (future enhancement)
- Business unit and division management for financial reporting (future management-accounting module)
- Cost center and profit center management (future management-accounting module)
- Fiscal calendar management — fiscal year, periods, cutoff dates (financial-accounting module)
- Inter-company transaction configuration (future enhancement)
- Operational storage buckets — `StorageLocation` (owned by the inventory module; references organization `Site`)
- Business partner addresses — billing, shipping (future business-partner module)

### Scope Decision Rationale

Organization is strictly scoped to **structural identity** — the legal, functional, and physical structure of the business. It answers "which legal entity?", "which department?", and "which site?" without owning any transactional or operational data.

Company/legal entity is the root scoping entity. Nearly every transactional record in the ERP will carry a `companyId` referencing this module. This makes organization a foundational module that should remain stable and simple.

Departments are included because they represent the internal functional structure that many modules reference (cost allocation, approval workflows, reporting). The self-referential hierarchy is sufficient for initial needs; a more flexible multi-purpose hierarchy system can be added later if required.

Sites are included because physical facilities are referenced by inventory (stock holding), sales (ship-from), purchasing (delivery destination), and tax (jurisdiction). Organization owns the site identity and address; the inventory module owns the operational storage buckets (`StorageLocation`) referencing a site directly.

Employee/HR data is excluded because an employee is a business domain entity with its own lifecycle (hiring, termination, leave) that differs from organizational structure. A user account (user-management) is a login identity, an employee is an HR record, and a department membership is a structural assignment — these three concepts must remain separate. Consequently, department manager and company-to-user membership are also deferred: the manager of a department is an employee/worker, not a login identity, and membership requires an employee concept that this module does not own — the workforce module owns that employee concept.

## Module Dependencies

- [primitives](../primitives/README.md) — Currency definitions for company base currency assignment