Manual Account Entry and Import#

Manual accounts are accounts with no linked banking provider — they have no Plaid, SimpleFIN, or other account_providers record. The Account model's manual scope identifies them by the absence of those associations. There are two primary paths for getting data into a manual account:

1. UI-driven manual entry — create an account with an opening balance and enter transactions directly.
2. File-based import — upload a file in one of several supported formats.

After any data change, balance history is recalculated using the forward strategy (vs. the reverse strategy used by linked/synced accounts).

Manual Account Creation (UI Entry)#

The AccountableResource concern provides the shared create/update actions for all account type controllers (Depository, Investment, CreditCard, Loan, Property, Vehicle, etc.).

Creation flow:

• opening_balance_date is read from the form; defaults to 2 years ago if absent 1.
• Calls Account.create_and_sync(params, opening_balance_date:) 2, which creates an opening-anchor valuation via Account::OpeningBalanceManager and then enqueues a balance sync.
• Permitted params: name, balance, currency, subtype, opening_balance_date, institution_name, institution_domain, notes, exclude_from_reports 3.

Balance updates on an existing account go through Account#set_current_balance, which creates a new reconciliation Valuation entry rather than mutating the original opening anchor 4.

File Import System#

Base Model#

Import is the polymorphic base class for all import types. It handles CSV parsing (with configurable column separator, number format, and encoding), date-format detection, duplicate row skipping, and the publish/revert lifecycle 5:

Lifecycle: upload → Import::Preflight validation → configure column mappings → publish_later → ImportJob calls import! → family.sync_later 6. Reverting destroys all accounts and entries the import created, then re-syncs 7.

Controllers: ImportsController drives the full publish/revert lifecycle; Import::UploadsController handles file uploads and format validation (QIF requires an account selection step; SureImport triggers preflight validation).

Mapping models: Import::AccountMapping, Import::CategoryMapping, Import::Row (signed amount conversion, tag parsing), Import::Preflight (pre-flight validation without persisting).

Supported Formats#

Chunked NDJSON (SureImport)#

Large NDJSON exports are split into chunks. ImportSession orchestrates multi-chunk uploads: it validates sequence order, verifies SHA-256 checksums per chunk, enforces total row count limits, and tracks readback verification (not_verified → matched / mismatch / failed). ImportSessionJob publishes each chunk in sequence.

Forward-Strategy Balance Calculation#

Manual accounts use the forward strategy for balance history. In Account::Syncer#perform_sync, the strategy is chosen as:

• linked account → :reverse — start from today's provider-reported balance and work backward
• manual account → :forward — start from the opening anchor and project forward

8

Balance::ForwardCalculator iterates day-by-day from calc_start_date to calc_end_date, applying daily transaction flows and market-value changes to carry the balance forward 9.

Valuation overrides: If a Valuation entry exists for a date (e.g., a user-entered reconciliation), that day's ending balance is taken directly from the valuation rather than being derived from flows 10.

Incremental mode: When window_start_date is provided, the calculator seeds from the persisted Balance row for window_start_date - 1 instead of replaying from the opening anchor. It falls back to full recalculation when 11:

• No prior persisted balance exists for that date
• The prior balance has a non-zero non-cash component (investment holdings are always fully rematerialized)
• The account has multi-currency entries or a foreign currency

Balance::Materializer orchestrates the forward calculation, persists the resulting Balance rows, and updates the account's balance column. Manual accounts do not use a current_anchor — their current balance is derived from the running forward calculation 12.