# CreateCompany

## Permission Scope

company

## Overview

CreateCompany establishes a new legal entity in the system in DRAFT status. The command accepts the company's legal name, and optionally tax identification number, registration number, base currency, and registered address fields. Companies are created in DRAFT to allow configuration and review before activation.

This command supports initial system setup and multi-company expansion scenarios.

## Business Rules

- Legal name is required and must be non-empty
- Company is always created in DRAFT status
- Base currency, if provided, must reference a valid active Currency from the primitives module
- Tax identification number and registration number are optional at creation
- Registered address fields are optional at creation (required before activation)

## Process Flow

```mermaid
flowchart TD
    A[Receive create request] --> B{Validate legal name}
    B -->|Empty| C[Return error: INVALID_LEGAL_NAME]
    B -->|Valid| D{Base currency provided?}
    D -->|Yes| E{Currency exists and active?}
    E -->|No| F[Return error: CURRENCY_NOT_FOUND]
    E -->|Yes| G[Create company record]
    D -->|No| G
    G --> H[Set status: DRAFT]
    H --> I[Return created company]
```

## External Dependencies

- [primitives::getCurrency](../../../primitives/docs/query/GetCurrency.md) - Validates that the referenced base currency exists and is active

## Error Scenarios

- **INVALID_LEGAL_NAME**: Legal name is empty, whitespace-only, or not provided
- **CURRENCY_NOT_FOUND**: Referenced base currency does not exist or is inactive

## Test Cases

- creates company in DRAFT status
- throws when legal name is empty
- throws when referenced currency does not exist
- throws when referenced currency is inactive
- creates company without base currency
- creates company with full address fields
- passes custom fields through to insert
