--- id: MOD-MBR-STR title: 'Organizational Structure, Membership Configuration and Terms' product_area: membership module: structure revision: 1 status: draft source_sha: services-membership: 5994c270e8a37a30f848e99ba5b5ee6b87c08893 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f repositories: - name: services-membership paths: - modules/structure - modules/configuration - modules/terms - docs/acceptance - 'aws/membership.service.ts (application, structure, programs and configuration permission groups)' - aws/terms (the term engine’s routes) - aws/api/configuration-routes.ts - aws/api/route-inputs.ts - README.md - AGENTS.md - docs/migrations/structure/README.md - docs/migrations/unit-merge/README.md - docs/migrations/packages-as-products/README.md - docs/migrations/membership-core/README.md (configuration sections) - docs/migrations/bootstrap/README.md (term rules) - >- tests/e2e/{structure-api,terms-api,packages-as-products,database-refusals,s04-lapse-and-rejoin,s09-restructuring,s13-unit-merge}.e2e.spec.ts - 'tests/unit/{route-authorization,metadata-registration}.spec.ts' - tests/acceptance/structure - tests/acceptance/configuration - >- modules/memberships/services/affiliations/unit-rules.ts and modules/memberships/tests/integration/services/identity-unit-merge.integration.spec.ts (cited records of the memberships module) - name: react-console paths: - 'app/(console)/console/[tenantId]/membership' - acceptance/membership - components/membership/settings (read for the boundary) - components/console/nav-config.ts (the Membership configuration entry) - lib/authz/permissions.ts (the console’s Membership permission names) owns: - Unit kinds and permitted parent kinds - 'Unit identities, custom values, current placements, dated parent history and record versions' - Organization links and the relationship categories used for those links - Unit finance settings and Accounting dues-product extensions - Programs and their permitted membership unit kinds - Membership types and organization-to-person flow-down selections - 'Accounting membership-product extensions, package grants, unit requirements and fixed term boundaries' - Package change policy sets and their selector cases - Reasons available for membership status changes - >- Term date calculations, status and continuity calculations, holding-cache changes, sweep decisions and reusable term columns - >- Structure lifecycle participation, initial records, validated bulk loads, export definitions, metadata registrations and published tree functions does_not_own: - record: >- Membership records, their terms and affiliations, rosters, officer scopes, scheduled sweep execution, staff actions and configuration revision history owner: MOD-MBR-MEM - record: Application process definitions and submitted applications owner: MOD-MBR-MEM - record: 'Commerce participation, membership billing execution and purchase snapshots' owner: MOD-MBR-MEM - record: 'Product identities, pricing and activity in Accounting' owner: MOD-ACC-PRD - record: 'Commerce ordering profiles, purchases and checkout' owner: MOD-COM-ORD - record: Commerce member-pricing audiences displayed in Membership settings owner: MOD-COM-CAT - record: 'CRM organization identities, organization categories and contact relationships' owner: MOD-CRM-ENT - record: Committees associated with organizational units owner: MOD-CMT-CMT - record: 'Workspace creation, reset, export and removal coordination' owner: MOD-PFM-TNL - record: Data import job execution and identity crosswalks owner: MOD-PFM-DJE - record: 'Access roles, permission policies and authorization decisions' owner: MOD-PFM-SEC - record: 'Custom-field schemas, object registration infrastructure and query datasets' owner: MOD-PFM-MTD and MOD-PFM-QRY hosted_screens: [] supersedes: - react-console acceptance inventory area STR (CAP-MBR-STR-001 to 014) - 'react-console acceptance inventory area CFG (CAP-MBR-CFG-001 to 009, 011, 013 to 016)' evidence: - >- services-membership: pinned route declarations, request validation, record persistence, structural edits, table declarations, date and status algorithms, lifecycle participation, data loading, exports and metadata; associated unit, integration, end-to-end and manual acceptance suites; local structure, merger, product-extension and final-acceptance records. - >- react-console: pinned Membership routes, settings and navigation establish the screen boundary; the permission map and acceptance inventories supply permission vocabulary and historical coverage references. coverage_catalog: > ### Source coverage at the pinned commits | Measure | Covered | Ratio | |---|---|---| | HTTP operations with an operation id in the module’s route files (structure 29, configuration 26, terms 1; the three public health routes are not counted) | 56 of 56 | 56/56 | | Tables declared in `modules/structure/db/*.table.ts` and `modules/configuration/db/*.table.ts` (13 and 12), each named by a capability | 25 of 25 | 25/25 | | Permission keys of the application, structure, programs and configuration groups, each reachable from a capability | 7 of 7 | 7/7 | | Test spec files of the module (structure 8, terms 8; the structure fixtures file is support) cited by a rule, a scenario binding or a finding | 16 of 16 | 16/16 | | End-to-end files of `tests/e2e/` in scope (structure-api, terms-api, packages-as-products, database-refusals, s04, s09, s13) cited | 7 of 7; the other 15 end-to-end files belong to the memberships module | 7/7 | | Acceptance journeys of the structure and configuration areas (37 and 43) named by a scenario binding, a rule, a journey or a finding | 80 of 80; MBR-ACC-0108 (application processes) and MBR-ACC-0109 (configuration revisions) are named for the boundary and belong to `MOD-MBR-MEM`; catalogue pass labels describe historical runs and do not certify the present examination | 80/80 | | Acceptance inventory capabilities of the STR and CFG areas named in a `supersedes` | 28 of 30; CAP-MBR-CFG-010 (application processes) and CAP-MBR-CFG-012 (configuration history) belong to `MOD-MBR-MEM` | 28/30 | | State machines, queues and schedules in scope | none: the nightly status sweep’s schedule and the event dispatcher belong to `MOD-MBR-MEM`; this module decides what the sweep does | — | ### Operation ownership | Capability | Operations | |---|---| | `CAP-MBR-STR-001` | `listOrganizationalUnitTypes`, `createOrganizationalUnitType`, `getOrganizationalUnitType`, `replaceOrganizationalUnitType`, `deactivateOrganizationalUnitType`, `deleteOrganizationalUnitType` | | `CAP-MBR-STR-002` | `createOrganizationalUnit` (placement), `moveOrganizationalUnit` | | `CAP-MBR-STR-003` | `mergeOrganizationalUnit` | | `CAP-MBR-STR-004` | `deactivateOrganizationalUnit`, `deleteOrganizationalUnit` | | `CAP-MBR-STR-005` | `listOrganizationalUnits`, `searchOrganizationalUnits`, `listOrganizationalUnitTree`, `listOrganizationalUnitDescendants`, `listOrganizationalUnitAncestors`, `listOrganizationalUnitParentHistory` | | `CAP-MBR-STR-006` | `createOrganizationalUnit` (record), `getOrganizationalUnit`, `replaceOrganizationalUnit` | | `CAP-MBR-STR-007` | `listOrganizationalUnitRelationshipTypes`, `createOrganizationalUnitRelationshipType`, `listOrganizationalUnitOrganizations`, `linkOrganizationalUnitOrganization`, `endOrganizationalUnitOrganization` | | `CAP-MBR-STR-008` | `getOrganizationalUnitFinancialSettings`, `setOrganizationalUnitFinancialSettings`, `listOrganizationalUnitDuesProducts`, `createOrganizationalUnitDuesProduct`, `replaceOrganizationalUnitDuesProduct` | | `CAP-MBR-STR-009` | `listPrograms`, `createProgram`, `getProgram`, `updateProgram`, `deleteProgram` | | `CAP-MBR-STR-010` | `replaceProgramUnitTypes` | | `CAP-MBR-STR-011` | `listMembershipTypes`, `createMembershipType`, `getMembershipType`, `updateMembershipType`, `deleteMembershipType` | | `CAP-MBR-STR-012` | `listMembershipPackages`, `createMembershipPackage`, `getMembershipPackage`, `updateMembershipPackage`, `deleteMembershipPackage` | | `CAP-MBR-STR-014` | `listChangePolicySets`, `createChangePolicySet`, `getChangePolicySet`, `updateChangePolicySet`, `deleteChangePolicySet` | | `CAP-MBR-STR-017` | `listStatusReasons`, `createStatusReason`, `getStatusReason`, `updateStatusReason`, `deleteStatusReason` | | `CAP-MBR-STR-019` | `getTermsTenantHealth` | ### Table ownership | Capability | Tables | |---|---| | `CAP-MBR-STR-001` | `organizational_unit_types`, `organizational_unit_type_parents` | | `CAP-MBR-STR-002` | `organizational_unit_closure`, `organizational_unit_parent_history`, `organizational_unit_parent_history_versions` | | `CAP-MBR-STR-006` | `organizational_units`, `organizational_units_versions`, `organizational_unit_custom_field_values` | | `CAP-MBR-STR-007` | `organizational_unit_relationship_types`, `organizational_unit_organizations`, `organizational_unit_organizations_versions` | | `CAP-MBR-STR-008` | `organizational_unit_financial_settings`, `organizational_unit_dues_products` | | `CAP-MBR-STR-009` | `programs` | | `CAP-MBR-STR-010` | `program_unit_types` | | `CAP-MBR-STR-011` | `membership_types`, `membership_type_flowdown_contact_roles`, `membership_type_flowdown_organization_types` | | `CAP-MBR-STR-012` | `membership_packages` | | `CAP-MBR-STR-013` | `package_grants`, `package_unit_rules` | | `CAP-MBR-STR-014` | `change_policy_sets`, `change_policies` | | `CAP-MBR-STR-015` | `package_fixed_term_ends` | | `CAP-MBR-STR-017` | `membership_status_reasons` | --- # Organizational Structure, Membership Configuration and Terms ## Purpose The association defines its organizational units, arranges them into a hierarchy and maintains that arrangement through moves, mergers and retirement. Membership setup connects programs and types to the packages available for purchase. Shared term calculations supply dates, status and continuity decisions to the services that manage membership records. ## Boundary Structure owns unit definitions and relationships, membership configuration and the term engine. Membership operations own member records, affiliations, applications, billing and scheduled execution. Accounting supplies the underlying products; Commerce supplies ordering profiles and purchases; CRM supplies organization identities; Committees manages committee records. Platform coordinates workspace lifecycle, imports, authorization, custom-field schemas and query infrastructure. The permitted console routes contain no administration screen for this module. The planning layer therefore describes service operations and internal calculation interfaces, with browser workflows remaining an open design concern. Source coverage and acceptance proof are tracked separately: a referenced file establishes examination scope, while a test binding identifies a particular executable example. ## Features | Feature | Name | Concepts | Capabilities | Journeys | |---|---|---|---|---| | `FEAT-MBR-STR-01` | Association Hierarchy | 1 | 5 | 2 | | `FEAT-MBR-STR-02` | Organizational Units | 1 | 3 | 1 | | `FEAT-MBR-STR-03` | Programs and Classifications | 1 | 3 | 1 | | `FEAT-MBR-STR-04` | Membership Offerings | 1 | 3 | 0 | | `FEAT-MBR-STR-05` | Terms and Standing | 1 | 3 | 1 | | `FEAT-MBR-STR-06` | Setup Governance | 1 | 3 | 0 | ## Capabilities | Capability | Feature | Title | Product Intent | Evidence | |---|---|---|---|---| | `CAP-MBR-STR-001` | `FEAT-MBR-STR-01` | Define unit kinds and their permitted places | proposed | observed | | `CAP-MBR-STR-002` | `FEAT-MBR-STR-01` | Restructure units while preserving dated placement | proposed | observed | | `CAP-MBR-STR-003` | `FEAT-MBR-STR-01` | Combine units and continue their memberships | proposed | observed | | `CAP-MBR-STR-004` | `FEAT-MBR-STR-01` | Close units or remove units without retained dependencies | proposed | observed | | `CAP-MBR-STR-005` | `FEAT-MBR-STR-01` | Find units and inspect current or historical structure | proposed | observed | | `CAP-MBR-STR-006` | `FEAT-MBR-STR-02` | Maintain a unit’s identity and local details | proposed | observed | | `CAP-MBR-STR-007` | `FEAT-MBR-STR-02` | Describe a unit’s dated relationships with organizations | proposed | observed | | `CAP-MBR-STR-008` | `FEAT-MBR-STR-02` | Connect unit dues to products and settlement choices | proposed | observed | | `CAP-MBR-STR-009` | `FEAT-MBR-STR-03` | Establish programs and their membership context | proposed | partially-observed | | `CAP-MBR-STR-010` | `FEAT-MBR-STR-03` | Set a program’s affiliation requirements | proposed | observed | | `CAP-MBR-STR-011` | `FEAT-MBR-STR-03` | Classify memberships and configure organization flow-down | proposed | observed | | `CAP-MBR-STR-012` | `FEAT-MBR-STR-04` | Offer membership through an Accounting product | proposed | observed | | `CAP-MBR-STR-013` | `FEAT-MBR-STR-04` | Bundle grants and package-specific unit requirements | proposed | observed | | `CAP-MBR-STR-014` | `FEAT-MBR-STR-04` | Record policies for future package changes | proposed | partially-observed | | `CAP-MBR-STR-015` | `FEAT-MBR-STR-05` | Determine a term’s start and end dates | proposed | observed | | `CAP-MBR-STR-016` | `FEAT-MBR-STR-05` | Interpret membership status and continuity by date | proposed | observed | | `CAP-MBR-STR-017` | `FEAT-MBR-STR-05` | Maintain reasons for membership status actions | proposed | observed | | `CAP-MBR-STR-018` | `FEAT-MBR-STR-06` | Maintain configuration with consistent change safeguards | proposed | observed | | `CAP-MBR-STR-019` | `FEAT-MBR-STR-06` | Authorize structure and configuration work | proposed | observed | | `CAP-MBR-STR-020` | `FEAT-MBR-STR-06` | Provision, migrate and remove membership setup | proposed | partially-observed | ## Journeys | Journey | Title | E2E Policy | |---|---|---| | `JNY-MBR-STR-001` | Prepare the association’s structure and local dues | optional | | `JNY-MBR-STR-002` | Reorganize a branch and retain its earlier reporting context | optional | | `JNY-MBR-STR-003` | Combine chapters and review the membership result | optional | | `JNY-MBR-STR-004` | Prepare a program and enrol its first member | optional | | `JNY-MBR-STR-005` | Interpret expiry, lapse and a later rejoin | none |