--- id: SVC-MBR-STR-structure title: Organizational Structure Service product_area: membership module: structure repository: services-membership source_module: modules/structure revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-membership: 5994c270e8a37a30f848e99ba5b5ee6b87c08893 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f inference: [] owns: - DOM-MBR-STR-001 - DOM-MBR-STR-002 does_not_own: - >- Affiliations, identity-bound memberships and applications referencing units belong to the memberships module. - 'Accounting product identities, prices and status belong to Accounting.' - CRM organization identities belong to CRM. - Ordering profiles belong to Commerce. - Committee attachments belong to Committees. - >- Custom-field definitions and registered query infrastructure belong to Platform metadata and Platform query services. - >- Bulk execution and lifecycle coordination belong to Platform import execution and Platform workspace lifecycle coordination. operations: - operation_id: listOrganizationalUnitTypes intent: 'Page through unit kinds by display order and identifier, with optional active-only filtering.' access: console permission: membership.structure.read realises: - CAP-MBR-STR-001 published_to_submissions: 'not published: administrative reading does not collect a submission' - operation_id: createOrganizationalUnitType intent: Define a kind and the parent kinds under which its units can be placed. access: console permission: membership.structure.manage realises: - CAP-MBR-STR-001 published_to_submissions: 'not published: workspace structure administration requires staff authority' - operation_id: getOrganizationalUnitType intent: Retrieve a kind's definition together with its permitted parents. access: console permission: membership.structure.read realises: - CAP-MBR-STR-001 published_to_submissions: 'not published: administrative reading does not collect a submission' - operation_id: replaceOrganizationalUnitType intent: 'Replace the complete kind definition at the read version, applying defaults to omitted fields.' access: console permission: membership.structure.manage realises: - CAP-MBR-STR-001 published_to_submissions: 'not published: workspace structure administration requires staff authority' - operation_id: deactivateOrganizationalUnitType intent: Disable new placements and moves using a kind at its required version. access: console permission: membership.structure.manage realises: - CAP-MBR-STR-001 published_to_submissions: 'not published: workspace structure administration requires staff authority' - operation_id: deleteOrganizationalUnitType intent: Remove an unused kind and its owned parent selections without a version parameter. access: console permission: membership.structure.manage realises: - CAP-MBR-STR-001 published_to_submissions: 'not published: workspace structure administration requires staff authority' - operation_id: listOrganizationalUnitRelationshipTypes intent: Page through the workspace's organization-link purposes by identifier. access: console permission: membership.structure.read realises: - CAP-MBR-STR-007 published_to_submissions: 'not published: administrative reading does not collect a submission' - operation_id: createOrganizationalUnitRelationshipType intent: Add an organization-link purpose using a supplied or name-derived identifier. access: console permission: membership.structure.manage realises: - CAP-MBR-STR-007 published_to_submissions: 'not published: workspace structure administration requires staff authority' - operation_id: listOrganizationalUnits intent: 'Page through units by code, optionally filtering kind, parent or standing.' access: console permission: membership.structure.read realises: - CAP-MBR-STR-005 published_to_submissions: 'not published: administrative reading does not collect a submission' - operation_id: searchOrganizationalUnits intent: 'Find code or name fragments in code order, with an optional standing filter.' access: console permission: membership.structure.read realises: - CAP-MBR-STR-005 published_to_submissions: 'not published: administrative reading does not collect a submission' - operation_id: listOrganizationalUnitTree intent: Page through the whole tree or one branch by depth and code. access: console permission: membership.structure.read realises: - CAP-MBR-STR-005 published_to_submissions: 'not published: administrative reading does not collect a submission' - operation_id: createOrganizationalUnit intent: >- Create an active unit with validated details, custom values and dated placement; the HTTP response is the unit. access: console permission: membership.structure.manage realises: - CAP-MBR-STR-002 - CAP-MBR-STR-006 published_to_submissions: 'not published: workspace structure administration requires staff authority' - operation_id: getOrganizationalUnit intent: Retrieve one unit and its custom values. access: console permission: membership.structure.read realises: - CAP-MBR-STR-006 published_to_submissions: 'not published: administrative reading does not collect a submission' - operation_id: replaceOrganizationalUnit intent: 'Replace ordinary unit details at the read version while preserving placement, kind and standing.' access: console permission: membership.structure.manage realises: - CAP-MBR-STR-006 published_to_submissions: 'not published: workspace structure administration requires staff authority' - operation_id: deleteOrganizationalUnit intent: Remove an unused unit after affiliation and reference checks; the request takes no version. access: console permission: membership.structure.manage realises: - CAP-MBR-STR-004 published_to_submissions: 'not published: workspace structure administration requires staff authority' - operation_id: moveOrganizationalUnit intent: Move a unit and its branch with an explanation and an effective date no later than today. access: console permission: membership.structure.manage realises: - CAP-MBR-STR-002 published_to_submissions: 'not published: workspace structure administration requires staff authority' - operation_id: mergeOrganizationalUnit intent: 'Combine children and eligible memberships under an active survivor, returning counts and leftovers.' access: console permission: membership.structure.manage realises: - CAP-MBR-STR-003 published_to_submissions: 'not published: workspace structure administration requires staff authority' - operation_id: deactivateOrganizationalUnit intent: Close a unit without removing its current relationships or retained work. access: console permission: membership.structure.manage realises: - CAP-MBR-STR-004 published_to_submissions: 'not published: workspace structure administration requires staff authority' - operation_id: listOrganizationalUnitDescendants intent: Read a unit and its descendants now or for effective and knowledge dates. access: console permission: membership.structure.read realises: - CAP-MBR-STR-005 published_to_submissions: 'not published: administrative reading does not collect a submission' - operation_id: listOrganizationalUnitAncestors intent: Read a unit and its current ancestors in increasing distance and code order. access: console permission: membership.structure.read realises: - CAP-MBR-STR-005 published_to_submissions: 'not published: administrative reading does not collect a submission' - operation_id: listOrganizationalUnitParentHistory intent: Read retained parent periods from earliest to latest with attribution. access: console permission: membership.structure.read realises: - CAP-MBR-STR-005 published_to_submissions: 'not published: administrative reading does not collect a submission' - operation_id: listOrganizationalUnitOrganizations intent: Retrieve a unit's organization relationships ordered by first day and identity. access: console permission: membership.structure.read realises: - CAP-MBR-STR-007 published_to_submissions: 'not published: administrative reading does not collect a submission' - operation_id: linkOrganizationalUnitOrganization intent: Add a dated relationship to a CRM reference using a known link purpose. access: console permission: membership.structure.manage realises: - CAP-MBR-STR-007 published_to_submissions: 'not published: workspace structure administration requires staff authority' - operation_id: endOrganizationalUnitOrganization intent: Record or shorten an inclusive link end without a supplied version. access: console permission: membership.structure.manage realises: - CAP-MBR-STR-007 published_to_submissions: 'not published: workspace structure administration requires staff authority' - operation_id: getOrganizationalUnitFinancialSettings intent: 'Read the unit''s ordering-profile and default-dues pointers, or return not found when absent.' access: console permission: membership.structure.read realises: - CAP-MBR-STR-008 published_to_submissions: 'not published: administrative reading does not collect a submission' - operation_id: setOrganizationalUnitFinancialSettings intent: Create financial settings without a version or replace existing settings at their read version. access: console permission: membership.structure.manage realises: - CAP-MBR-STR-008 published_to_submissions: 'not published: workspace structure administration requires staff authority' - operation_id: listOrganizationalUnitDuesProducts intent: 'Read local dues extensions with Accounting product fields, catch-all first.' access: console permission: membership.structure.read realises: - CAP-MBR-STR-008 published_to_submissions: 'not published: administrative reading does not collect a submission' - operation_id: createOrganizationalUnitDuesProduct intent: Extend an existing chapter-dues product for one unit and an optional package. access: console permission: membership.structure.manage realises: - CAP-MBR-STR-008 published_to_submissions: 'not published: workspace structure administration requires staff authority' - operation_id: replaceOrganizationalUnitDuesProduct intent: Replace a dues extension's package pointer at the read version. access: console permission: membership.structure.manage realises: - CAP-MBR-STR-008 published_to_submissions: 'not published: workspace structure administration requires staff authority' - operation_id: membership.unit_descendants intent: Expose a database read of the unit and current descendants inside a connected application's transaction. access: internal permission: database role rhythm_table_reader; row isolation on the caller's workspace realises: - CAP-MBR-STR-005 published_to_submissions: 'not published: an internal read contract rather than submitter intake' - operation_id: membership.unit_ancestors intent: Expose a database read of the unit and current ancestors inside a connected application's transaction. access: internal permission: database role rhythm_table_reader; row isolation on the caller's workspace realises: - CAP-MBR-STR-005 published_to_submissions: 'not published: an internal read contract rather than submitter intake' - operation_id: query datasets membership.organizational_units and membership.organizational_unit_types intent: 'Declare query datasets for units and kinds, including unit custom values and ancestor collections.' access: internal permission: membership.structure.read realises: - CAP-MBR-STR-005 published_to_submissions: 'not published: an internal read contract rather than submitter intake' events: - name: membership.unit.reparented direction: produced when: >- A move or a relocated merge child commits; creation, closure, deletion and bulk loading do not publish this event. payload_summary: >- Version-one data describes the unit, old and new parents, effective first day, optional merged source and transaction attribution. jobs: - >- The structural lifecycle participant applies initial relationship purposes, verifies provisioning, batches purge and export, and supplies inventory. - Development convergence supplies known unit kinds and units through ordinary services. integrations: - system: Accounting products direction: outbound contract: >- The products port reads Accounting tables to validate chapter-dues extensions and supply shared display, status and sale fields. Its transactional write functions have no composed Membership offering caller. - system: Membership business-event outbox and change-events dispatcher direction: outbound contract: >- Moves and relocated children write reparenting to the published-event table before commit. The local registry identifies handlers afterward without proving every delivery policy. - system: Committees and other connected applications direction: inbound contract: Connected readers use the two ancestry functions under the shared reader role and workspace isolation. - system: Platform metadata and query registration direction: outbound contract: >- Object manifests declare unit and kind datasets, with custom fields enabled on units; registration code alone does not certify deployment registration. consistency: - rule: >- Creation, moves and merges rebuild parents, periods, ancestry and depths in one locked transaction. Closure changes standing only, and deletion removes the unused unit and its ancestry pairs without a full rebuild. kind: transactional compensation: Rollback retains the pre-edit arrangement. - rule: >- A merge applies its structural and membership plan in one transaction and rejects the whole result on failure. kind: transactional compensation: Rollback retains both structural and membership records. - rule: >- Reparent event persistence shares the edit transaction, while dispatch happens afterward; no examined handler reacts to reparenting. kind: eventual compensation: No structural compensation is defined; delivery limits remain unknown within this examination. - rule: >- Dues creation checks product existence and type, and later Accounting changes appear on subsequent reads. kind: eventual compensation: >- No compensating product write occurs; a missing or retired product is exposed through inactive or hidden defaults. - rule: >- Declared database version capture retains unit, link and parent-period changes within their writing transaction. kind: transactional compensation: Transaction failure rolls back the corresponding write. evidence: - >- services-membership at 5994c270: modules/structure/aws/api/structure.routes.ts, structure-requests.ts; services/tree/tree-edits.ts; services/persistence/*.ts; ports/accounting-products.ts; services/lifecycle/structure-participant.ts; metadata/structure.objects.ts; modules/events/contracts/business-events.ts; modules/events/services/publishing/publish-business-event.ts; aws/membership.service.ts (STRUCTURE_PERMISSIONS); docs/migrations/structure/README.md. - >- Submissions publication assessed against R2-ARCH-002 as cited by the landed corpus (services-platform:docs/standards/submission-compatible-operations.md, not readable in this job; FND-MBR-STR-039). controls: [TC-AVL-002, TC-AVL-003, TC-AVL-004, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-005, TC-DAT-007, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-MON-003, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-SEC-001, TC-SEC-004, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004] --- # Organizational Structure Service ## What This Service Is For Structure holds the association's units, permitted arrangements, dated parentage, organization links and local dues configuration. It supplies the map used by membership visibility and connected readers. ## Boundary The service owns hierarchy and unit facets, while Memberships owns member records and affiliations. Merge planning and deletion counts call Memberships inside the local transaction. Accounting, CRM, Commerce, Committees and Platform retain ownership of the records and infrastructure referenced at those boundaries. ## Operations in Words Staff define kinds, create units, replace details, move branches, merge sources, close units and delete unused records. Readers can browse or search current records and inspect dated parentage. Link and financial operations maintain local context, and dues operations extend Accounting products without owning their shared fields. Internal ancestry functions and query declarations are listed separately from the HTTP route operations. ## Events and Jobs Moves and relocated children publish reparenting before commit. Creation, moves and merges additionally call telemetry after commit; closure and deletion contain no explicit telemetry call in their examined functions. Lifecycle participation supplies provisioning, inventory, batched export and removal, while development setup uses ordinary services. ## Consistency Guarantees Placement transactions rebuild derived ancestry before committing. Closure and deletion use narrower writes, and bulk loading explicitly defers rebuilding. Merge atomicity covers the local structural and membership plan; product changes and subscriber effects remain separate consistency boundaries.