--- id: FEAT-CRM-ENT-02 title: Organization Records product_area: crm module: entities revision: 1 status: approved product_intent: proposed source_sha: services-crm: 7ea48a414c42eade10d60753b8bcc323b1dd726f react-console: da63075876b2c5f4a6af07d457bb24ea8bf4c0c7 purpose: >- Staff record organizations and their place in a wider structure. These records provide a shared reference for work with people and organizations. outcomes: - Staff record organizations and their place in a wider structure. concepts: - CON-CRM-ENT-002 actors: - ACT-CRM-001 - ACT-CRM-002 - ACT-CRM-003 - ACT-CRM-004 - ACT-CRM-005 acceptance: FAS-CRM-ENT-02 capabilities: - CAP-CRM-ENT-002 journeys: [] approved_by: Andrew approved_at: 2026-10-22T00:00:00.000Z narrative: status: verified review: NARRATIVE-REVIEW-2026-10-23 narrative_sources: - section: Why It Exists provenance: inferred source: CAP-CRM-ENT-002 note: >- Operational consequences are the reviewer’s reading of the child contracts, not attributed historical motivation. The affiliation milestone supplies the current-membership distinction where named. - section: Decisions and Tradeoffs provenance: inferred source: "CAP-CRM-ENT-002" note: The tradeoffs interpret the child contracts; no historical motive is attributed. - section: How It Works provenance: observed source: >- services-crm:modules/entities/tests/integration/services/persistence/organizations.field-rules.integration.spec.js#refuses a name of 201 characters, naming name; services-crm:modules/entities/tests/e2e/organizations.e2e.spec.js#keeps the id the body named, which is no UUIDv7; services-crm:modules/entities/tests/integration/services/persistence/organizations.integration.spec.js#renumbers after the tenant's highest organization number, never its contacts'; services-crm:modules/entities/tests/e2e/organization-types.e2e.spec.js#refuses an organization of a type the tenant does not have (409), and the delete of a type an organization has (409); services-crm:modules/entities/tests/e2e/organizations.e2e.spec.js#answers 409 for a parent the tenant does not have; services-crm:modules/entities/tests/integration/db/organizations.table.integration.spec.js#refuses the second move by organizations_parent_not_descendant once the first commits; services-crm:modules/entities/tests/integration/services/persistence/organizations.integration.spec.js#answers the descendant, never saved again, its ancestry under the new parent; services-crm:modules/entities/tests/integration/db/organizations.table.integration.spec.js#refuses a status outside the closed list by organizations_status_check; services-crm:modules/entities/tests/unit/db/organization-domain-name.spec.js#derives the domain name without the protocol or the www prefix; services-crm:modules/entities/tests/integration/services/persistence/organizations.integration.spec.js#refuses the update as ObjectInvalid, naming the logo field; FND-CRM-ENT-029; services-crm:docs/milestones/CRM-M1-contacts-and-organizations.plan.md#2. Scope related_concepts: - CON-CRM-ENT-008 acceptance_suite: FAS-CRM-ENT-02 --- # Organization Records ## Overview Organization Records represents the bodies an association works with: member firms, chapters, schools, and other organizations. Their identity continues even when the people representing them change. Staff can attach organizational information to the body itself and connect people through affiliations. Organizations can also sit within a hierarchy. A chapter's parent identifies its place beneath a national body, while derived ancestry lets readers understand the wider structure without maintaining a separate list of ancestors on every record. ## Why It Exists Our reading is that an association needs to keep a member firm or chapter distinct from the people representing it. Harbor West Chapter remains the same body when its chair resigns and another officer joins. If its name and address exist only on the departing chair's contact, staff lose a shared reference or carry conflicting copies into the next person's record. A separate organization gives those people a common party to name. A parent relationship also answers where the chapter sits in the association's structure, without making every representative's employment change a hierarchy change. This structure must remain interpretable after a parent move: a loop would make ancestry and descendant discovery unreliable. The capability therefore explains the organization's identity and hierarchy together, while individual affiliations and compliance assessments remain elsewhere. ## Who Uses It The CRM Editor creates organizations and records their parent relationships. The CRM Reader inspects names and organizational context. The Data Importer establishes organizations through authorized integrations. The CRM Administrator maintains organization classifications and safeguards, while the CRM System derives ancestry and maintains compliance information under the separate compliance capability. ## How It Works Staff enter an organization's name, classification, contact information, and optional parent. Rhythm checks that referenced classifications and parents belong to the workspace, establishes the organization's identity and number, and stores its owned information. Logo preparation happens before the record write can succeed. A later read derives ancestry from the current parent chain. Moving a parent therefore changes a descendant's reported ancestry without requiring staff to resave that descendant. The hierarchy refuses moves that would create a cycle, including conflicting concurrent moves. The console supports creation; the formal contract retains the milestone boundary that existing organization editing uses the service. The coordinator first decides whether the organization is an independent body already on file. A name identifies it to staff; its assigned number and durable identity distinguish it from another body with a similar name. Classification, address, phone and parent describe that body. A Chapter type does not itself attach the chapter to a national organization: the parent relationship supplies that placement. Conversely, a parent relationship does not make everyone in the chapter an employee of the national body; affiliations answer that different question. Before writing, the service checks the name and referenced organization type and parent. A parent from another workspace or an unknown parent produces a refusal, not a new organization or an unparented fallback. Logo preparation is another prerequisite. If the selected logo cannot be made permanent, the request fails rather than storing a broken image selection. Contact and organization numbers come from separate counters; a caller cannot force the organization's number through its payload, and gaps after refused work are possible. For a later hierarchy change, the caller reads the existing organization and submits the changed parent under the record-save contract. The ancestry returned afterwards is derived from that current chain, nearest ancestor first. The caller does not repair each descendant or supply an authoritative ancestry list. A move underneath the organization's own descendant is rejected. Database enforcement also covers two opposing moves made concurrently, so separately plausible requests cannot together leave a loop. The recorded console boundary matters here: creation is available to staff, while this existing-record edit is described through the service rather than promised as a completed console editor. ## Examples A national trade association records Harbor National and Harbor West Chapter, selecting the national body as the chapter's parent. Reading the chapter identifies the national body as its ancestor. If staff later move the chapter beneath a regional council, the next descendant read reflects that placement without a separate ancestry repair. Harbor National has Harbor Regional Council beneath it, and Harbor West Chapter initially sits directly beneath the national body. The coordinator creates the chapter with its own name, address and website, then opens the record to inspect the saved identity, parent and derived domain. A mistaken parent identity is refused; she selects the actual national body and retries the corrected request. In November the association places the chapter under the regional council. An authorized service caller reads the chapter's current version and changes its parent. The next chapter read identifies the council first and the national body above it, while the chapter retains its identity and number. If another caller tries to place the council under the chapter, that opposing move is rejected after the first move commits. A descendant of the chapter needs no independent save to report the new ancestry. Staff can continue using the same organization in affiliations while reviewing the changed hierarchy. ## Decisions and Tradeoffs Our reading is that storing one parent and deriving ancestry avoids turning a restructuring into a collection of manual descendant repairs. Storing copied ancestor lists would appear to simplify a read but could leave different descendants reporting different structures after a move. Cycle checks preserve the possibility of answering ancestry and descendant questions at all; concurrency enforcement closes the gap left by two separate validations. Independent identities preserve a body's continuity when its name, representatives or placement changes. They do not establish that repeated organization creation has the contact creation path's retry guarantees. The service-only edit boundary also prevents readers from mistaking implemented persistence for a finished staff experience. These are interpretations of the contracts, not a recorded account of why a particular person chose the design. ## Scope and Boundaries This feature establishes organizations and their hierarchy. Affiliations and Roles owns who is connected to them, and Organization Compliance owns the calculated assessment of role coverage. Platform supplies file storage and metadata definitions. Other applications own memberships, invoices, and program records that reference organizations; those records do not become part of organization creation. ## Outcomes Staff can recognize an organization independently of its representatives and understand its place within a wider structure. The Organization Records acceptance suite connects creation, reading, and hierarchy behavior. It provides the verification contract for those outcomes, including refused parent choices, rather than promising a complete console editor beyond the recorded milestone boundary. ## Its Capabilities Establish an organization and its hierarchy creates the independent organization identity, records its parent, and derives ancestry when staff read it. Its organization validation and concurrency safeguards keep that hierarchy usable as a shared reference for affiliations and for the current-affiliate discovery journey described under Contact Records.