Check Deposit Manager

Component File: src/features/deposits/components/CheckDepositManager.tsx Route / navigation: Path /fund-accounting, Zustand accountingTool = check-deposit (via Deposits sub-hub). See 00-ACCOUNTING-HUB.md. Access Level: Parent Org and Fund Users with Accounting access (position-based) Last Updated: April 13, 2026

Recent Fixes

Submit rollback + edit re-entry safeguards (Apr 13, 2026)

Pre-finalize failures: Submit performs compensating rollback when failures occur after partial writes (void created JE when present, archive created pending deposit, or soft-void created donations if no deposit row exists yet).
Post-finalize safety: Once finalizeDeposit succeeds, later non-critical errors no longer trigger rollback logic that could unwind an already-posted deposit.
Edit duplicate guard: Re-entry mode excludes source-batch donation IDs from duplicate checks so corrected reposts are not blocked by the rows being replaced.
Source batch archive: After successful re-entry submit, the original pending source batch is archived to avoid stale duplicate drafts in Deposit History.

Calculator-style amount entry (Apr 9, 2026)

Check Deposit is included in the live fund-accounting calculator-input rollout.
The editable Amount field now accepts arithmetic expressions such as 152.48+157.82, subtraction, multiplication, and division; the result commits to the numeric amount on blur or Enter.
Invalid expressions do not replace the previously committed amount with 0.

Donation Revenue default for deposit intake (Apr 8, 2026)

Rule: Check deposits require an effective donations_revenue default before a check can be confirmed to the batch or the batch submitted. A fund may use its own override or inherit the parent organization’s mapping through get_default_account_id.
Client: getDefaultAccountId() resolves the effective mapping with parent fallback. Revenue on each check is the user-selected / resolved revenue account tied to that mapping; there is no silent fallback to the first revenue account in the chart.
Multi-fund batches: Submit validates every selected fund has an effective Donation Revenue default available for deposits. The Complete step shows a warning and Open Account Defaults, which navigates to Administration → Chart of Accounts with { accountDefaultsTab: 'defaults' }. Submit is disabled while per-fund default queries are pending or any selected fund is missing a resolvable mapping.
Edit from Deposit History: Prefill restores saved line-level fund/account/purpose first, then falls back to effective defaults where needed; donation-linked taxability and DAF sponsor flags are also restored.
IFM data: Migration 20260408120000_ifm_donations_revenue_default_4000_02.sql sets IFM parent org donations_revenue to chart code 4000.02 when that account exists.
Tests / helpers: account-defaults.test.ts keeps the owned-only helper covered for other override-only flows; deposit intake now uses the shared helpers in regularDepositTaxDefaults.ts to resolve effective revenue defaults without first-revenue fallback.

`createDonation()` DAF column alignment (Apr 2026)

DAF checks already pass method: 'daf' and isDafGift: true from CheckDepositManager.
The shared client createDonation() normalizes DAF vs non-DAF columns on insert for all callers.
New enforcement (Jun 2026): non-interfund DAF donations now require daf_sponsor_id at both app and schema layers (chk_donations_daf_sponsor_required, migration 20260615120000_enforce_daf_sponsor_and_memtx_deposit_requirements.sql).

DAF sponsor reuse on successive captures (Apr 2, 2026)

Problem: Same as Regular Deposit — users entering many DAF checks re-selected sponsor on every new scan.
Behavior: A ref (lastDafForNextCaptureRef) stores DAF fields from the check confirmed to the batch and from the last check in a successful submit.
Hardening (Jun 2026): Sticky sponsor reuse is now conditional. OCR/heuristic detection still wins first (suggestDafSponsor), but fallback sticky reuse only applies when the current payer still looks DAF-related (keyword hit) or has strong normalized token overlap with the previous payer. This prevents accidental carryover to unrelated checks.
Scope guard: Sticky DAF state is cleared when the active selected fund context changes.
Files: CheckDepositManager.tsx (dafFieldsForNewCheckCapture helper)

Standardized donor duplicate guard (Apr 2, 2026)

Check Deposit now uses shared guard logic from src/lib/donationEntryGuards.ts (runDonationDuplicateGuard + shared block message builder).
High-confidence duplicates (same org + amount + date + payer, and check number when present, matched through existing deposit_items) are hard-blocked before posting.
This guard logic is shared with Regular Deposit and Manual Add Donation (Record mode) for consistent behavior.
Files: CheckDepositManager.tsx, donationEntryGuards.ts

PDF check import — page picker + OCR (Mar 27, 2026)

Behavior: File upload accepts PDF as well as images. Choosing a PDF opens `PdfPagePickerDialog` (shared component): thumbnail grid (`ScrollArea` with bounded height so many pages scroll), Select all / Clear, Continue (import selected pages), and optional Done — pick more later (keeps the File in memory so the user can reopen the picker without re-uploading). Cancel closes without importing. Each selected page becomes one `CheckData` row (same as adding separate photos); pages are rasterized with PDF.js (src/lib/pdfClient.ts), then OCR runs with bounded concurrency (mapWithConcurrency + scan-receipt). Submit still uses `uploadReceiptImage()` → JPEG in the receipts bucket.
Apr 10, 2026 fix: PDF import no longer blocks the page import itself when the current header context cannot resolve a concrete donations_revenue account up front. This now matches the photo-import flow: pages can still be imported into the draft batch, and Donation Revenue enforcement happens later when the user confirms a check or submits the batch. CheckDepositManager now resolves the effective default account with the same shared helper used by RegularDepositManager, avoiding false "configure Donation Revenue" errors when the mapping exists but was not resolved into the current account list yet.
Preview: Check thumbnails and zoom dialog use `AttachmentPreview` (replaces the old ResolvedCheckImage helper) so `.pdf` storage paths or PDF signed URLs can render in an iframe when needed.
Files: CheckDepositManager.tsx, PdfPagePickerDialog.tsx, AttachmentPreview.tsx, pdfClient.ts, ocrUtils.ts, migration 20260327120200_receipts_bucket_allow_pdf.sql, STORAGE-BUCKETS.md, DEVELOPER-PLAYBOOK.md §44.

Tranched multi-fund deposit (one slip, many funds) (Mar 27, 2026)

Behavior: Submitting selected checks creates one deposits row for the whole batch. If the batch includes more than one fund and a parent organization exists in entity mapping, deposits.organization_id is the parent org UUID; each check still posts donations and GL credit lines to its own fund (fundId / organization_id per line). Cash debits use the parent org’s default checking (same as other parent-level operations). A single compound journal entry spans all lines (createJournalEntry with jeAnchorEntityId = parent when multi-fund).
Deposit History: get_deposit_history_page includes a deposit when p_org_id matches either the deposit header org or any linked donation’s organization_id, so fund-scoped users still see tranched batches that include their checks.
Memorized transactions: One memorized template per submit when enabled; cash line uses admin-fund organization_id when multi-fund; revenue lines set organization_id per check fund.
Files: CheckDepositManager.tsx, RegularDepositManager.tsx, migration 20260327200000_deposit_history_tranched_visibility.sql, 17-DEPOSIT-HISTORY.md.

Summary step: check image + edit affordance (Mar 23, 2026)

Problem: After loading a deposit for edit, the summary card used <img src={check_image_url}> but persisted values are storage paths in the private receipts bucket — the browser cannot load them without a signed URL (same as Deposit History). Edit from summary was only possible indirectly (no pencil control).
Fix: Shared `AttachmentPreview` uses getReceiptImageUrl() for non–data-URL paths (review, summary thumbnails, zoom dialog). Summary cards include a pencil action that opens the Review Check Details step for that row; Cancel returns to the summary and restores the row if the user had opened Review from Edit.
Files: CheckDepositManager.tsx, AttachmentPreview.tsx, this doc.

OCR does not prefill payer / donor name (Mar 23, 2026)

Behavior: After a check scan, Payer name stays empty. Users must type or search/add the donor (or prospect) explicitly. Amount, date, check #, memo, bank, and purpose hints from OCR are unchanged.
Rationale: Avoid wrong donor links from noisy OCR; user-entered names are intentional.
Files: CheckDepositManager.tsx (processCheckOCR returns payerName: ''; removed resolvePayerNameFromOCR), this doc.

Edit from Deposit History: deposit date prefilled (Mar 23, 2026)

Report: Christy Nelson — when editing a check deposit from Deposit History, the Deposit Date field showed today instead of the saved deposit date.
Root cause: On editDepositId prefill, CheckDepositManager mapped deposit.deposit_date onto each check line’s date but never called setDepositDate(), so depositDate state stayed at its initial value (toLocalDateString(new Date())).
Fix: After building prefilled checks, set deposit date state from deposit.deposit_date (normalize YYYY-MM-DD from ISO strings).
Files: CheckDepositManager.tsx, this doc.

Check OCR Donor + Purpose Mapping Fix (Mar 6, 2026)

Problem: The OCR contract returned payee (who the check is made out to), and CheckDepositManager mapped that value into payerName, which is later used for donor lookup/creation. This could create or link the wrong donor. Memo text was captured, but it was not used to suggest a purpose.
Solution:
scan-receipt now requests payerName (check writer/account holder) separately from payee
The frontend only maps donor data from payerName (or other writer/account-holder variants), never from payee
OCR memo text is preserved and used as a conservative purpose hint; if it matches an existing purpose name/description, that purpose is auto-selected, otherwise the check defaults to General
Donor/prospect search, purpose lookup, default revenue account lookup, and DAF sponsor lookup now follow the current check's entity rather than the global dropdown alone
Summary-step purpose labels now load per entity so multi-fund batches display correctly
Revenue JE credit lines now carry each check's purposeId and memo
Files Modified: supabase/functions/scan-receipt/index.ts, src/features/deposits/components/CheckDepositManager.tsx, documentation/pages/accounting/08-CHECK-DEPOSIT-MANAGER.md, documentation/frontend/DEVELOPER-PLAYBOOK.md

Selective Batch Submission (Mar 1, 2026)

Feature: Users can now choose which checks from a batch to include in a deposit, keeping the rest for a future deposit.
Problem: Previously, all checks in a batch were submitted together — there was no way to deposit a subset and retain the rest.
Solution:
Added selected field to CheckData interface (defaults to true)
Complete step now shows per-check checkboxes and a Select All/Deselect All toggle
Summary stats show "Selected / Total" count and "Selected Amount" vs "Batch Total"
Submit button dynamically shows "Submit N of M to Ledger" when a subset is selected
Submit handler filters to selected checks only; unselected checks remain in the batch and persist in localStorage
After submission, remaining checks stay in the batch with an info toast ("N checks remain in batch")
If remaining checks exist, the component stays on the complete step; otherwise it returns to capture
No database changes required — purely frontend logic
Files Modified: CheckDepositManager.tsx

Deposit Void/Delete Bug Fix (Feb 14, 2026)

Problem: Voiding or deleting a deposit did not clean up linked donations or journal entries. See 10-REGULAR-DEPOSIT-MANAGER.md for full details.
Impact on Check Deposits: Same fix applies — voidDepositBatch(), deleteDeposit(), and deleteDepositItem() in src/lib/db/deposits.ts are shared between Regular and Check deposit flows.
New UI: Deposit History now has Void/Delete actions (gated behind canWriteAccounting).

iOS Safari OCR Fixes + Entity Auto-Selection (Feb 10, 2026)

Root Cause: selectedEntity started as '' in Zustand store and was never auto-set for parent_org users on first load. getActualOrgId('') returned null, causing the edge function to reject with "Organization is required for OCR."
Fix (useEntityEnforcement.ts): Added useEffect that auto-selects the parent org entity when selectedEntity is empty after entities load. Covers all parent_org users.
iOS Safari hardening (imageUtils.ts):
Added canvas size guards: cap dimensions to 4096px per side and 16.7MP total area (Safari's hard limit)
Added blob.size > 0 check to catch silent toBlob failures
isIOSSafari() helper for detection
iOS Safari hardening (CheckDepositManager.tsx):
processCheckOCR() now wraps compressImage in try/catch with fallback to raw base64
Camera/file inputs reset value = '' after capture (fixes iOS Safari not firing onChange on re-capture)
Camera input accepts image/heic,image/heif explicitly

Parent Org Filtering (Dec 31, 2025; tranched batching Mar 27, 2026)

Per-check fund: Users still assign each check to a fund (parent org stays hidden from the fund dropdown in multi-org setups). The deposit header for a multi-fund batch is stored under the parent org when one exists, while GL credits remain fund-attributed (see tranched deposit note above).
Behavior:
In multi-org setups, the parent parent_org org is hidden from the per-check nonprofit dropdown
In single-org setups (standalone nonprofit), the org is shown regardless of type
The 'all' pseudo-entity is always excluded
Technical: Uses useMemo to filter entities by type, with special handling for single-org scenarios

Batch Persistence - localStorage (Dec 22, 2025)

Problem: Checks scanned in a batch were lost if user navigated away before submitting
Solution: Added localStorage persistence for check batches
Behavior:
Batch is automatically saved to localStorage as checks are scanned
On return to page, saved batch is restored with notification
Batches expire after 24 hours
"Clear" button allows users to discard saved batch
Batch is cleared from localStorage after successful submission
Technical: Uses localStorage with entity-specific keys (alignmint-check-batch-{entityId})
Note: Check images can be large; if localStorage quota is exceeded, persistence fails gracefully

Overview

The Check Deposit Manager streamlines the check deposit process with OCR (Optical Character Recognition) technology. Users can capture check images via camera or upload files, automatically extract check details, review and edit the information, and batch process multiple checks for deposit. This reduces manual data entry and speeds up the deposit workflow.

Shared “batch” workflow with Regular Deposit and reimbursements

The mental model matches [Regular Deposit](./10-REGULAR-DEPOSIT-MANAGER.md) and [Reimbursements](./07-REIMBURSEMENTS-MANAGER.md) (Submit tab): users accumulate lines into a working batch, then finish on a review / Complete step before posting to the ledger (or submitting for approval). Regular Deposit names the staging action Add to batch and jumps straight to that review step; check deposit reaches the same Complete step after Capture and per-check Review. Reimbursements use the same three-step Submit flow ending in Complete with a staged receipt batch. See Regular Deposit doc → *Canonical workflow: Add to batch → batch review (draft batch)* for the cross-surface nomenclature note (draft batch vs DB-backed Drafts tab).

UI Features

Workflow Steps

1. Capture Step:

2. Review Step:

3. Complete Step:

Camera capture button (mobile)
File upload button (desktop)
Multiple check capture
Image preview
List of captured checks
Edit check details
Remove checks
Add more checks
Deposit summary
Total amount
Check count
Finalize deposit

Check Capture Interface

PDF upload: Opens the page-picker dialog; user selects one or more pages; each page becomes a check line on the Complete step (batch import). Resume (stashed PDF): if the user closed the picker with Done — pick more later, a button reopens the same file without re-uploading.
Copy / i18n (shared with reimbursements): Capture tiles, format line, drag/drop hint, and OCR line use **common.json → captureUpload.*** (common:captureUpload.* in code). Check-specific OCR sentence remains `deposits.check.ocrHint`.
Camera Capture:
Live camera view (mobile)
Capture button
Auto-process with OCR
File Upload:
Drag-and-drop area
File browser
Multiple file selection
Supported formats: JPG, PNG, HEIC, HEIF, other image formats accepted by the browser

OCR Processing

Automatic extraction of:
Payer/donor name from the check writer or account holder (when visible)
Payee captured separately for OCR safety checks (not used for donor creation)
Check number
Amount
Date
Bank name (if visible)
Memo/notes
Purpose hint derived from memo text when it matches an existing purpose
Processing indicator
Manual override capability

Check Review Form

Check image preview
Payer Name (editable)
Check Number (editable)
Amount (editable)
Date (editable)
Revenue account/category selector
Purpose selector
Memo (editable)
Bank Name (editable)
Entity/Organization selection
Non-taxable checkbox (marks donation as not tax-deductible)
DAF gift toggle + sponsor selection
Confirm / cancel actions

Deposit Summary

Selected / total check count
Selected amount and batch total
Deposit date selector for cash and modified-accrual orgs
Per-check review cards with image, fund, account, purpose, and memo
Select all / deselect all toggle
Add more checks action
Memorized transaction option
Submit selected checks to ledger

Data Requirements

Check Data (During Capture)

id (uuid) - Temporary ID during capture
image (data URL) - Check image
payer_name (string) - Check writer/account holder used for donor lookup
check_number (string) - Check number
amount (decimal) - Check amount
date (date) - Check date
account (account object) - Revenue account used for the credit side of the batch JE
purpose_id (uuid, nullable) - Purpose auto-matched from memo or defaulted to General
memo (string) - Check memo/notes
bank_name (string) - Bank name
entity_id (uuid) - Organization

Deposit Data (Final)

id (uuid) - Unique identifier
organization_id (uuid) - Organization owner
deposit_type (string) - 'check', 'cash', 'mixed'
deposit_date (date) - Date of deposit
bank_account_id (uuid) - Account being deposited to
total_amount (decimal) - Total deposit amount
check_count (integer) - Number of checks
status (string) - 'pending', 'deposited', 'cleared'
deposited_by_id (uuid) - User who created deposit
deposit_slip_url (string, nullable) - Uploaded deposit slip
notes (text, nullable) - Additional notes
created_at (datetime) - When created
updated_at (datetime) - When updated

Deposit Item Data

id (uuid) - Unique identifier
deposit_id (uuid) - Parent deposit
donation_id (uuid, nullable) - Linked donation (if applicable)
item_type (string) - 'check', 'cash'
amount (decimal) - Item amount
check_number (string, nullable) - Check number
payer_name (string, nullable) - Payer name
check_image_url (string, nullable) - Check image URL
memo (text, nullable) - OCR/manual memo for the check
created_at (datetime) - When created
updated_at (datetime) - When updated

Data Mutations

Process OCR: supabase.functions.invoke('scan-receipt')
Create Donation: createDonation() for each selected check
Create Deposit: createDeposit() with linked deposit_items
Finalize Deposit: finalizeDeposit() after JE creation
Create Journal Entry: createJournalEntry() for the batch
Upload Check Images: uploadReceiptImage(..., 'checks')

Service Contracts & Data Layer

OCR Edge Function

Function: scan-receipt Invocation: supabase.functions.invoke('scan-receipt', { body: { imageBase64, type: 'check', organization_id } })

Check response shape:

interface CheckOCRResult {
  payerName?: string;
  payee?: string;
  amount?: number;
  date?: string;
  checkNumber?: string;
  memo?: string;
  bankName?: string;
}

Behavior:

payerName is the intended donor/payer source and should represent the check writer/account holder
payee is returned for OCR validation/safety only and should not be used for donor creation
memo is preserved and used as a purpose hint
If OCR cannot identify the check writer confidently, payerName is returned as an empty string for manual review

Frontend Submission Flow

1. Scan image with scan-receipt 2. Populate currentCheck with OCR suggestions (revenue account only when an org-owned donations_revenue mapping exists and matches a revenue account on the fund’s chart) 3. Auto-match purpose from memo when possible, otherwise default to General 4. Resolve or create donor from payerName 5. Gate: Owned donations_revenue per fund + valid revenue account on each selected check 6. Create donation record for each selected check 7. Create deposit batch and linked deposit_items 8. Create compound JE (tranched multi-fund when applicable), with one credit line per check carrying purposeId and memo 9. Finalize deposit

Key Frontend Functions

// src/features/deposits/components/CheckDepositManager.tsx
processCheckOCR(imageDataUrl): Promise<Partial<CheckData>>
handleFileCapture(file: File): Promise<void>
handleSubmitDeposit(): Promise<void>

Key Data-Layer Functions

// src/lib/db
createDonation(...)
createDeposit(...)
finalizeDeposit(depositId)
createJournalEntry(...)
fetchPurposes(entityId, includeInactive?)
findOrCreateDonorByName(payerName, entityId)

Integration Note

This manager does not use a bespoke internal REST layer or mock OCR flows. The authoritative implementation is the Supabase edge function and DB helper flow documented above.

Authentication & Authorization

Required Permissions

deposits:read - View deposits
deposits:write - Create and update deposits
deposits:delete - Delete deposits
deposits:finalize - Finalize deposits

Role-Based Access

Admin: Full access to all operations
Manager: Can create, finalize, view all
Staff: Can create and view own
Volunteer: No access

Business Logic & Validations

Frontend Validations

At least one check required
Amount must be greater than 0 for each check
Payer name required
Fund required
Org-owned Donation Revenue default for the check’s fund (and for every fund represented in the selected batch) — see Recent Fixes → Apr 7, 2026
Revenue account required on each check (account.id) before confirm/submit
Purpose required
DAF checks require a selected DAF sponsor before submit
Deposit date required
Image required for each check

Backend / Service Validations

scan-receipt requires a valid JWT and organization_id
OCR scanning is tier-gated via guardExternalServiceAccess
OCR request times out after 30 seconds on the client and retries once
Amounts are sanitized before use (e.g., "1,600.00" → 1600)
Deposits without a configured default checking account cannot be submitted
Parent-org users must still submit deposits to a deposit-eligible entity/fund

Business Rules

Each submitted check creates a donation record before the deposit batch is created
If submit fails before finalize, staged donations/deposit are rolled back; after finalize, the posted deposit remains authoritative
Successful re-entry submissions archive the original pending source batch
Finalized deposits create journal entries automatically
Check images are compressed client-side, then stored securely
OCR results are suggestions, manual review required
The payee should never be used as the donor source for check scanning
Memo text may auto-select a purpose, but the user can always override it
Multiple checks can be batched in a single deposit
Cleared status updated via bank reconciliation

State Management

Local State

step - Current workflow step ('capture', 'review', 'complete')
checks - Array of captured checks
currentCheck - Check being edited
isProcessing - OCR processing state
depositDate - Deposit date
currentCheck.donorId / currentCheck.donorSource - Donor linkage metadata from shared donor picker
memorizeEnabled, memorizeName, memorizeSchedule, memorizeNextDate - Memorized transaction controls
viewCheckOpen - Check image viewer state

Donor Search Standard

Payer lookup uses shared `DonorSearch` (src/components/shared/DonorSearch.tsx) instead of local Popover + Command state.
DonorSearch calls searchDonorsAndProspects() (RPC-backed search_donors_and_prospects_autocomplete) with fund scope.
Shared autocomplete config is enforced centrally: 2-character minimum, 150ms debounce, 30s stale cache.

Global State

selectedEntity - Current organization

Dependencies

Internal Dependencies

src/lib/db - Donation, deposit, journal entry, purpose, donor, account-default, and DAF sponsor helpers
src/lib/entityMapping.ts - getOrgId, getActualOrgId, isMappingInitialized
src/lib/imageUtils.ts - compressImage, uploadReceiptImage
Shared UI components (Card, Button, Dialog, AccountSearch, DatePicker, etc.)

External Libraries

lucide-react - Icons
@tanstack/react-query - Data fetching and caching
@supabase/supabase-js - Edge function invocation
sonner - Toast notifications
OpenRouter-backed OCR via Supabase Edge Functions

Error Handling

Error Scenarios

1. Network Error: Show toast "Unable to process deposit", retry 2. OCR Failed: Show error "Failed to read check. Please enter manually." 3. Camera Access Denied: Show error "Camera permission denied" 4. Invalid Image: Show error "Invalid image format" 5. Upload Failed: Show toast "Image upload failed" 6. Cannot Edit: Show error "Cannot edit finalized deposits" 7. Permission Error: Show toast "You don't have permission"

Loading States

OCR Processing: Show spinner with "Processing check..." message
Image Upload: Runs during submission when check images are stored to Supabase storage
Finalize Deposit: Submission button shows loading state while donations/deposit/JE are created
Camera Capture: Processing indicator

Implementation Notes

Purpose auto-assignment is conservative: exact purpose-name match first, then description/name substring match, then General
Selected checks are grouped by entity before creating deposits and journal entries
On cash/modified-accrual basis, the batch JE uses the deposit date; on accrual basis, it uses the check date
The batch summary resolves purpose names per entity to avoid cross-fund display drift

Ready to Get Started?

See how Alignmint can simplify your nonprofit's operations. Schedule a free demo with our team and we'll walk you through everything.

Schedule Your Free Demo Log In to Alignmint

Questions? Email us at steven@getalignmint.org