Investment Portfolio Sync #974

2024-07-12T03:25:00+08:00

zachgoll commented

2024-07-12 03:25:00 +08:00

(Migrated from github.com)

This is a backend-only PR that introduces the necessary models required to support investment portfolios and integrates these models into the Account::Sync process.

Overview

Below are a few important notes about the domain changes:

Mental model

An Account can have various Account::Entrys.

An Account::Entry can be either an Account::Valuation, Account::Transaction, or Account::Trade.

Account::Valuation - sets the new account balance to the valuation amount (i.e. "the account is worth $X on Y date")
Account::Transaction / Account::Trade - these are adjustments to the prior day balance

An Account::Balance is a temporal value that represents the output of an Account::Sync, which reads through Account::Entry records and modifies the balance according to the signage of the entry.

An Account::Holding is also a temporal value that represents the output of an Account::Sync when an account has relevant Account::Trade entries. A holding represents a qty of a Security on a specific date for a specific Account, which is worth amount, based on the Security::Price and qty for date.

Total Account Value

The total value of an Account is equal to Account::Balance + SUM(Account::Holding) for a given date.

Account::Balance represents the "cash" balance of an account on a date, while Account::Holdings are summed up on a date to derive the "investment value" based on current day Security::Price of each owned holding.

Trade signage

In the Maybe app, when an Account::Entry has a negative amount, this indicates an "inflow" to an Account::Balance and will increase the account balance. For example, a transaction with amount of -500 would affect different accounts as follows:

Credit Card Account (liability) - decreases the balance on the account, which reduces the liability balance (inflow)
Depository Account (asset) - increases the balance on the account, which increases the asset balance (inflow)

For Account::Trade types, there are two components of amount:

qty - a positive quantity represents a "buy", and a negative qty represents a "sell"
price - this is always a positive amount

Therefore, if a user "buys" 10 shares of AAPL at $200 per share, the amount with be positive (outflow):

amount = 10 * 200 = $2,000

Consistent with the convention that "positive equals outflow", we can say that $2,000 flowed out of the "cash balance" of the account and into the "Holdings Value" of the account.

This is a backend-only PR that introduces the necessary models required to support investment portfolios and integrates these models into the `Account::Sync` process. ## Overview Below are a few important notes about the domain changes: ### Mental model An `Account` can have various `Account::Entry`s. An `Account::Entry` can be either an `Account::Valuation`, `Account::Transaction`, or `Account::Trade`. - `Account::Valuation` - sets the new account balance to the valuation amount (i.e. "the account is worth $X on Y date") - `Account::Transaction` / `Account::Trade` - these are _adjustments_ to the prior day balance An `Account::Balance` is a temporal value that represents the _output_ of an `Account::Sync`, which reads through `Account::Entry` records and modifies the balance according to the signage of the entry. An `Account::Holding` is also a temporal value that represents the _output_ of an `Account::Sync` when an account has relevant `Account::Trade` entries. A holding represents a `qty` of a `Security` on a specific date for a specific `Account`, which is worth `amount`, based on the `Security::Price` and `qty` for `date`. ### Total Account Value The total value of an `Account` is equal to `Account::Balance` + `SUM(Account::Holding)` for a given `date`. `Account::Balance` represents the "cash" balance of an account on a date, while `Account::Holding`s are summed up on a date to derive the "investment value" based on current day `Security::Price` of each owned holding. ### Trade signage In the Maybe app, when an `Account::Entry` has a _negative_ `amount`, this indicates an "inflow" to an `Account::Balance` and will increase the account balance. For example, a transaction with `amount` of -500 would affect different accounts as follows: - Credit Card Account (liability) - decreases the balance on the account, which reduces the liability balance (inflow) - Depository Account (asset) - increases the balance on the account, which increases the asset balance (inflow) For `Account::Trade` types, there are two components of `amount`: - `qty` - a positive quantity represents a "buy", and a negative `qty` represents a "sell" - `price` - this is _always_ a positive amount Therefore, if a user "buys" 10 shares of AAPL at $200 per share, the amount with be positive (outflow): `amount` = 10 * 200 = $2,000 Consistent with the convention that "positive equals outflow", we can say that $2,000 flowed _out_ of the "cash balance" of the account and _into_ the "Holdings Value" of the account.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: gavin/maybe#974