Organization
What It Models
An organization models a body that has an identity independent of its representatives: a member firm, chapter, school or national association. It owns organizational information and can provide shared contact-point sources to people. Harbor West Chapter remains the same body when its billing representative leaves.
Our reading is that independent identity keeps hierarchy and policy intelligible as people change. The organization’s type supplies allowed responsibilities, compliance expectations and presentation overrides, while its parent supplies structure. These are different concerns: organizational ancestry does not give staff security access, and CRM classification does not create financial or membership rights.
Identity and Attributes
An organization uses a workspace-scoped identity supplied by the client when unused, or generated by the service. Its staff-facing number comes from a separate organization counter beginning at 10000; allocation is service-controlled and spent numbers are not reused.
The table describes logical properties. Optional values can be absent; a required collection member is distinct from requiring the collection itself. Examples illustrate association information and do not establish new defaults. Service-owned values remain separate from fields that staff or integrations supply.
| Property | Meaning and writer | Constraints | Example |
|---|---|---|---|
| id | The continuing organization identity. Set by integration. | Unused workspace identity with the API identity grammar; generated when omitted. | harbor_west |
| number | The staff-facing reference independent of person numbering. Set by system. | Allocated by the organization counter beginning at 10000; spent numbers are not reused. | 10023 |
| name | The organization’s recognized name. Set by staff. | Nonblank trimmed text up to 200 characters. | Harbor West Chapter |
| acronym | A compact organizational label. Set by staff. | Optional trimmed text. | HWC |
| description | An explanation of the body’s work. Set by staff. | Optional trimmed text. | Western chapter of the engineering association. |
| notes | Operational notes about this body. Set by staff. | Trimmed optional text up to 10,000 characters. | Board meets on the first Tuesday. |
| status | The body’s business status, independent of archive and compliance. Set by staff. | Active by default; inactive and duplicate are also accepted. | active |
| organization type | The workspace classification supplying presentation and role policy. Set by staff. | Optional workspace reference; deletion of a referenced type is blocked. | Chapter |
| parent organization | The organization immediately above this one. Set by staff. | Workspace-local; cannot be self or create a descendant cycle. | Harbor National |
| ancestor organizations | The nearest-first chain of parent identities. Set by system. | Derived on read from the current hierarchy. | ["Harbor National"] |
| number of ancestors | The current depth below the root. Set by system. | Derived from the parent chain, rather than maintained on every descendant. | 1 |
| top-level organization | The root of the current hierarchy. Set by system. | Derived on read. | Harbor National |
| website | The organization’s web address. Set by staff. | Recognizable website or domain input can derive the other; unrecognized content remains input. | https://harbor.example |
| domain | The organization’s main internet domain. Set by staff. | Optional; can be derived from a recognizable website. | harbor.example |
| alternate domains | Additional internet domains associated with this body. Set by staff. | Optional string list. | ["harborwest.example"] |
| logo | The body’s display image. Set by staff. | Platform file handling prepares a permanent copy before the record transaction. | Chapter logo |
| flags | Optional labels retained on the organization. Set by staff. | String list; does not itself confer authority. | ["regional-office"] |
| tax exempt | The stored tax-exemption indicator. Set by staff. | Optional boolean; recording it is not a tax decision by this module. | true |
| region | The regional grouping assigned from the deciding address. Set by system. | Regions assigns it unless an explicit override is selected. | Western Region |
| override automatic region assignment | Whether an explicit regional assignment takes precedence. Set by staff. | Optional boolean. | true |
| The body’s recorded social-profile reference. Set by staff. | Optional trimmed text. | https://www.facebook.com/harborwest | |
| The body’s recorded social-profile reference. Set by staff. | Optional trimmed text. | @HarborWest | |
| The body’s recorded social-profile reference. Set by staff. | Optional trimmed text. | https://www.linkedin.com/company/harbor-west | |
| profile last updated | The stored profile review time. Set by staff. | Optional ISO timestamp. | 2026-10-20T14:00:00Z |
| addresses | Organization-owned typed postal sources. Set by staff. | One row per type and at most one preferred; linked contact rows can resolve these values. | Headquarters: 42 Harbor Avenue, Oakland, CA 94612, US |
| phone numbers | Organization-owned typed telephone sources. Set by staff. | One row per type and at most one preferred. | Main: +1 510 555 0100 |
| custom field values | Customer-specific extensions using Platform definitions. Set by staff. | Active organization definitions govern their declared data types. | Chapter charter date: 1998-06-01 |
| role compliance status | The last stored assessment of the type’s role coverage. Set by system. | Evaluator owns in compliance, not in compliance or absent; ordinary submitted values are ignored. | not in compliance |
| compliance violations | Ordered explanations of failed role-count bounds. Set by system. | Evaluator stores the role, configured bound and distinct holder count. | Billing Contact: minimum 1, actual 0 |
| version | The basis against which a later correction is compared. Set by system. | System advances it for a committed aggregate change; the caller echoes its read version. | 7 |
| lock | A customer restriction on mutation of this record. Set by system. | Dedicated lock actions choose no lock, deletes, or updates & deletes; ordinary saves retain it. | deletes |
| created at | When this identity is first stored. Set by system. | System timestamp; unchanged by later corrections. | 2026-10-20T14:00:00Z |
| created by | The actor responsible for creation. Set by system. | System attribution; a read can resolve its current display name. | Association coordinator |
| modified at | When the latest net change commits. Set by system. | A current-version no-op preserves this timestamp. | 2026-10-23T15:30:00Z |
| modified by | The actor or system responsible for the latest change. Set by system. | Recorded with the write context; system work can invalidate an open editor. | CRM system |
| archived at | Whether ordinary discovery and editing exclude this identity. Set by system. | Only archive and unarchive actions control the timestamp. | 2026-10-23T15:30:00Z |
| archived by | Who sets this record aside. Set by system. | Captured by the archive action and cleared on restoration. | CRM administrator |
| archive reason | The explanation for setting the record aside. Set by system. | Optional trimmed reason limited to 500 characters. | Firm closed |
| unarchive reason | The explanation for making the record available again. Set by system. | Optional trimmed reason limited to 500 characters. | Firm reopened |
Detail collection properties
Each entry belongs to its aggregate and has its own identity and system lock/stamps. These child properties explain the exposed value and source fields without creating independent domain objects. Organization values supply linked contact values only through the verified affiliation and source references.
| Property | Meaning | Example |
|---|---|---|
| organization addresses / address_type_id | The workspace address purpose, subject to one-per-type and applicability validation. | business |
| organization addresses / line1 | First postal delivery line. | 410 Association Way |
| organization addresses / line2 | Second postal delivery line. | Suite 200 |
| organization addresses / line3 | Additional postal delivery context. | Member Services |
| organization addresses / city | City in the postal value. | Columbus |
| organization addresses / state | State or province in the postal value. | OH |
| organization addresses / postal_code | Postal routing code. | 43215 |
| organization addresses / county | County supplied with the postal value. | Franklin |
| organization addresses / country | Country code; storage defaults to US. | US |
| organization addresses / latitude | Optional latitude supplied with the postal value. | 39.96 |
| organization addresses / longitude | Optional longitude supplied with the postal value. | -83.00 |
| organization addresses / time_zone_id | Optional time-zone identity associated with the location. | America/New_York |
| organization addresses / is_preferred | Preferred selection within this owner’s collection. | true |
| organization phone numbers / phone_number_type_id | The workspace telephone purpose, subject to one-per-type and applicability validation. | direct |
| organization phone numbers / phone_number | The telephone value; linked contact entries obtain their effective value from the organization source. | +1 614 555 0100 |
Policy and audit properties
These properties belong to the catalogue or safeguard facet named in the property column. They explain the implementation’s exposed policy and audit context without allocating another domain object. System attribution is read-only; catalogue policy is administered through its own permitted operation and is not changed by an ordinary record edit.
| Property | Meaning | Example |
|---|---|---|
| Organization type / id | Workspace classification identity used by the organization. | chapter |
| Organization type / name | Classification label shown to staff. | Chapter |
| Organization type / is_active | Availability for new selection without erasing retained classification. | true |
| Organization type / display_order | Optional ordering among classifications, with alphabetical fallback. | 2 |
| Organization type / restrict_contact_roles | Whether the allowed-role selection constrains assigned responsibilities. | true |
| Organization type / applicable_contact_role_ids | Workspace-local responsibilities selected for a restricted classification. | President, Treasurer |
| Organization type / enable_contact_role_compliance | Whether organizations of this classification have applicable role assessment. | true |
| Organization type / has_contact_role_compliance_options | Stored indicator accompanying configured policy options. | true |
| Compliance rule / role | The responsibility whose effective people are counted. | Treasurer |
| Compliance rule / minimum | Optional lower bound, validated with the other bound. | 1 |
| Compliance rule / maximum | Optional upper bound; zero can express that no holder is allowed. | 2 |
| Organization type / notify_contacts_of_compliance_violation | Whether a transition can prepare compliance communication. | true |
| Organization type / notification_contact_role_ids | Selected recipient responsibilities; absent and explicitly empty selections remain distinct. | President |
| Organization type / template reference | Platform-owned notification content referenced by the classification. | Chapter compliance notice |
Relationships
A child owns one optional parent reference, giving each parent potentially many children. The live chain must remain acyclic. A parent with children cannot be hard-deleted; archiving keeps that chain and its labels available. Reads derive ancestry rather than treating a parent move as a write to every descendant.
Affiliations are contact-owned and reference this organization. Any such reference blocks hard deletion regardless of dates. Organization addresses and phones can supply many linked contacts. Source removal disconnects those details in the removal transaction and records each affected person’s change. Protection and history remain attached to the organization, with revisions retained after ordinary deletion.
Lifecycle
The organization lifecycle separates active, inactive and duplicate business status from archive. A closed chapter can be archived while retaining its previous status, hierarchy and past representatives. Restoring it clears the archive overlay rather than inventing a new status or recreating its identity.
Compliance has a separate evaluator-owned lifecycle: no applicable policy, in compliance, or not in compliance. Changing type policy does not itself refresh every saved organization. Hard deletion checks all dependents, locks and protection and removes owned values only when those checks permit it.
Invariants
The organization’s continuing identity holds the hierarchy and people’s ties together while staff correct its name or classification. References must stay inside the workspace. A parent chain containing the organization itself cannot be traversed meaningfully, so hierarchy validation protects both the immediate move and the ancestry returned to readers. Deleting a referenced organization would remove the context for a child or a person’s employment history; the dependency boundary prevents that result.
Compliance belongs to the evaluator rather than an editable assertion by staff. A saved satisfactory result and an absence of applicable policy answer different questions. Type policy supplies the required roles; the evaluator examines people and dated responsibilities and stores the resulting violations. Keeping that authority separate prevents a profile save from making an unmet requirement appear satisfied.
Notice identity protects accepted submissions against repetition of the same transition. It does not prove delivery. Reprocessing likewise keeps one active scan cursor per workspace so concurrent workers cannot independently claim the same progress. A completed scan establishes that its stored work reached the end, while failed delivery or later policy changes remain separate concerns. Type references and role-policy dependencies keep the evaluator’s definitions meaningful rather than leaving labels that no longer identify a usable classification.
Permissions
The CRM authorization model separates workspace access from permission for a particular action. crm.organizations.read is granted to Administrator, Power User, Standard User, Read Only. crm.organizations.create is granted to Administrator, Power User, Standard User. crm.organizations.update is granted to Administrator, Power User, Standard User. crm.organizations.archive is granted to Administrator, Power User. crm.organizations.delete is granted to Administrator, Power User. crm.organizations.lock is granted to Administrator, Power User. crm.organizations.unlock is granted to Administrator, Power User. crm.organizations.history is granted to Administrator, Power User, Standard User, Read Only.
The service checks these grants at the corresponding operation boundary. Additional record guards still apply: grants do not bypass archive, customer restrictions, dependencies, version comparison or Rhythm protection. Read access and history access are separate; record history checks the applicable read authority as well as the history grant.
How It Is Stored and Shared
Entities owns the organization row, postal and telephone children, custom values and calculated violation rows. The organization save is the local transaction boundary. When a source detail disappears, database triggers disconnect linked people and capture their changes in that same transaction. Returned ancestry is assembled from the current parent chain.
Platform owns custom definitions, forms, layouts, files, notice templates and sending. Search and region consumers follow captured events; compliance notices have their own submission and delivery stages. A caller cannot infer refreshed search or delivered mail from the organization save response alone.
Open Design Questions
Organization creation does not have the contact create’s replay recognition. The live organization page has no general editor and no organization revision-history entry, despite available service operations. Compliance reevaluation after a type change depends on a later trigger or reprocess. Those implementation limits remain in the existing findings.