# `Logistiki.BusinessEntities.BusinessEntity`
[🔗](https://github.com/thanos/logistiki/blob/v0.1.0/lib/logistiki/business_entities/business_entity.ex#L1)

A hierarchical business entity: legal, operational, customer, organizational,
or ownership structure.

Entities form a tree maintained through a closure table
(`Logistiki.BusinessEntities.BusinessEntityClosure`). Each entity may have a
`parent_id` pointing to its parent; roots have `parent_id: nil`.

## Fields

  * `id` — `integer()` — primary key (e.g. `1`)
  * `parent_id` — `integer() | nil` — self-reference; `nil` for roots (e.g. `nil` or `1`)
  * `name` — `String.t()` — display name (required) (e.g. `"Acme Holdings"`)
  * `legal_name` — `String.t() | nil` — legal name (e.g. `"Acme Holdings LLC"`)
  * `entity_type` — `String.t()` — one of `types/0` (default `"company"`, e.g. `"trust"`, `"individual"`)
  * `status` — `String.t()` — one of `statuses/0` (default `"pending"`, e.g. `"active"`, `"frozen"`)
  * `jurisdiction` — `String.t() | nil` — e.g. `"US"`, `"EU"`, `"GB"`
  * `external_id` — `String.t() | nil` — unique external reference (e.g. `"crm_12345"`)
  * `metadata` — `map()` — extensible key/value store (default `%{}`, e.g. `%{"risk_score" => "low"}`)
  * `inserted_at` — `DateTime.t() | nil` — set by Ecto timestamps (e.g. `~U[2026-07-07 12:00:00Z]`)
  * `updated_at` — `DateTime.t() | nil` — set by Ecto timestamps

## Associations

  * `parent` — `belongs_to` `__MODULE__` — the parent entity (via `parent_id`)
  * `children` — `has_many` `__MODULE__` — direct child entities

## Example

    %Logistiki.BusinessEntities.BusinessEntity{
      id: 1,
      parent_id: nil,
      name: "Acme Holdings",
      legal_name: "Acme Holdings LLC",
      entity_type: "company",
      status: "active",
      jurisdiction: "US",
      external_id: "crm_12345",
      metadata: %{"risk_score" => "low"},
      inserted_at: ~U[2026-07-07 12:00:00Z],
      updated_at: ~U[2026-07-07 12:00:00Z]
    }

# `t`

```elixir
@type t() :: %Logistiki.BusinessEntities.BusinessEntity{
  __meta__: term(),
  children: term(),
  entity_type: String.t() | nil,
  external_id: String.t() | nil,
  id: integer() | nil,
  inserted_at: DateTime.t() | nil,
  jurisdiction: String.t() | nil,
  legal_name: String.t() | nil,
  metadata: map() | nil,
  name: String.t() | nil,
  parent: term(),
  parent_id: integer() | nil,
  status: String.t() | nil,
  updated_at: DateTime.t() | nil
}
```

The `BusinessEntity` struct type.

Represents a hierarchical business entity with provenance, status, and
extensible metadata.

## Fields

  * `id` — `integer() | nil` — primary key (e.g. `1`)
  * `parent_id` — `integer() | nil` — parent entity id; `nil` for roots
  * `name` — `String.t() | nil` — display name (e.g. `"Acme Holdings"`)
  * `legal_name` — `String.t() | nil` — legal name
  * `entity_type` — `String.t() | nil` — e.g. `"company"`, `"trust"`
  * `status` — `String.t() | nil` — e.g. `"active"`, `"frozen"`
  * `jurisdiction` — `String.t() | nil` — e.g. `"US"`
  * `external_id` — `String.t() | nil` — unique external reference
  * `metadata` — `map() | nil` — extensible metadata
  * `inserted_at` — `DateTime.t() | nil`
  * `updated_at` — `DateTime.t() | nil`

## Example

    %Logistiki.BusinessEntities.BusinessEntity{
      id: 1, parent_id: nil, name: "Acme Holdings",
      entity_type: "company", status: "active"
    }

# `statuses`
*since 0.1.0* 

```elixir
@spec statuses() :: [atom(), ...]
```

Returns the list of allowed entity statuses as atoms.

## Returns

  * `[atom()]` — `[:pending, :active, :inactive, :frozen, :closed]`

## Examples

    iex> Logistiki.BusinessEntities.BusinessEntity.statuses()
    [:pending, :active, :inactive, :frozen, :closed]

# `types`
*since 0.1.0* 

```elixir
@spec types() :: [atom(), ...]
```

Returns the list of allowed entity types as atoms.

## Returns

  * `[atom()]` — `[:individual, :company, :trust, :partnership, :fund,
    :bank, :branch, :department, :counterparty, :internal]`

## Examples

    iex> :company in Logistiki.BusinessEntities.BusinessEntity.types()
    true

---

*Consult [api-reference.md](api-reference.md) for complete listing*