Transaction Management#

Transaction management in Sure covers two intersecting concerns: a unified form that handles income, expense, and transfer entry in a single UI surface, and an attribute-locking system that protects manually created or edited transactions from being overwritten by automated account syncs.

Unified Form Architecture#

The transaction creation form (_form.html.erb) 1 is shared across all three transaction types — Expense, Income, and Transfer — via a three-tab segmented control rendered from _transaction_type_tabs.html.erb.

How type switching works:

• Expense and Income tabs are handled client-side by the Stimulus TransactionTypeTabsController. Clicking a tab calls selectTab, which updates the hidden nature field 2 to either "outflow" (expense) or "inflow" (income) without a page navigation. The active segment styling is also toggled client-side 3.
• The Transfer tab is a plain link to new_transfer_path 4 — transfers use a separate form and are routed to Transfer::Creator rather than TransactionsController.

How nature drives amount sign:

On submission, TransactionsController#entry_params reads the nature value and converts the unsigned form amount into a signed amount before saving 5:

• "inflow" → negative amount (income/credit)
• "outflow" → positive amount (expense/debit)

The form also includes a collapsible Details section for merchant, tags, and notes 6, and an exchange-rate widget for multi-currency transactions 7.

Permitted entry params (create/update): name, date, amount, currency, excluded, notes, nature, entryable_type, with nested entryable_attributes for category_id, merchant_id, kind, investment_activity_label, exchange_rate, and tag_ids 8.

Transfers are not created through TransactionsController. They are built by Transfer::Creator, which creates a matched pair of Transaction records — one outflow on the source account and one inflow on the destination — inside a single database transaction 9.

Attribute Locking: Protecting Manual Transactions from Sync Overwrites#

Every time a user creates or edits a transaction, the controller calls three methods on the Entry 10:

The same three calls are made on update 14 and update_tags 15.

protected_from_sync? returns true if any of three flags are set 16:

• excluded? — entry is soft-deleted from reports
• user_modified? — user made a manual edit
• import_locked? — entry was created via file import

Enrichable concern (on both Entry and Transaction / entryable) stores lock state in a locked_attributes JSONB column keyed by attribute name → ISO8601 timestamp 17. The lock_saved_attributes! on Entry delegates to both the entry row and its entryable 18.

Unlocking: Users can explicitly re-expose a transaction to future syncs via the unlock action 19, which calls unlock_for_sync! — clearing user_modified, import_locked, and all locked_attributes on both the entry and its entryable in a single transaction.

Key Files#