Core Concepts & Integrations

Core Concepts & Integrations

Understanding how QuickCatch intercepts notifications and securely interfaces with the YNAB API will help you maximize your real-time budget tracking efficiency.

⚙️ How It Works

QuickCatch operates as a background system integration tool. Instead of waiting for bank clears, it acts immediately on transaction events:

[Transaction Event] ──> [Android System Notification] OR [Gmail Alert]
                                    │
                                    ▼
                          [QuickCatch Listener]
                                    │ (Trust Verification & DNA Check)
                                    ▼
                         [Local Parsing Engine]
                                    │ (Extract: Merchant, Amount, Account)
                                    ▼
                         [Hybrid Payee Matching]
                                    │ (Map Payee & Category)
                                    ▼
                         [YNAB API Transmission]

1. Intercept: When a transaction occurs, your banking app creates a system notification, or your bank sends a notification email to your Gmail account.
2. Verify & Parse: QuickCatch’s StandardNotificationParser or EmailParserAggregator reads the payload. It applies a DNA Check to confirm it is a financial transaction (preventing spam or social notifications from triggering runs) and extracts the numeric value, currency, merchant name, and timestamp.
3. Local Sync: The details are stored in your local Room Database and matched against your custom rules.
4. Forward: QuickCatch initiates a background sync request via WorkManager to push the transaction to YNAB’s transactions API endpoint using secure HTTPS/TLS.

📖 Glossary

• Notification Listener Service: A native Android system utility that permits QuickCatch to read incoming push notifications from designated white-listed packages (e.g. com.chase.sig.android).
• Verified Source System: A multi-tiered security layer that determines whether a source is trusted to trigger transaction parses.
  • Tier 1 (Out-of-the-Box Whitelist): Pre-configured, verified packages like Venmo (com.venmo) or Citi (com.citi.citimobile).
  • Tier 2 (DNA Check): Unknown applications analyzed for transaction keywords (e.g. charged, spent, withdrawn, currency symbols).
  • Tier 3 (User Whitelist): Custom apps that you have manually verified and trusted.

1. Verify Source Option

2. Trust Source Settings Dialog

🔑 YNAB Connection Guide

QuickCatch uses the official YNAB API to sync transactions. Follow these steps to secure and authenticate the connection:

1. Open the QuickCatch application and navigate to Settings > YNAB Connection.
2. Tap Connect to YNAB.
3. A secure browser window will open, redirecting to the official YNAB login portal.
4. Enter your YNAB login credentials and review the requested permissions (Access to budgets, accounts, and transactions).
5. Tap Authorize. You will be automatically redirected back to QuickCatch via the custom protocol scheme quickcatch://.
6. The app will automatically retrieve and safely store the encrypted Access Token and Refresh Token in your device’s secure local storage.

YNAB Sync Optimization & Caching

To minimize startup delays and reduce network usage, QuickCatch implements metadata caching:

• 12-Hour Cache: Budget files, categories, and account list metadata are cached locally for 12 hours. Background sync workers and main app launches bypass redundant YNAB API calls, making execution significantly faster.
• Manual Refresh: You can force an immediate refresh of your YNAB metadata using the refresh button on the connectivity status page. A relative timestamp (e.g., “Last updated 5 mins ago”) displays the age of the currently cached data.

🔒 Security & Privacy Practices

[!IMPORTANT] No External Server Logging: QuickCatch is a local-first application. It communicates directly with YNAB and Google endpoints over HTTPS. Your banking credentials, notifications, tokens, and budget details are never sent to third-party servers.