Cursor rule

1---
2description: This rule explains the system architecture and data flow of the Rails app
3globs: *
4alwaysApply: true
5---
6 
7This file outlines how the codebase is structured and how data flows through the app.
8 
9This is a personal finance application built in Ruby on Rails.  The primary domain entities for this app are outlined below.  For an authoritative overview of the relationships, [schema.rb](mdc:db/schema.rb) is the source of truth.
10 
11## App Modes
12 
13The codebase runs in two distinct "modes", dictated by `Rails.application.config.app_mode`, which can be `managed` or `self_hosted`.
14 
15- "Managed" - in managed mode, a team operates and manages servers for users
16- "Self Hosted" - in self hosted mode, users host the codebase on their own infrastructure, typically through Docker Compose.  We have an example [docker-compose.example.yml](mdc:docker-compose.example.yml) file that runs [Dockerfile](mdc:Dockerfile) for this mode.
17 
18## Families and Users
19 
20- `Family` - all Stripe subscriptions, financial accounts, and the majority of preferences are stored at the [family.rb](mdc:app/models/family.rb) level.
21- `User` - all [session.rb](mdc:app/models/session.rb) happen at the [user.rb](mdc:app/models/user.rb) level.  A user belongs to a `Family` and can either be an `admin` or a `member`.  Typically, a `Family` has a single admin, or "head of household" that manages finances while there will be several `member` users who can see the family's finances from varying perspectives.
22 
23## Currency Preference
24 
25Each `Family` selects a currency preference.  This becomes the "main" currency in which all records are "normalized" to via [exchange_rate.rb](mdc:app/models/exchange_rate.rb) records so that the app can calculate metrics, historical graphs, and other insights in a single family currency.
26 
27## Accounts
28 
29The center of the app's domain is the [account.rb](mdc:app/models/account.rb).  This represents a single financial account that has a `balance` and `currency`.  For example, an `Account` could be "Chase Checking", which is a single financial account at Chase Bank.  A user could have multiple accounts at a single institution (i.e. "Chase Checking", "Chase Credit Card", "Chase Savings") or an account could be a standalone account, such as "My Home" (a primary residence).
30 
31### Accountables
32 
33In the app, [account.rb](mdc:app/models/account.rb) is a Rails "delegated type" with the following subtypes (separate DB tables).  Each account has a `classification` or either `asset` or `liability`.  While the types are a flat hierarchy, below, they have been organized by their classification:
34 
35- Asset accountables
36  - [depository.rb](mdc:app/models/depository.rb) - a typical "bank account" such as a savings or checking account
37  - [investment.rb](mdc:app/models/investment.rb) - an account that has "holdings" such as a brokerage, 401k, etc.
38  - [crypto.rb](mdc:app/models/crypto.rb) - an account that tracks the value of one or more crypto holdings
39  - [property.rb](mdc:app/models/property.rb) - an account that tracks the value of a physical property such as a house or rental property
40  - [vehicle.rb](mdc:app/models/vehicle.rb) - an account that tracks the value of a vehicle
41  - [other_asset.rb](mdc:app/models/other_asset.rb) - an asset that cannot be classified by the other account types.  For example, "jewelry".
42- Liability accountables
43  - [credit_card.rb](mdc:app/models/credit_card.rb) - an account that tracks the debt owed on a credit card
44  - [loan.rb](mdc:app/models/loan.rb) - an account that tracks the debt owed on a loan (i.e. mortgage, student loan)
45  - [other_liability.rb](mdc:app/models/other_liability.rb) - a liability that cannot be classified by the other account types.  For example, "IOU to a friend"
46 
47### Account Balances
48 
49An account [balance.rb](mdc:app/models/account/balance.rb) represents a single balance value for an account on a specific `date`.  A series of balance records is generated daily for each account and is how we show a user's historical balance graph.  
50 
51- For simple accounts like a "Checking Account", the balance represents the amount of cash in the account for a date.  
52- For a more complex account like "Investment Brokerage", the `balance` represents the combination of the "cash balance" + "holdings value".  Each accountable type has different components that make up the "balance", but in all cases, the "balance" represents "How much the account is worth" (when `classification` is `asset`) or "How much is owed on the account" (when `classification` is `liability`)
53 
54All balances are calculated daily by [balance_calculator.rb](mdc:app/models/account/balance_calculator.rb).
55 
56### Account Holdings
57 
58An account [holding.rb](mdc:app/models/holding.rb) applies to [investment.rb](mdc:app/models/investment.rb) type accounts and represents a `qty` of a certain [security.rb](mdc:app/models/security.rb) at a specific `price` on a specific `date`.
59 
60For investment accounts with holdings, [base_calculator.rb](mdc:app/models/holding/base_calculator.rb) is used to calculate the daily historical holding quantities and prices, which are then rolled up into a final "Balance" for the account in [base_calculator.rb](mdc:app/models/account/balance/base_calculator.rb).
61 
62### Account Entries
63 
64An account [entry.rb](mdc:app/models/entry.rb) is also a Rails "delegated type".  `Entry` represents any record that _modifies_ an `Account` [balance.rb](mdc:app/models/account/balance.rb) and/or [holding.rb](mdc:app/models/holding.rb).  Therefore, every entry must have a `date`, `amount`, and `currency`.
65 
66The `amount` of an [entry.rb](mdc:app/models/entry.rb) is a signed value.  A _negative_ amount is an "inflow" of money to that account.  A _positive_ value is an "outflow" of money from that account.  For example:
67 
68- A negative amount for a credit card account represents a "payment" to that account, which _reduces_ its balance (since it is a `liability`)
69- A negative amount for a checking account represents an "income" to that account, which _increases_ its balance (since it is an `asset`)
70- A negative amount for an investment/brokerage trade represents a "sell" transaction, which _increases_ the cash balance of the account 
71 
72There are 3 entry types, defined as [entryable.rb](mdc:app/models/entryable.rb) records: 
73 
74- `Valuation` - an account [valuation.rb](mdc:app/models/valuation.rb) is an entry that says, "here is the value of this account on this date".  It is an absolute measure of an account value / debt.  If there is an `Valuation` of 5,000 for today's date, that means that the account balance will be 5,000 today.
75- `Transaction` - an account [transaction.rb](mdc:app/models/transaction.rb) is an entry that alters the account balance by the `amount`.  This is the most common type of entry and can be thought of as an "income" or "expense".  
76- `Trade` - an account [trade.rb](mdc:app/models/trade.rb) is an entry that only applies to an investment account.  This represents a "buy" or "sell" of a holding and has a `qty` and `price`.
77 
78### Account Transfers
79 
80A [transfer.rb](mdc:app/models/transfer.rb) represents a movement of money between two accounts.  A transfer has an inflow [transaction.rb](mdc:app/models/transaction.rb) and an outflow [transaction.rb](mdc:app/models/transaction.rb).  The codebase auto-matches transfers based on the following criteria:
81 
82- Must be from different accounts
83- Must be within 4 days of each other
84- Must be the same currency
85- Must be opposite values
86 
87There are two primary forms of a transfer:
88 
89- Regular transfer - a normal movement of money between two accounts.  For example, "Transfer $500 from Checking account to Brokerage account". 
90- Debt payment - a special form of transfer where the _receiver_ of funds is a [loan.rb](mdc:app/models/loan.rb) type account.  
91 
92Regular transfers are typically _excluded_ from income and expense calculations while a debt payment is considered an "expense".
93 
94## Plaid Items
95 
96A [plaid_item.rb](mdc:app/models/plaid_item.rb) represents a "connection" maintained by our external data provider, Plaid in the "hosted" mode of the app.  An "Item" has 1 or more [plaid_account.rb](mdc:app/models/plaid_account.rb) records, which are each associated 1:1 with an internal app [account.rb](mdc:app/models/account.rb).
97 
98All relevant metadata about the item and its underlying accounts are stored on [plaid_item.rb](mdc:app/models/plaid_item.rb) and [plaid_account.rb](mdc:app/models/plaid_account.rb), while the "normalized" data is then stored on internal app domain models.
99 
100## "Syncs"
101 
102The codebase has the concept of a [syncable.rb](mdc:app/models/concerns/syncable.rb), which represents any model which can have its data "synced" in the background.  "Syncables" include:
103 
104- `Account` - an account "sync" will sync account holdings, balances, and enhance transaction metadata
105- `PlaidItem` - a Plaid Item "sync" fetches data from Plaid APIs, normalizes that data, stores it on internal app models, and then finally performs an "Account sync" for each of the underlying accounts created from the Plaid Item.
106- `Family` - a Family "sync" loops through the family's Plaid Items and individual Accounts and "syncs" each of them.  A family is synced once per day, automatically through [auto_sync.rb](mdc:app/controllers/concerns/auto_sync.rb).
107 
108Each "sync" creates a [sync.rb](mdc:app/models/sync.rb) record in the database, which keeps track of the status of the sync, any errors that it encounters, and acts as an "audit table" for synced data.
109 
110Below are brief descriptions of each type of sync in more detail.
111 
112### Account Syncs
113 
114The most important type of sync is the account sync.  It is orchestrated by the account's `sync_data` method, which performs a few important tasks:
115 
116- Auto-matches transfer records for the account
117- Calculates daily [balance.rb](mdc:app/models/account/balance.rb) records for the account from `account.start_date` to `Date.current` using [base_calculator.rb](mdc:app/models/account/balance/base_calculator.rb)
118  - Balances are dependent on the calculation of [holding.rb](mdc:app/models/holding.rb), which uses [base_calculator.rb](mdc:app/models/account/holding/base_calculator.rb) 
119- Enriches transaction data if enabled by user
120 
121An account sync happens every time an [entry.rb](mdc:app/models/entry.rb) is updated.
122 
123### Plaid Item Syncs
124 
125A Plaid Item sync is an ETL (extract, transform, load) operation:
126 
1271. [plaid_item.rb](mdc:app/models/plaid_item.rb) fetches data from the external Plaid API
1282. [plaid_item.rb](mdc:app/models/plaid_item.rb) creates and loads this data to [plaid_account.rb](mdc:app/models/plaid_account.rb) records
1293. [plaid_item.rb](mdc:app/models/plaid_item.rb) and [plaid_account.rb](mdc:app/models/plaid_account.rb) transform and load data to [account.rb](mdc:app/models/account.rb) and [entry.rb](mdc:app/models/entry.rb), the internal codebase representations of the data.
130 
131### Family Syncs
132 
133A family sync happens once daily via [auto_sync.rb](mdc:app/controllers/concerns/auto_sync.rb).  A family sync is an "orchestrator" of Account and Plaid Item syncs.
134 
135## Data Providers
136 
137The codebase utilizes several 3rd party data services to calculate historical account balances, enrich data, and more.  Since the app can be run in both "hosted" and "self hosted" mode, this means that data providers are _optional_ for self hosted users and must be configured.
138 
139Because of this optionality, data providers must be configured at _runtime_ through [registry.rb](mdc:app/models/provider/registry.rb) utilizing [setting.rb](mdc:app/models/setting.rb) for runtime parameters like API keys:
140 
141There are two types of 3rd party data in the codebase:
142 
1431. "Concept" data
1442. One-off data
145 
146### "Concept" data
147 
148Since the app is self hostable, users may prefer using different providers for generic data like exchange rates and security prices.  When data is generic enough where we can easily swap out different providers, we call it a data "concept".
149 
150Each "concept" has an interface defined in the `app/models/provider/concepts` directory.
151 
152```
153app/models/
154  exchange_rate/
155    provided.rb # <- Responsible for selecting the concept provider from the registry
156  provider.rb # <- Base provider class
157  provider/
158    registry.rb <- Defines available providers by concept
159    concepts/
160      exchange_rate.rb <- defines the interface required for the exchange rate concept
161```
162 
163### One-off data
164 
165For data that does not fit neatly into a "concept", an interface is not required and the concrete provider may implement ad-hoc methods called directly in code.
166 
167## "Provided" Concerns
168 
169In general, domain models should not be calling [registry.rb](mdc:app/models/provider/registry.rb) directly.  When 3rd party data is required for a domain model, we use the `Provided` concern within that model's namespace.  This concern is primarily responsible for:
170 
171- Choosing the provider to use for this "concept"
172- Providing convenience methods on the model for accessing data
173 
174For example, [exchange_rate.rb](mdc:app/models/exchange_rate.rb) has a [provided.rb](mdc:app/models/exchange_rate/provided.rb) concern with the following convenience methods:
175 
176```rb
177module ExchangeRate::Provided
178  extend ActiveSupport::Concern
179 
180  class_methods do
181    def provider
182      registry = Provider::Registry.for_concept(:exchange_rates)
183      registry.get_provider(:synth)
184    end
185 
186    def find_or_fetch_rate(from:, to:, date: Date.current, cache: true)
187      # Implementation 
188    end
189 
190    def sync_provider_rates(from:, to:, start_date:, end_date: Date.current)
191      # Implementation 
192    end
193  end
194end
195```
196 
197This exposes a generic access pattern where the caller does not care _which_ provider has been chosen for the concept of exchange rates and can get a predictable response:
198 
199```rb
200def access_patterns_example
201  # Call exchange rate provider directly
202  ExchangeRate.provider.fetch_exchange_rate(from: "USD", to: "CAD", date: Date.current)
203 
204  # Call convenience method
205  ExchangeRate.sync_provider_rates(from: "USD", to: "CAD", start_date: 2.days.ago.to_date)
206end
207```
208 
209## Concrete provider implementations
210 
211Each 3rd party data provider should have a class under the `Provider::` namespace that inherits from `Provider` and returns `with_provider_response`, which will return a `Provider::ProviderResponse` object:
212 
213```rb
214class ConcreteProvider < Provider
215  def fetch_some_data
216    with_provider_response do
217      ExampleData.new(
218        example: "data"
219      )
220    end
221  end
222end
223```
224 
225The `with_provider_response` automatically catches provider errors, so concrete provider classes should raise when valid data is not possible:
226 
227```rb
228class ConcreteProvider < Provider
229  def fetch_some_data
230    with_provider_response do
231      data = nil
232 
233      # Raise an error if data cannot be returned
234      raise ProviderError.new("Could not find the data you need") if data.nil?
235 
236      data
237    end
238  end
239end
240```
241