Rhythm 2.0 Specifications

Appearance

CAP-MBR-STR-006Maintain a unit’s identity and local details

Markdown

CAP-MBR-STR-006

Maintain a unit’s identity and local details

Markdown
  • DocumentDraft
  • Product intentProposed
  • ImplementationObserved

Planning

Feature
FEAT-MBR-STR-02
Exercised by
FAS-MBR-STR-02-01, FAS-MBR-STR-02-02, FAS-MBR-STR-02-03, FAS-MBR-STR-02-04, FAS-MBR-STR-02-05
Key concepts
CON-MBR-STR-002
Actors
ACT-MBR-001, ACT-MBR-002
Journeys
JNY-MBR-STR-001
Depends on
CAP-MBR-STR-002
Related
CAP-MBR-STR-007, CAP-MBR-STR-008
Proved by
ATS-MBR-STR-006

Implementation

Executable suites
TST-MBR-STR-006, TST-MBR-STR-066, TST-MBR-STR-087, TST-MBR-STR-088, TST-MBR-STR-089

KindCapabilityProduct areaMembershipModuleOrganizational Structure, Membership Configuration and TermsRevision1

Read atservices-membership 5994c270react-console baf6dae3

Maintain a unit’s identity and local details ​

Purpose ​

Staff maintain the information that identifies and describes an individual chapter, section or regional unit.

How It Works ​

Staff create a unit with a recognizable code and display name. Its local details can describe how to contact it and where correspondence goes. Those details belong to the unit even when a related CRM organization has similar information. Staff can add the customer’s configured unit fields. A single-record read returns those values alongside ordinary details. The replacement operation uses the version staff read, so an intervening edit must be reconciled. Ordinary omitted details return to defaults; custom values use their own submitted-field behavior. Placement and status are managed through structural operations rather than this replacement. The unit’s kind stays fixed after creation. Changes retain attribution and versions. Selecting a welcome template records a choice without establishing that a welcome message is sent.

Relationships ​

  • Creating a unit invokes structural placement validation.
  • Organization links and finance settings refer to the unit’s continuing identity.

The Formal Contract

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

Outcomes
Each unit has its own contact information and customer-specific values.Saved changes retain attribution and version information.
Surfaces
api
Intent sources
services-membership:AGENTS.md#Custom Fields Are Opt-In Per Entity: R2-ARCH-001 (Andrew, 2026-10-19; organizational units declare custom fields)

Controls

38 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-002 TC-DAT-003 TC-DAT-007 TC-IAM-001 TC-IAM-002 TC-IAM-004 TC-IAM-005 TC-LOG-001 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PI-003 TC-PI-005 TC-PRV-001 TC-PRV-002 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

10 rules, 9 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 code uses lowercase letters, digits and single underscores, is unique within the workspace and can change through detail replacement.
proved by ATS-MBR-STR-006-01, TST-MBR-STR-006
validationapi, service, databasetest
services-membership:modules/structure/tests/integration/services/persistence/organizational-units.integration.spec.ts#organizational units in the database › the refusals › refuses a code the tenant already has
02must prove
Proposed
Creation fixes the unit kind and validates placement; detail replacement cannot change kind, parent or status, while later tree operations change placement or status.
proved by ATS-MBR-STR-002-15, ATS-MBR-STR-006-02, ATS-MBR-STR-006-11, TST-MBR-STR-089
invariantapi, serviceobserved
services-membership:modules/structure/services/persistence/organizational-units.ts:updateOrganizationalUnit
03must prove
Proposed
Unit e-mail input is trimmed, normalized to lowercase and validated, with blank input stored as empty.
proved by ATS-MBR-STR-006-03
validationserviceobserved
services-membership:modules/structure/services/persistence/organizational-units.ts:attributeValues
04must prove
Proposed
Latitude must be between minus 90 and 90 and longitude between minus 180 and 180; other address and telephone details have no format validation.
proved by ATS-MBR-STR-006-04
validationdatabaseobserved
services-membership:modules/structure/db/organizational-units.table.ts:organizational_units_latitude_check
05must prove
Proposed
Unit detail replacement requires the version read and resets omitted ordinary fields to their defaults, while custom values change only for submitted fields.
proved by ATS-MBR-STR-006-06, TST-MBR-STR-066
validationdatabasedocumented
services-membership:docs/migrations/structure/README.md#Tables and migrations
06must prove
Proposed
Organizational units accept customer-defined fields validated against unit definitions, with required values checked on creation.
origin: services-membership:AGENTS.md#Custom Fields Are Opt-In Per Entity: R2-ARCH-001 (Andrew, 2026-10-19; organizational units declare custom fields)
proved by ATS-MBR-STR-006-05, TST-MBR-STR-088
validationservice, databaseobserved
services-membership:modules/structure/services/persistence/organizational-units.ts:insertOrganizationalUnit
07must prove
Proposed
Single-unit reads include custom values, whereas ordinary unit lists and tree reads omit them.
proved by ATS-MBR-STR-006-08
policyapi, serviceobserved
services-membership:modules/structure/services/persistence/organizational-units.ts:updateOrganizationalUnit
08must prove
Proposed
Unit and parent-history changes retain attributed versions for audit and historical reconstruction.
proved by ATS-MBR-STR-006-07, ATS-MBR-STR-006-10, TST-MBR-STR-006, TST-MBR-STR-087
calculationserviceobserved
services-membership:modules/structure/services/persistence/organizational-units.ts:getOrganizationalUnit
09must prove
Proposed
Welcome-template selection is stored without an implemented sender.
proved by ATS-MBR-STR-006-09
invariantdatabasetest
services-membership:modules/structure/tests/integration/services/persistence/organizational-units.integration.spec.ts#organizational units in the database › the versions › writes a version of the unit for its creation, its update and its move, each with the actor of its context
10
Proposed
Inactive units allow detail replacement; merged units reject it.
policyserviceobserved
services-membership:modules/structure/metadata/structure.objects.ts:organizationalUnitsObject

Scenarios

IdGivenWhenThenProvenance
01Staff are preparing Atlanta’s local record.They save mailing, geographic, contact and custom details together with visibility.A subsequent single-record read returns the saved details.test
services-membership:tests/acceptance/structure/MBR-ACC-0006.acceptance.ts#MBR-ACC-0006 a complete chapter, recorded and read back

Edge Cases

IdGivenWhenThenProvenance
02An integration expects omitted replacement fields to remain unchanged.It submits code, name and version while omitting optional details.Ordinary details return to defaults, while omitted custom values remain intact.test
services-membership:tests/acceptance/structure/MBR-ACC-0032.acceptance.ts#MBR-ACC-0032 a client that thinks PUT is a patch, and a unit deleted behind the service

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