Local Association
Data Entity
Description
Represents a local chapter or branch within a parent organization. Local associations are the operational unit to which peer mentors and coordinators are assigned. They belong to a geographic region and sit beneath an organization in the multi-tenant hierarchy. NHF alone has ~1,400 local associations across 9 regions and 12 national federations.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key — stable surrogate identifier for the local association | PKrequiredunique |
organization_id |
uuid |
Foreign key to the parent organization (tenant). All data scoped to this org. | required |
region_id |
uuid |
Foreign key to the geographic region this local association belongs to. Nullable for top-level associations or orgs without regional structure. | - |
name |
string |
Official display name of the local association (e.g., 'Oslo og Omegn Lokallag') | required |
short_name |
string |
Abbreviated name used in compact UI contexts and reports | - |
external_id |
string |
Identifier used in the organization's external systems (e.g., HLF Dynamics portal, NHF member registry). Enables bi-directional sync and duplicate detection. | - |
status |
enum |
Operational status of the local association | required |
municipality_code |
string |
Norwegian municipality code (kommunenummer, 4 digits) for geographic matching and Bufdir reporting | - |
contact_email |
string |
Primary contact email for the local association, used for coordinator notifications | - |
contact_phone |
string |
Primary contact phone number for the local association | - |
member_count |
integer |
Approximate number of peer mentors currently associated with this local association. Denormalized for dashboard KPI performance; refreshed by background sync. | - |
allow_duplicate_membership |
boolean |
When true, peer mentors may belong to this association AND another within the same org. NHF-specific — some peer mentors belong to up to 5 local associations. | required |
metadata |
json |
Freeform key-value store for organization-specific fields (e.g., internal codes, district labels, Bufdir sub-identifiers) without schema changes | - |
created_at |
datetime |
Timestamp of record creation (UTC) | required |
updated_at |
datetime |
Timestamp of last modification (UTC) | required |
deleted_at |
datetime |
Soft-delete timestamp. NULL = active. Set instead of hard-deleting to preserve audit trail and historical activity data. | - |
Database Indexes
idx_local_associations_organization_id
Columns: organization_id
idx_local_associations_region_id
Columns: region_id
idx_local_associations_org_external_id
Columns: organization_id, external_id
idx_local_associations_status
Columns: organization_id, status
idx_local_associations_municipality
Columns: municipality_code
idx_local_associations_deleted_at
Columns: deleted_at
Validation Rules
name_not_empty
error
Validation failed
municipality_code_format
error
Validation failed
contact_email_format
error
Validation failed
status_transition_allowed
error
Validation failed
external_id_no_whitespace
error
Validation failed
metadata_valid_json
error
Validation failed
Business Rules
tenant_isolation
A local association always belongs to exactly one organization. All reads and writes must be scoped to the calling user's organization_id. Global admins may read across tenants for system management but may not modify org operational data.
unique_external_id_per_org
Within a single organization, external_id must be unique so that portal sync (HLF Dynamics, NHF member registry) never creates duplicate local associations during import.
inactive_association_blocks_new_memberships
Peer mentors may not be assigned to a local association whose status is 'inactive' or 'suspended'. Existing memberships are preserved but flagged.
soft_delete_only
Local associations must never be hard-deleted. Set deleted_at to preserve referential integrity with historical activities, Bufdir reports, and audit logs. All queries must filter WHERE deleted_at IS NULL by default.
multi_membership_requires_flag
A peer mentor may belong to multiple local associations only when allow_duplicate_membership = true on at least one of the target associations. Applies to NHF where some peer mentors cover up to 5 local associations. Without the flag, a second membership assignment is rejected.
region_must_belong_to_same_org
If region_id is set, the referenced region must itself belong to the same organization as the local association. Cross-tenant region assignment is forbidden.
member_count_cache_refresh
The denormalized member_count field must be refreshed whenever a user_roles record linking a peer mentor to this association is created, updated (status change), or deleted. Keeps KPI dashboards accurate without expensive live COUNT() queries.
bufdir_municipality_required_for_reporting
municipality_code must be populated before the local association can be included in a Bufdir export. If absent, the export service emits a warning and excludes the association's data from the Bufdir report.