Banking Provider Integration#

Sure integrates with banking providers — currently EnableBanking (European Open Banking / PSD2) and Akahu (New Zealand) — through a shared, consistent architecture. Each provider follows the same structural pattern: a provider Item (credential holder) → intermediate Account table (provider-specific account mirror) → Sure's internal Account record. Syncing is handled uniformly by the Syncable mixin and SyncJob background queue.

Data Model: Items, Provider Accounts, and the Account Link#

Each provider connection is represented by an Item record owned by a Family:

Items do not link directly to Sure accounts. Instead, provider-specific intermediate tables hold the raw account mirror:

The binding to Sure's internal accounts table goes through a separate account_providers polymorphic join table 5, so the same internal account can never be linked to two provider accounts of the same type (enforced by a unique index on [account_id, provider_type]). The full traversal is:

AkahuItem / EnableBankingItem
  → [akahu_accounts / enable_banking_accounts] (has_many)
  → [account_providers] (has_one, polymorphic)
  → Account (internal record)

Both items expose has_many :accounts, through: :akahu_accounts 6 / through: :enable_banking_accounts 7.

Syncable Mixin#

Both AkahuItem and EnableBankingItem include Syncable (alongside Provided, Unlinking, and Encryptable) 8 9.

Syncable (app/models/concerns/syncable.rb) adds a has_many :syncs polymorphic association and the key method sync_later:

• Deduplication: Inside a database transaction with a row lock, sync_later checks for any visible (< 5 min old, non-terminal) Sync. If one exists, it expands the date window rather than creating a duplicate 10.
• Enqueueing: Only if no recent sync exists is a new Sync record created and SyncJob.perform_later(sync) called 11.
• Delegation: perform_sync and perform_post_sync delegate to self.class::Syncer 12, so each model supplies its own Syncer inner class.

Sync State Machine (Sync model)#

The Sync model (table: syncs) is polymorphic (syncable_type / syncable_id) and uses AASM for state management 13:

States: pending → syncing → completed / failed / stale

• Syncs older than 24 hours that are still incomplete are marked stale by a cleanup cron 14.
• The visible scope (< 5 min old + incomplete) is what Syncable#sync_later checks to prevent duplicates 15.
• Syncs are hierarchical: an Item sync is the parent; each linked Account sync is a child. The parent only finalizes once all children complete 16.
• Sync.for_family uses reflection to automatically discover all *_items associations on Family that include Syncable, so no manual registry is needed when adding a new provider 17.

SyncJob#

SyncJob runs on the high_priority queue and calls sync.perform. It accepts an optional balances_only: flag injected as a singleton method on the Sync instance (rather than persisted) to adjust sync behavior at runtime without a schema change 18.

Provider Syncers#

Each provider supplies a Syncer inner class following the same phased contract:

AkahuItem::Syncer (app/models/akahu_item/syncer.rb) phases:

1. Import latest data from Akahu API (import_latest_akahu_data)
2. Identify linked vs. unlinked accounts; set pending_account_setup flag 19
3. Process transactions via AkahuAccount::Processor 20
4. Schedule child Account syncs via schedule_account_syncs(parent_sync: sync) 21

EnableBankingItem::Syncer (app/models/enable_banking_item/syncer.rb) follows the same four phases but adds a session validation guard — if the session is expired the item is immediately marked requires_update and the sync aborts cleanly.

Both syncers include SyncStats::Collector to attach structured stats (accounts total/linked/unlinked) to the Sync record.

Adding a New Provider#

The pattern to follow is:

1. Create {Provider}Item model — include Syncable — with has_many :{provider}_accounts and has_many :accounts, through: :{provider}_accounts.
2. Create the intermediate {Provider}Account model with has_one :account_provider and belongs_to :{provider}_item.
3. Implement {Provider}Item::Syncer with perform_sync(sync) and perform_post_sync.
4. Add has_many :{provider}_items to Family — Sync.for_family will pick it up automatically via the *_items reflection 17.