Subscription and Recurring Payments

Relevant source files

The following files were used as context for generating this wiki page:

• frontend/app/(dashboard)/subscriptions/page.tsx
• frontend/components/subscriptions/subscriptions-client.tsx
• frontend/lib/actions/subscriptions.ts
• frontend/lib/actions/subscription-suggestions.ts
• frontend/components/subscriptions/subscription-detail-sheet.tsx
• frontend/components/subscriptions/subscription-form-dialog.tsx
• backend/postgres_migration/monitor_db.py

Introduction

The Subscription and Recurring Payments module is a core feature of the personal finance application designed to track, detect, and manage ongoing financial commitments. It allows users to monitor recurring expenses across different frequencies (weekly, monthly, yearly), visualize historical costs, and link specific bank transactions to these commitments for accurate financial reporting.

The system utilizes a dual-layered approach consisting of Subscriptions (manually created or verified recurring transactions) and Subscription Suggestions (AI-detected patterns from historical transaction data). By linking transactions to subscriptions, the application can provide deeper insights into "all-time" and "this-year" spending for specific services.

Sources: README.md, frontend/lib/actions/subscriptions.ts:18-28, frontend/lib/actions/subscription-suggestions.ts:16-20

System Architecture and Data Models

The system is built on a shared PostgreSQL database used by both the Next.js frontend and Python backend. The primary entities involved are RecurringTransaction (referred to as Subscriptions in the UI) and SubscriptionSuggestion.

Data Entities

Field	Type	Description
id	UUID	Unique identifier for the subscription or suggestion.
name	String	User-facing name (e.g., "Netflix").
amount	Decimal	The expected recurring amount.
frequency	Enum	The recurrence interval: weekly, biweekly, monthly, quarterly, yearly.
isActive	Boolean	Whether the subscription is currently being tracked (for RecurringTransaction).
confidence	Integer	0-100 score indicating detection certainty (for SubscriptionSuggestion).
importance	Integer	1-3 scale representing the priority of the expense.

Sources: frontend/lib/actions/subscriptions.ts:32-55, backend/postgres_migration/monitor_db.py:535-542, frontend/components/subscriptions/subscription-form-dialog.tsx:32-42

Relationship Diagram

The following diagram illustrates how transactions relate to subscriptions and their supporting entities like accounts and categories.

Subscription Detection Logic

The application identifies potential subscriptions by analyzing historical transaction data for patterns. This process happens in two primary ways: background detection (generating suggestions) and on-demand detection from a specific transaction.

Detection Factors

1. String Similarity: Uses Levenshtein distance to compare merchant names and descriptions.
2. Amount Matching: Allows for a ±10% tolerance to account for currency fluctuations or minor price changes.
3. Temporal Consistency: Analyzes "date gaps" between transactions to match defined frequency ranges (e.g., ~30 days for monthly).
4. Consistency Score: Calculated based on the standard deviation of gaps; lower deviation results in higher confidence.

Managing Subscriptions

Users interact with subscriptions through a dedicated dashboard that lists active subscriptions, inactive ones, and pending suggestions.

Core Operations

• Verification: When a user approves a suggestion, the system creates a RecurringTransaction and retroactively links the matched Transaction IDs to it.
• Matching: The matchTransactionsToSubscription function performs a bulk update of the recurringTransactionId field for any existing transactions that meet similarity thresholds.
• Cost Aggregation: The system calculates "This Year" and "All Time" totals by summing the absolute values of all transactions linked to a specific subscription ID.

Sources: frontend/lib/actions/subscriptions.ts:468-545, frontend/lib/actions/subscription-suggestions.ts:96-180, frontend/components/subscriptions/subscription-detail-sheet.tsx:135-155

Subscription KPIs

The system calculates real-time KPIs to provide a financial overview of recurring commitments:

• Monthly Total: Normalizes all active subscriptions to a monthly equivalent using frequency multipliers (e.g., yearly amount / 12).
• Active Count: Total number of subscriptions where isActive is true.
• All-Time Total: Cumulative sum of every transaction ever linked to a subscription.

Sources: frontend/lib/actions/subscriptions.ts:251-285, frontend/components/subscriptions/subscriptions-summary-row.tsx:15-22

Integration with Company Logos

The module integrates with the Logo.dev API to enhance the UI. When creating or editing a subscription, the system can automatically search for a company's logo based on the name or domain. These logos are stored in the companyLogos table and cached locally to reduce API calls.

Sources: README.md, frontend/components/subscriptions/subscription-form-dialog.tsx:112-140, frontend/lib/actions/subscriptions.ts:122

Summary

The Subscription and Recurring Payments system provides a robust framework for managing financial commitments. By combining automated detection with manual management and detailed transaction linking, it allows users to maintain a clear view of their recurring financial obligations and historical spending patterns.

Sources: README.md, frontend/app/(dashboard)/subscriptions/page.tsx