---
id: CON-MBR-STR-001
name: Association Hierarchy
feature: FEAT-MBR-STR-01
product_area: membership
module: structure
revision: 1
status: draft
product_intent: proposed
implementation_evidence: observed
source_sha:
  services-membership: 5994c270e8a37a30f848e99ba5b5ee6b87c08893
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
definition: >-
  The organizational hierarchy describes the association’s unit categories and the dated parent relationships
  that arrange its units.
owned_by: MOD-MBR-STR
synonyms:
  - association structure
  - unit tree
not_to_be_confused_with:
  - CRM organization parentage
  - Member affiliations
  - Security grants for unit officers
facets:
  - name: Unit category
    meaning: >-
      A customer-defined category describes units such as regions or chapters and their available parent
      choices.
    used_for: Classifying units and selecting categories for membership programs.
  - name: Placement safeguards
    meaning: >-
      Root eligibility, permitted parents, cycle prevention and a maximum depth protect the structural
      arrangement.
    used_for: Checking creation and restructuring requests.
  - name: Present arrangement
    meaning: Stored ancestry pairs describe the current distance between each unit and its ancestors.
    used_for: Supplying current structural reads to other product concerns.
  - name: Dated parentage
    meaning: Effective periods and retained versions explain both when parentage applies and when it becomes known.
    used_for: Reproducing historical structural reporting.
  - name: Restructuring
    meaning: Relocation changes parentage for a unit and its branch with an effective date and explanation.
    used_for: Reflecting changes in the association’s administration.
  - name: Combination
    meaning: A source unit is absorbed into a survivor while eligible children and memberships continue.
    used_for: Consolidating chapters without individual transfers.
  - name: Closure
    meaning: Inactive categories and units retain identity while restricting new structural use.
    used_for: Preserving references when parts of the association close.
relationships:
  - to: CON-MBR-STR-002
    statement: The hierarchy places individual units beneath permitted parents or at eligible roots.
    provenance: observed
    source: 'services-membership:modules/structure/db/organizational-units.table.ts:organizationalUnits'
  - to: CON-MBR-STR-003
    statement: Programs refer to unit categories for affiliation or identifying membership context.
    provenance: observed
    source: 'services-membership:modules/configuration/db/programs.table.ts:programs'
  - to: CON-MBR-STR-006
    statement: Workspace setup supplies lifecycle and loading contributions around the structure.
    provenance: observed
    source: 'services-membership:modules/structure/services/lifecycle/structure-participant.ts:structureParticipant'
lifecycle:
  - state: active
    meaning: Available for ordinary use under its owning record’s activity controls.
    how_it_changes: Deactivation changes availability; a unit can also be combined into a survivor.
  - state: inactive
    meaning: 'Retained outside ordinary active use, with record-specific consumer restrictions.'
    how_it_changes: >-
      Kinds and configuration can reactivate through their ordinary saves; units have no reactivation
      operation.
  - state: merged
    meaning: The unit records absorption into its survivor while preserving identity.
    how_it_changes: Structural mutations are refused; organization and finance operations remain separate.
acted_on_by:
  - CAP-MBR-STR-001
  - CAP-MBR-STR-002
  - CAP-MBR-STR-003
  - CAP-MBR-STR-004
  - CAP-MBR-STR-005
  - CAP-MBR-STR-020
visible_to:
  - ACT-MBR-001
  - ACT-MBR-002
  - ACT-MBR-003
  - ACT-MBR-004
  - ACT-MBR-005
evidence:
  - >-
    services-membership: Verified material includes unit type, unit and parent history tables and persistence,
    the tree edits and tree reads.
  - 'services-membership: Verified material includes the structure module record and the structure tests.'
supersedes:
  - react-console acceptance inventory CAP-MBR-STR-001
  - react-console acceptance inventory CAP-MBR-STR-004
  - react-console acceptance inventory CAP-MBR-STR-005
  - react-console acceptance inventory CAP-MBR-STR-006
  - react-console acceptance inventory CAP-MBR-STR-007
  - react-console acceptance inventory CAP-MBR-STR-008
---

# Association Hierarchy

## What It Is

The organizational hierarchy is the association’s map of its operating parts. Staff use it to distinguish a national body from regions, zones, chapters and sections, and to describe which particular unit belongs beneath another. The categories are configurable, so those familiar names illustrate a customer’s structure rather than prescribe one universal organization. A category describes possible placements; an individual unit occupies one of them.

The hierarchy includes the present arrangement and the dated record of earlier parentage. Those views answer different operational questions. Current ancestry helps identify the branch responsible for a member today. Dated parentage helps interpret a reporting period after the association has reorganized. Retained versions also distinguish an effective date from the moment the change was recorded.

## What It Is Not

The hierarchy does not describe CRM organizations’ own parent relationships. A chapter may correspond to an incorporated organization, but its structural place and its legal relationship remain separate information. Nor does the tree create membership affiliations or security grants. Those concerns refer to the arrangement while maintaining their own records and permissions.

## How It Is Used

Administrators establish unit categories before building the association’s branches. They later relocate units when responsibilities change or combine units when chapters consolidate. Readers consult the same arrangement for current and earlier dates. A successful reorganization preserves the unit identities that other records reference. An invalid parent choice or a loop prevents the operation, leaving staff to choose a different arrangement. Administrators should also review the consequences of merged units that remain visible in the current structure.

## Its Facets

**Unit category.** A category supplies names and placement choices shared by its units.

**Placement safeguards.** Parent eligibility and depth checks protect the complete branch being edited.

**Present arrangement.** Current ancestry supports quick reads of what lies above and below a unit.

**Dated parentage.** Effective periods explain successive placements; versions preserve earlier knowledge and corrections.

**Restructuring.** Relocation carries the branch rather than rewriting its members.

**Combination.** A survivor receives eligible children and membership relationships, with leftovers identified for staff.

**Closure.** Retirement preserves a category or unit that historical references still need.

## How It Relates

Organizational units supply the individual identities arranged by the hierarchy. Programs select categories for affiliation or identity binding. Membership administration, reporting and connected applications use structural reads without taking ownership of parentage. Workspace setup provides the lifecycle and migration context in which the association’s structure is prepared and retained.

## What It Could Become

The product should settle the current-tree treatment of merged units and the reopening of inactive units. Future-effective restructuring and dependable retry behavior would make planned reorganizations easier to administer. Historical display names are another possible extension: the dated structure currently returns the names and codes on the present unit record rather than reconstructing their earlier appearance.