Rhythm 2.0 Specifications

Appearance

CAP-MBR-STR-001Define unit kinds and their permitted places

Markdown

CAP-MBR-STR-001

Define unit kinds and their permitted places

Markdown
  • DocumentDraft
  • Product intentProposed
  • ImplementationObserved

Planning

Feature
FEAT-MBR-STR-01
Key concepts
CON-MBR-STR-001
Actors
ACT-MBR-001, ACT-MBR-002, ACT-MBR-003
Journeys
JNY-MBR-STR-001
Related
CAP-MBR-STR-002, CAP-MBR-STR-010
Proved by
ATS-MBR-STR-001

KindCapabilityProduct areaMembershipModuleOrganizational Structure, Membership Configuration and TermsRevision1

Read atservices-membership 5994c270react-console baf6dae3

Define unit kinds and their permitted places ​

Purpose ​

Administrators describe the association’s building blocks so new units fit an agreed structural pattern.

How It Works ​

An administrator starts by naming the structural categories the association uses. National bodies, regions and chapters are examples rather than a fixed catalogue. Each category has its own readable reference, presentation details and placement choices. Staff specify possible parents and whether units of that kind may stand independently at the top. The service checks those choices when units are placed. A later adjustment may fail because an existing placement still relies on the previous choices. Staff resolve those placements before narrowing the category. Retiring a category keeps its existing units recognizable. Reactivation restores its availability for placement work. Deletion requires the category to be free of references.

Relationships ​

  • Placement and restructuring use these categories to assess proposed parents.
  • Program affiliation requirements select categories from this catalogue.

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes
Units use a recognized kind with explicit placement choices.Unused kinds can leave active use while existing units retain their classification.
Surfaces
api

Controls

33 controls apply, from the corpus control catalogue.

TC-AVL-002 TC-AVL-003 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-004 TC-DAT-007 TC-IAM-001 TC-IAM-002 TC-IAM-004 TC-IAM-005 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-PI-001 TC-PI-003 TC-PI-005 TC-SEC-001 TC-SEC-004 TC-TEN-001 TC-TEN-002 TC-TEN-003

Permissions

KeyChecked atScope
membership.structure.readapitenant
membership.structure.manageapitenant
membership.application.accessapitenant

Business Rules

11 rules, 10 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

IdRuleKindEnforced atProvenance
01must prove
Proposed
A unit kind retains a permanent readable identifier, supplied by staff or derived from its name, using lowercase letters, digits and single underscores.
✓ Omitting the identifier for Sub Region produces sub_region.✗ A whitespace-bearing or reserved identifier fails validation.
no proof recorded yet
validationapi, service, databaseobserved
services-membership:modules/structure/services/persistence/organizational-unit-types.ts:createOrganizationalUnitType
02must prove
Proposed
Creating or replacing a non-root kind without an allowed parent kind is rejected before any record is saved.
no proof recorded yet
validationserviceobserved
services-membership:modules/structure/services/persistence/organizational-unit-types.ts:parentIdsOf
03must prove
Proposed
Allowed parent kinds must belong to this workspace, with self-reference permitted for nested units of the same kind.
no proof recorded yet
validationservice, databaseobserved
services-membership:modules/structure/services/persistence/organizational-unit-types.ts:requireKnownTypes
04must prove
Proposed
Creating a kind under an existing identifier fails without altering the existing kind.
no proof recorded yet
validationservice, databaseobserved
services-membership:modules/structure/services/persistence/organizational-unit-types.ts:createOrganizationalUnitType
05must prove
Proposed
A kind’s root permission and allowed parent kinds cannot be withdrawn while current unit placements depend on them.
no proof recorded yet
policyserviceobserved
services-membership:modules/structure/services/persistence/organizational-unit-types.ts:updateOrganizationalUnitType
06must prove
Proposed
A kind replacement requires the version read and restores omitted fields to their defaults.
no proof recorded yet
policyapi, serviceobserved
services-membership:modules/structure/services/persistence/organizational-unit-types.ts:updateOrganizationalUnitType
07must prove
Proposed
An inactive kind prevents creation and movement of its units while preserving their placements; a full replacement can reactivate the kind.
no proof recorded yet
lifecycleserviceobserved
services-membership:modules/structure/services/tree/tree-edits.ts:validatePlacement
08must prove
Proposed
Deletion is blocked while units, other kinds, programs or package requirements refer to the kind.
no proof recorded yet
lifecycleservice, databasetest
services-membership:tests/e2e/structure-api.e2e.spec.ts#the structure API, end to end in process › refuses to delete a unit type in use, 409 unit_type_in_use
09must prove
Proposed
Kind lists use display order followed by identifier, support pagination and can exclude inactive kinds.
no proof recorded yet
calculationserviceobserved
services-membership:modules/structure/services/persistence/organizational-unit-types.ts:listOrganizationalUnitTypes
10must prove
Proposed
The member-affiliation setting controls new affiliations without removing existing affiliations when it is disabled.
no proof recorded yet
policyserviceobserved
services-membership:modules/structure/services/persistence/organizational-unit-types.ts:updateOrganizationalUnitType
11
Proposed
Committee and geography settings are retained on the kind without an implemented consumer.
policyserviceobserved
services-membership:modules/structure/aws/api/structure-requests.ts:unitTypeBody

Scenarios

IdGivenWhenThenProvenance
01The association uses national, regional, zone and chapter categories.Staff save those categories with their permitted parent choices.The catalogue retains the choices and presents categories in display order.test
services-membership:tests/acceptance/structure/MBR-ACC-0001.acceptance.ts#MBR-ACC-0001 staff define, rename, retire and delete kinds of unit

Edge Cases

IdGivenWhenThenProvenance
02Existing chapters have zone parents.Staff withdraw zone parentage from the chapter category.The service requires those chapters to move before accepting the narrower choice.test
services-membership:tests/acceptance/structure/MBR-ACC-0003.acceptance.ts#MBR-ACC-0003 a tree rule chapters rely on cannot be withdrawn until they move

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.

Rhythm Software