From be9247b15e6922b9d3ea086f238a31c665af5bc2 Mon Sep 17 00:00:00 2001 From: Kevin Tam Date: Sun, 21 Jan 2024 18:01:48 +0800 Subject: [PATCH] docs: update user docs for public view --- README.md | 40 +---- client/public/md/background.md | 87 +++++++++++ client/public/md/help.md | 267 +------------------------------- client/public/md/howto.md | 34 +++++ client/public/md/reference.md | 270 +++++++++++++++++++++++++++++++++ client/public/md/tutorial.md | 62 ++++++++ client/public/md/welcome.md | 25 ++- 7 files changed, 475 insertions(+), 310 deletions(-) create mode 100644 client/public/md/background.md create mode 100644 client/public/md/howto.md create mode 100644 client/public/md/reference.md create mode 100644 client/public/md/tutorial.md diff --git a/README.md b/README.md index 5313f1ef..9a56ccba 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,16 @@ -### Usage Guidelines +### Overview +Gainstrack is -The key things to record are -1. The account balances of your key bank accounts and investment assets - -Things you should do your best to record -1. All your approximate earnings and income, both personal and from investments -2. All interbank transfers and asset purchases - -Things you don't need to record -- Every single expense. Just the one off large items might be worthwhile - -Things that are nice to record -- Net income is okay (i.e. gross-expenses) - -### How the data will be used -Account balances allow you to determine your networth at points in time - -Recording transfers and asset purchases is needed to avoid spikes in your networth caused by reading account balances at times before and after the transfer - -Your earnings are needed to determine your monthly/yearly income for forward planning - -With all that information, your overall expenses can be determined. Any specifically measured expenses are just for your reporting granularity - -By knowing your networth, income and expenses, we can forecast many things like -* Return on your investments (IRR calculation) -* How close you are to retirement +The following guide is targeted for developers. For user help, please visit [Gainstrack Help](http://www.gainstrack.com/help) ### Developer notes -Proxy the mysql instance as localhost with the [original version](https://cloud.google.com/sql/docs/mysql/sql-proxy) of cloud sql proxy - -`cloud_sql_proxy -credential_file=./gainstrack-firebase-adminsdk-i4v7p-cd5c94630a.json -instances=gainstrack:asia-northeast1:gainstrack-tk=tcp:3306` +To proxy a mysql instance in google cloud as localhost: -For the more [recent version](https://github.com/GoogleCloudPlatform/cloud-sql-proxy) of the proxy: - -`cloud-sql-proxy -c ./gainstrack-firebase-adminsdk-i4v7p-cd5c94630a.json gainstrack:asia-northeast1:gainstrack-tk` +`cloud-sql-proxy -c ./gainstrack-firebase-adminsdk-some-id.json gainstrack:asia-northeast1:gainstrack-tk` #### Environment variables -`AV_API_KEY` - API Key for alphavantage. Free keys can be obtained from their webiste +`AV_API_KEY` - API Key for alphavantage. Free keys can be obtained from their website `MYSQL_PASS` - Password to MySQL database @@ -82,7 +55,6 @@ cd client quasar build ``` - Full single build of backend app server image can be built and submitted with `gcloud builds submit --config cloudbuild.yaml` This will also update the latest image in the container registry diff --git a/client/public/md/background.md b/client/public/md/background.md new file mode 100644 index 00000000..abb83bbd --- /dev/null +++ b/client/public/md/background.md @@ -0,0 +1,87 @@ +## Background + +This page explains the design of Gainstrack and why choices around design were made. Clarification and discussion of key topics. + +## How finances are recorded +Gainstrack allows you to record your finances in a simple text file. + +Behind the scenes, Gainstrack converts this to a journal of double-entry bookkeeping records, allowing the generation of rich and powerful reporting that is usually the domain of advanced accounting software run by accountants. + +Commands are defined to record transactions + +## Commands vs plaintext accounting transactions +Gainstrack is heavily inspired by beancount (and other similar) on its design. As an example, let's look at how one may record transactions in an investment account. + +In Gainstrack, here is how we record opening a Stocks account, funding it with 1000 GBP, buying some FTSE and VWRL stocks and subsequently having a dividend paid for the FTSE stock. It is very concise with 5 lines. + +``` +2004-10-14 open Assets:Investment:Stocks GBP + fundingAccount: Assets:Bank:England + multiAsset:true +2006-11-01 fund Assets:Investment:Stocks 1000.0 GBP +2006-11-02 trade Assets:Investment:Stocks 50.0 FTSE @10.0 GBP +2006-11-02 trade Assets:Investment:Stocks 50.0 VWRL @10.0 GBP C0.20 GBP +2006-11-15 yield Assets:Investment:Stocks FTSE 10.0 GBP +``` + +Here is what it takes to achieve the same in Beancount + +``` +2004-10-14 open Assets:Investment:Stocks GBP +2004-10-14 open Assets:Investment:Stocks:FTSE FTSE +2004-10-14 open Income:Investment:Stocks GBP +2004-10-14 open Assets:Investment:Stocks:VWRL VWRL +2004-10-14 open Income:Investment:Stocks:GBP GBP +2004-10-14 open Expenses:Investment:Stocks:GBP GBP +2004-10-14 open Income:Investment:Stocks:FTSE GBP +2004-10-14 open Expenses:Investment:Stocks GBP +2004-10-14 open Assets:Investment:Stocks:USD USD + +2006-11-01 * "Fund 1000.0 GBP" + Assets:Bank:England -1000.0 GBP + Assets:Investment:Stocks:GBP 1000.0 GBP +2006-11-02 * "BUY 50.0 FTSE @10.0 GBP" + Assets:Investment:Stocks:GBP -500.0 GBP + Assets:Investment:Stocks:FTSE 50.0 FTSE @10.0 GBP +2006-11-02 * "BUY 50.0 VWRL @10.0 GBP" + Assets:Investment:Stocks:GBP -500.2 GBP + Assets:Investment:Stocks:VWRL 50.0 VWRL @10.0 GBP + Expenses:Investment:Stocks:GBP 0.2 GBP +2006-11-15 * "FTSE yield 10.0 GBP" + Income:Investment:Stocks:FTSE -10.0 GBP + Assets:Investment:Stocks:GBP 10.0 GBP + +``` + +Let's look at the key differences + +Firstly syntactically +1. Double ledger plain text accounting requires you to have double the amount of information being recorded. Gainstrack removes this duplication. +2. Gainstrack syntax aims to minimize the amount of text needed - using less than half the size of most plaintextaccounting packages +3. Multi-currency account management happens automatically - both opening the right accounts but also allocating postings to the right accounts +4. Automatically generating expense accounts (e.g. for commission) and income accounts (e.g. for dividends) +5. Retaining additional source information by recording *why* the transaction appears. E.g. is it some trading cost, or yield of an asset. Plaintextaccounting only records the movement. This additional information will allow the driving of sophisticated networth tracking and P&L explain + +## Transactions must balance or not? + +Beancount transactions are [required to balance](https://beancount.github.io/docs/a_comparison_of_beancount_and_ledger_hledger.html), period. hledger allows the use of [virtual accounts](https://ledger-cli.org/doc/ledger3.html#Virtual-postings). The former position maintains the integrity of accounting data. The latter allows more ease of use to those not familiar with accounting principles. + +Gainstrack seeks to have the best of both worlds. The command syntax of Gainstrack does not require the user to worry about the concept of balancing of postings. But internally, Gainstrack will always generate transactions where all the postings add up to exactly zero. + +## Networth tracking doesn't require recording every little transaction + +TBD: Discussion on the use of `bal` command to rebalance with to a padding account and why it works well. + + +## Can gainstrack replace my use of beancount/hledger? What doesn't gainstrack do? + +Gainstrack is for tracking their own finances and networth. This does not require tracking every dollar and cent. As such, use cases that require transactional level tracking or not appropriate for gainstrack. I.e. I would *not* use gainstrack for +* Maintaining accounts of a company +* Use as a basis for handling personal tax calculations + +Some (current) technical gaps that prevent the above include +* Lack of unrealised vs realised tracking - networth tracking at Gainstrack is all mark-to-market based +* Cost basis of transactions is not being tracked +* User defined multi-posting transfers + +The gainstrack syntax design doesn't preclude any tracking of the above so these are features that could be added in future if there is demand. diff --git a/client/public/md/help.md b/client/public/md/help.md index 89b81319..2b987469 100644 --- a/client/public/md/help.md +++ b/client/public/md/help.md @@ -1,265 +1,8 @@ # Gainstrack Help -## Key concepts -Your financial data is maintained in a Gainstrack text file. It consists of a set of **entries** in the file written in plain text, each of which represents some event that affects your financial position. -### Entries +Gainstrack provides a lot of documentation. A high-level overview of how it’s organized will help you know where to look for certain things: -The input consists mainly of **entries**, each of which may have various **options**. Each entry begins with an associated date, which determines the point in time at which the entry will apply, and its type, which defines which kind of event this directive represents. Entries begin with a syntax that looks like this - -`YYYY-MM-DD ...` - -where YYYY is the year, MM is the numerical month, and DD the numerical date. All digits are required, for example, the 7th of May 2007 should be “2007-05-07”, including its zeros. - -### Ordering of entries -The order of declaration of the entries is not important. In fact, the entries are re-sorted by gainstrack automatically when you use the website, although for your own purposes you can organise your input file in any way you wish. - -Directives may be defined as occurring on start of day, intraday or end of day. - -### Accounts -Gainstrack accumulates assets in accounts. Main accounts must be defined before they can be use, although Gainstrack will automatically generate related accounts depending on how the account is used. - -An account name is a colon-separated list of capitalized words which begin with a letter, and whose first word must be one of five account types: - -`Assets Liabilities Equity Income Expenses` - -The components of account names is still to be defined by Gainstrack but it is strongly recommended that each component of the account names begin with a capital letter or a number and are followed by letters, numbers or dash (-) characters. All other characters should be avoided. - -An example of an account would be -`Assets:UK:Investment:ISA` - -Gainstrack may automatically create related accounts based on this such as -``` -Assets:UK:Investment:ISA:GBP ; GBP held in that account -Income:UK:Investment:ISA ; Income generated by this account -Expenses:UK:Investment:ISA ; Expenses generated by this account -``` -These automatically generated related accounts are used for reporting purposes backed by the double entry journals that are generated. However, entries in the input file should only refer to the main account names, not the related account. - -The set of all names of accounts seen in an input file implicitly define a hierarchy of accounts (sometimes called a chart-of-accounts), similarly to how files are organized in a file system. - - -### Assets -Accounts contain **assets**. Assets are anything of value, such as currencies, commodities, property, crypto and other investments. - -Like account names, asset names are recognized by their syntax, though, unlike account names, they need not be declared before being used). The syntax for an asset is a word all in capital letters, like these: -``` -USD -CAD -EUR -MSFT -IBM -AIRMILE -HOME -``` -Gainstrack recognises currencies specially. If they are an [ISO 4217 currency](http://en.wikipedia.org/wiki/ISO_4217#Active_codes), the website will use its historic database of currency database to perform automatic currency conversion. - -In general, Gainstrack does not apply special treatment to assets. They are just "things" that can be put into accounts. - -Finally, you will notice that there exists a “commodity” directive that can be used to declare assets. It is entirely optional: assets come into being as you use them. The purpose of the directive is simply to attach metadata to it. The naming of "commodity" rather than "asset" is for consistency with beancount. - -### Comments -The Beancount input file isn’t intended to contain only your directives: you can place comments and headers in it to organize your file. Any text on a line after the character “;” is ignored, text like this: - -``` -; I paid and left the taxi, forgot to take change, it was cold. -2015-01-01 spend Expenses:Taxi 20 USD Assets:Cash -``` - -At present, inline comments, while supported, will be dropped from the online editor - -## Account based entries -### Open -All main accounts need to be declared "open" to accept entries to be made against them. You can do this by writing a directive that looks like this: -``` -2014-05-01 open Liabilities:CreditCard:CapitalOne USD -``` -The general format of the Open directive is: -``` -YYYY-MM-DD open Account Asset - optionName: optionValue - optionName: optionValue -``` -Accounts can be multi-asset or single-asset. For single-asset, the Asset specifices the single type of asset the account holds. - -Multi-asset accounts are declared with the option -`multiAsset: true` -being set. The account's Asset still needs to be defined as this will determine the default reporting currency for that account. - -Each account should be declared “opened” at a particular date that precedes (or is the same as) the date of the first transaction that posts an amount to that account. - -Note that unlike Beancount, there is no booking method to be defined. - -Addition options include: - * expenseAccount: default account for expenses to be directed - * incomeAccount: default account for income to be directed - * fundingAccount: default account for funding to be sourced from - * multiAsset: if "true", account will be multi-asset - * automaticReinvestment: if "true", automatic reinvestment accounting is enabled (to be documented) - -### Close -This directive has not been defined, unlike other accounting platforms like Beancount. It may be added in future if required. - -## Transaction based entries -Unlike normal double entry based accounting systems that define a single transaction syntax, Gainstrack defines several ways to model transactions. These higher level directives allow for -* Simpler and shorter syntax to define transactions -* Ability to perform richer reporting from the extra information -* Inference of double entry accounting numbers, rather than being forced to be explicit - -TBD notes on use of main account and not referring to subaccounts - -### tfr -Transfer assets between two accounts - -This is the most basic directive. An example would be -``` -2009-01-01 tfr Assets:Bank:HSBCUK Assets:Property:PP 100000.0 GBP 1.0 HOME -``` -which represents spending money to buy a home. - -The general syntax is -``` -YYYY-MM-DD tfr FromAccount ToAccount AmountValue AmountAsset [TargetAmountValue TargetAmountAsset] -``` -TargetAmount only needs to be provided if it differs from the Amount to be deducted from the FromAccount. - -By providing a different TargetAmountAsset, cross currency transfers or asset purchases can be specified. -### trade -Purchase assets, recording cost basis - -The general syntax is -``` -YYYY-MM-DD trade Account AssetAmount @Price cCommission -``` -for example -`2020-01-20 trade Assets:Investment:IB 4000.0 IBTA @5.0 USD C12.0 USD` -means that 4000 units of IBTA were purchased at a cost of 5.0 USD per unit. The cost of performing the trade was 12 USD. As a result of this trade, the following postings would be generated -* 4000 applied to Assets:Investment:IB:IBTA, with a cost basis of 5.0 USD -* -20000 applied to Assets:Investment:IB:USD -* 12 applied to Expenses:Investment:IB:USD - -Trades must be performed within multi-asset accounts. - -Sales can similarly be recorded. For example -`2020-01-20 trade Assets:Investment:IB -4000.0 IBTA @6.0 USD C12.0 USD` -The following postings would be generated -* -4000 applied to Assets:Investment:IB:IBTA -* 23988 applied to Assets:Investment:IB:USD -* 12 applied to Expenses:Investment:IB:USD -Note that Gainstrack is not (presently) explicitly tracking inventory or lots of assets together with their cost basis. Also, realised P&L is not explicitly recorded in the postings. Instead Gainstrack handles unrealised and realised P&L in its reporting. For more discussion on this, see TBD docs. - -### fund -A shorthand for transfer funds into an account from a funding source. Typical use is to transfer funds in/out of an investment account. For example, given -``` -1900-01-01 open Assets:Bank USD -1900-01-01 open Assets:OtherBank USD -1900-01-01 open Assets:Investment:MyBroker USD - fundingAccount: Assets:Bank -``` -Then -`2010-01-01 fund Assets:Investment:MyBroker 10000.0 USD` -would represent a transfer from Assets:Bank to Assets:Investment:MyBroker of 10000 USD. - -Funding source can always be set explicitly, for example -`2010-01-01 fund Assets:Investment:MyBroker 10000.0 USD Assets:OtherBank` - -### yield -Records income generated from an asset. For example -`2010-01-01 yield Assets:Bank 50 USD` -could be used to represent bank interest being generated from a bank account. This would give rise to postings of -* Assets:Bank +50 USD -* Income:Bank -50 USD - -It can also be used to represent dividend yields in multi-asset accounts. For example -`2010-01-01 yield Assets:Investment:MyBroker VWRL 30 USD` -would give rise to postings of -* Assets:Investment:MyBroker:USD +30 USD -* Income:Investment:MyBroker:AGGG -30 USD - -### earn -Generate external personal income such as salary. For example, given -``` -1900-01-01 open Assets:Bank USD -1900-01-01 open Assets:OtherBank USD -1900-01-01 open Income:Salary - fundingAccount Assets:Bank -``` -Then -`2010-01-01 earn Income:Salary 1000 USD` -would fund Assets:Bank with 1000 USD from Income:Salary. - -The funding account can be specified explicitly if desired: -`2010-01-01 earn Income:Salary 1000 USD Assets:OtherBank` - -## Balance based commands -### bal -Declare a balance in an account of cash, applied at end of day - -For instance, this -`2014-12-26 bal Liabilities:US:CreditCard -3492.02 USD` - -asserts that the the account Liabilities:US:CreditCard should hold -3492.02 USD at *end of day*. If a different balance is encountered, a transfer is automatically generated from an adjustment account to the account in order to achieve the balance. - -The general syntax is -`YYYY-MM-DD bal AccountName AmountValue AmountAsset [AdjustmentAccount]` - -The account against which adjustments are to be made against is determined is chosen from, in order of priority - * the AdjustmentAccount in the entry - * TODO: an adjAccount on the account option - -Typical usage would be to use Expenses:General as an adjustment account for your bank account - -### unit -Declare a balance in an account of a security where cost basis is maintained -`2010-01-01 unit Assets:Pension:Company 706.0 UNITTRUST @5.0 GBP` - -This would ensure the resulting balance of UNITTRUST in the account reaches 706 by buying/selling the necessary units at 5.0 GBP to achieve the balance. - -If automaticReinvestment option is set to true on the account, any remaining cash amount in the account (currency determined by the currency of the main account), will be set to zero by moving value between an associated Income account. This feature is useful where the account is automatically reinvesting cash into assets so that cash is never undeployed - -### adj (deprecated) -Declare a balance in an account of cash, applied at start of day. It is otherwise similar to the `bal` command that asserts the balance at end of day. - -Since the assertion for this entry is start of day, the adjustment entry is made on the day before, which causes confusion. For that reason, this directive is deprecated - -## Global options -This commands are typically found at the top of the file - -`option "operating_currency" "GBP"` -specify your primary reporting currency - -## Miscellaneous commands -### price -Specify market price for an asset -``` -2010-01-01 price HOME 100,000 GBP -2010-01-01 price GBP 1.2 USD -``` -In practice, this type of entry is rarely needed because Gainstrack can obtain prices from -* Implied prices when transfer or trades are performed between two assets -* Historic prices for currencies - -It is still useful when one wants to perform a mark to market of an asset such as HOME where there is no automatic pricing available. - -### Commodity -This directive is to declare assets such as currencies, commodities or other assets -``` -1900-01-01 commodity CAD -1900-01-01 commodity VWRD - ticker: VWRD.LN - tags: equity -1900-01-01 commodity WORLDINDEX - proxy: VWRD.LN -``` -The general format of the Commodity directive is: - -`YYYY-MM-DD commodity Asset` -The purpose of this directive is to attach commodity-specific metadata fields on it, so that it can be gathered by reports later on. - -For example, defining an ISO currency will allow the website to perform automatic currency conversions. - -You can use any date for an asset as the date is never used. `1900-01-01` is a recommended date. - -Options include -* tags - comma separated set of strings, useful for identifying a class of assets (e.g. bond, equity) -* ticker - ticker symbol for obtaining external prices -* proxy - a proxy ticker symbol to extrapolate prices based on last trade and an external price source for the proxy ticker +- [Tutorials](/docs/tutorial) take you by the hand through setting up your first set of personal accounts +- [Background](/docs/background) discuss key topics and concepts at a fairly high level and provide useful background information and explanation. +- [Reference](/docs/reference) contains technical references +- [How-to](/docs/howto) guides are recipes. They guide you through the steps involved in addressing key problems and use-cases. diff --git a/client/public/md/howto.md b/client/public/md/howto.md new file mode 100644 index 00000000..24324fd2 --- /dev/null +++ b/client/public/md/howto.md @@ -0,0 +1,34 @@ +## How-tos +Step-by-step guides. + +### What should you try to record? + +Unlike formal accounting software where you must record every transaction and account for every dollar and cent, with Gainstrack, you only need to record what is useful. + +The key things to record are +1. Monthly - The account balances of your key bank accounts and investment assets + +Things you should do your best to record +1. All your approximate earnings and income, both personal and from investments +2. All interbank transfers and asset purchases + +Things you don't need to record +- Every single expense. Just the one off large items might be worthwhile + +Things that are nice to record +- Net income is okay (i.e. gross-expenses) + +### Why is it okay to only record part of one's accounts? +The goal of this software is to track your networth and explain how your networth is changing over time. To achieve this, not every single detail is required. + +Account balances allow you to determine your networth at points in time + +Recording transfers and asset purchases is needed to avoid spikes in your networth caused by reading account balances at times before and after the transfer + +Your earnings are needed to determine your monthly/yearly income for forward planning + +With all that information, your overall expenses can be determined. Any specifically measured expenses are just for your reporting granularity + +By knowing your networth, income and expenses, we can forecast many things like +* Return on your investments (IRR calculation) +* How close you are to retirement diff --git a/client/public/md/reference.md b/client/public/md/reference.md new file mode 100644 index 00000000..cd264c46 --- /dev/null +++ b/client/public/md/reference.md @@ -0,0 +1,270 @@ +## Reference + +Technical reference. + +[//]: # (Covers tools, components, commands and resources) + +## Key concepts +Your financial data is maintained in a Gainstrack text file. It consists of a set of **entries** in the file written in plain text, each of which represents some event that affects your financial position. + +### Entries + +The input consists mainly of **entries**, each of which may have various **options**. Each entry begins with an associated date, which determines the point in time at which the entry will apply, and its type, which defines which kind of event this directive represents. Entries begin with a syntax that looks like this + +`YYYY-MM-DD ...` + +where YYYY is the year, MM is the numerical month, and DD the numerical date. All digits are required, for example, the 7th of May 2007 should be “2007-05-07”, including its zeros. + +### Ordering of entries +The order of declaration of the entries is not important. In fact, the entries are re-sorted by gainstrack automatically when you use the website, although for your own purposes you can organise your input file in any way you wish. + +Directives may be defined as occurring on start of day, intraday or end of day. + +### Accounts +Gainstrack accumulates assets in accounts. Main accounts must be defined before they can be use, although Gainstrack will automatically generate related accounts depending on how the account is used. + +An account name is a colon-separated list of capitalized words which begin with a letter, and whose first word must be one of five account types: + +`Assets Liabilities Equity Income Expenses` + +The components of account names is still to be defined by Gainstrack but it is strongly recommended that each component of the account names begin with a capital letter or a number and are followed by letters, numbers or dash (-) characters. All other characters should be avoided. + +An example of an account would be +`Assets:UK:Investment:ISA` + +Gainstrack may automatically create related accounts based on this such as +``` +Assets:UK:Investment:ISA:GBP ; GBP held in that account +Income:UK:Investment:ISA ; Income generated by this account +Expenses:UK:Investment:ISA ; Expenses generated by this account +``` +These automatically generated related accounts are used for reporting purposes backed by the double entry journals that are generated. However, entries in the input file should only refer to the main account names, not the related account. + +The set of all names of accounts seen in an input file implicitly define a hierarchy of accounts (sometimes called a chart-of-accounts), similarly to how files are organized in a file system. + + +### Assets +Accounts contain **assets**. Assets are anything of value, such as currencies, commodities, property, crypto and other investments. + +Like account names, asset names are recognized by their syntax, though, unlike account names, they need not be declared before being used). The syntax for an asset is a word all in capital letters, like these: +``` +USD +CAD +EUR +MSFT +IBM +AIRMILE +HOME +``` +Gainstrack recognises currencies specially. If they are an [ISO 4217 currency](http://en.wikipedia.org/wiki/ISO_4217#Active_codes), the website will use its historic database of currency database to perform automatic currency conversion. + +In general, Gainstrack does not apply special treatment to assets. They are just "things" that can be put into accounts. + +Finally, you will notice that there exists a “commodity” directive that can be used to declare assets. It is entirely optional: assets come into being as you use them. The purpose of the directive is simply to attach metadata to it. The naming of "commodity" rather than "asset" is for consistency with beancount. + +### Comments +The Beancount input file isn’t intended to contain only your directives: you can place comments and headers in it to organize your file. Any text on a line after the character “;” is ignored, text like this: + +``` +; I paid and left the taxi, forgot to take change, it was cold. +2015-01-01 spend Expenses:Taxi 20 USD Assets:Cash +``` + +At present, inline comments, while supported, will be dropped from the online editor + +## Account based entries +### Open +All main accounts need to be declared "open" to accept entries to be made against them. You can do this by writing a directive that looks like this: +``` +2014-05-01 open Liabilities:CreditCard:CapitalOne USD +``` +The general format of the Open directive is: +``` +YYYY-MM-DD open Account Asset + optionName: optionValue + optionName: optionValue +``` +Accounts can be multi-asset or single-asset. For single-asset, the Asset specifices the single type of asset the account holds. + +Multi-asset accounts are declared with the option +`multiAsset: true` +being set. The account's Asset still needs to be defined as this will determine the default reporting currency for that account. + +Each account should be declared “opened” at a particular date that precedes (or is the same as) the date of the first transaction that posts an amount to that account. + +Note that unlike Beancount, there is no booking method to be defined. + +Addition options include: +* expenseAccount: default account for expenses to be directed +* incomeAccount: default account for income to be directed +* fundingAccount: default account for funding to be sourced from +* multiAsset: if "true", account will be multi-asset +* automaticReinvestment: if "true", automatic reinvestment accounting is enabled (to be documented) + +### Close +This directive has not been defined, unlike other accounting platforms like Beancount. It may be added in future if required. + +## Transaction based entries +Unlike normal double entry based accounting systems that define a single transaction syntax, Gainstrack defines several ways to model transactions. These higher level directives allow for +* Simpler and shorter syntax to define transactions +* Ability to perform richer reporting from the extra information +* Inference of double entry accounting numbers, rather than being forced to be explicit + +TBD notes on use of main account and not referring to subaccounts + +### tfr +Transfer assets between two accounts + +This is the most basic directive. An example would be +``` +2009-01-01 tfr Assets:Bank:HSBCUK Assets:Property:PP 100000.0 GBP 1.0 HOME +``` +which represents spending money to buy a home. + +The general syntax is +``` +YYYY-MM-DD tfr FromAccount ToAccount AmountValue AmountAsset [TargetAmountValue TargetAmountAsset] +``` +TargetAmount only needs to be provided if it differs from the Amount to be deducted from the FromAccount. + +By providing a different TargetAmountAsset, cross currency transfers or asset purchases can be specified. +### trade +Purchase assets, recording cost basis + +The general syntax is +``` +YYYY-MM-DD trade Account AssetAmount @Price cCommission +``` +for example +`2020-01-20 trade Assets:Investment:IB 4000.0 IBTA @5.0 USD C12.0 USD` +means that 4000 units of IBTA were purchased at a cost of 5.0 USD per unit. The cost of performing the trade was 12 USD. As a result of this trade, the following postings would be generated +* 4000 applied to Assets:Investment:IB:IBTA, with a cost basis of 5.0 USD +* -20000 applied to Assets:Investment:IB:USD +* 12 applied to Expenses:Investment:IB:USD + +Trades must be performed within multi-asset accounts. + +Sales can similarly be recorded. For example +`2020-01-20 trade Assets:Investment:IB -4000.0 IBTA @6.0 USD C12.0 USD` +The following postings would be generated +* -4000 applied to Assets:Investment:IB:IBTA +* 23988 applied to Assets:Investment:IB:USD +* 12 applied to Expenses:Investment:IB:USD + Note that Gainstrack is not (presently) explicitly tracking inventory or lots of assets together with their cost basis. Also, realised P&L is not explicitly recorded in the postings. Instead Gainstrack handles unrealised and realised P&L in its reporting. For more discussion on this, see TBD docs. + +### fund +A shorthand for transfer funds into an account from a funding source. Typical use is to transfer funds in/out of an investment account. For example, given +``` +1900-01-01 open Assets:Bank USD +1900-01-01 open Assets:OtherBank USD +1900-01-01 open Assets:Investment:MyBroker USD + fundingAccount: Assets:Bank +``` +Then +`2010-01-01 fund Assets:Investment:MyBroker 10000.0 USD` +would represent a transfer from Assets:Bank to Assets:Investment:MyBroker of 10000 USD. + +Funding source can always be set explicitly, for example +`2010-01-01 fund Assets:Investment:MyBroker 10000.0 USD Assets:OtherBank` + +### yield +Records income generated from an asset. For example +`2010-01-01 yield Assets:Bank 50 USD` +could be used to represent bank interest being generated from a bank account. This would give rise to postings of +* Assets:Bank +50 USD +* Income:Bank -50 USD + +It can also be used to represent dividend yields in multi-asset accounts. For example +`2010-01-01 yield Assets:Investment:MyBroker VWRL 30 USD` +would give rise to postings of +* Assets:Investment:MyBroker:USD +30 USD +* Income:Investment:MyBroker:AGGG -30 USD + +### earn +Generate external personal income such as salary. For example, given +``` +1900-01-01 open Assets:Bank USD +1900-01-01 open Assets:OtherBank USD +1900-01-01 open Income:Salary + fundingAccount Assets:Bank +``` +Then +`2010-01-01 earn Income:Salary 1000 USD` +would fund Assets:Bank with 1000 USD from Income:Salary. + +The funding account can be specified explicitly if desired: +`2010-01-01 earn Income:Salary 1000 USD Assets:OtherBank` + +## Balance based commands +### bal +Declare a balance in an account of cash, applied at end of day + +For instance, this +`2014-12-26 bal Liabilities:US:CreditCard -3492.02 USD` + +asserts that the the account Liabilities:US:CreditCard should hold -3492.02 USD at *end of day*. If a different balance is encountered, a transfer is automatically generated from an adjustment account to the account in order to achieve the balance. + +The general syntax is +`YYYY-MM-DD bal AccountName AmountValue AmountAsset [AdjustmentAccount]` + +The account against which adjustments are to be made against is determined is chosen from, in order of priority +* the AdjustmentAccount in the entry +* TODO: an adjAccount on the account option + +Typical usage would be to use Expenses:General as an adjustment account for your bank account + +### unit +Declare a balance in an account of a security where cost basis is maintained +`2010-01-01 unit Assets:Pension:Company 706.0 UNITTRUST @5.0 GBP` + +This would ensure the resulting balance of UNITTRUST in the account reaches 706 by buying/selling the necessary units at 5.0 GBP to achieve the balance. + +If automaticReinvestment option is set to true on the account, any remaining cash amount in the account (currency determined by the currency of the main account), will be set to zero by moving value between an associated Income account. This feature is useful where the account is automatically reinvesting cash into assets so that cash is never undeployed + +### adj (deprecated) +Declare a balance in an account of cash, applied at start of day. It is otherwise similar to the `bal` command that asserts the balance at end of day. + +Since the assertion for this entry is start of day, the adjustment entry is made on the day before, which causes confusion. For that reason, this directive is deprecated + +## Global options +This commands are typically found at the top of the file + +`option "operating_currency" "GBP"` +specify your primary reporting currency + +## Miscellaneous commands +### price +Specify market price for an asset +``` +2010-01-01 price HOME 100,000 GBP +2010-01-01 price GBP 1.2 USD +``` +In practice, this type of entry is rarely needed because Gainstrack can obtain prices from +* Implied prices when transfer or trades are performed between two assets +* Historic prices for currencies + +It is still useful when one wants to perform a mark to market of an asset such as HOME where there is no automatic pricing available. + +### Commodity +This directive is to declare assets such as currencies, commodities or other assets +``` +1900-01-01 commodity CAD +1900-01-01 commodity VWRD + ticker: VWRD.LN + tags: equity +1900-01-01 commodity WORLDINDEX + proxy: VWRD.LN +``` +The general format of the Commodity directive is: + +`YYYY-MM-DD commodity Asset` +The purpose of this directive is to attach commodity-specific metadata fields on it, so that it can be gathered by reports later on. + +For example, defining an ISO currency will allow the website to perform automatic currency conversions. + +You can use any date for an asset as the date is never used. `1900-01-01` is a recommended date. + +Options include +* tags - comma separated set of strings, useful for identifying a class of assets (e.g. bond, equity) +* ticker - ticker symbol for obtaining external prices +* proxy - a proxy ticker symbol to extrapolate prices based on last trade and an external price source for the proxy ticker diff --git a/client/public/md/tutorial.md b/client/public/md/tutorial.md new file mode 100644 index 00000000..b193a281 --- /dev/null +++ b/client/public/md/tutorial.md @@ -0,0 +1,62 @@ +## Getting Started + +Tutorials. A hands-on introduction to Gainstrack. + +### Quick-start +You can choose to create a login so that your account details or saved - or simply skip to use the anonymous mode without logging in. + +Go to the [editor](/editor). If it is the first time, you'll see a sample template + +If you'd like a sample to start, here is something you can enter + +```text +2000-01-01 open Equity:Opening GBP + multiAsset: true +2000-01-01 open Assets:Bank:England GBP + +2004-10-14 open Assets:Pension:Barclays GBP + multiAsset: true + automaticReinvestment: true + fundingAccount: Equity:Opening + +2004-10-14 fund Assets:Pension:Barclays 500 GBP +2004-10-14 fund Assets:Pension:Barclays Equity:Opening 500 GBP +2004-10-15 unit Assets:Pension:Barclays 500 BGIL @2 GBP +2019-04-18 unit Assets:Pension:Barclays 600 BGIL @5 GBP + +2004-10-14 open Assets:ISA:London GBP + fundingAccount: Assets:Bank:England + incomeAccount: Income:ISA:London + +2004-10-14 fund Assets:ISA:London 7000 GBP +; Cash in ISA makes money +2005-10-14 adj Assets:ISA:London 8000 GBP Income:ISA:London +; Earn interest income, paid back to bank +2005-10-15 yield Assets:ISA:London 15 GBP + +2004-10-14 open Assets:Investment:Stocks GBP + fundingAccount: Assets:Bank:England + multiAsset: true +2006-11-01 fund Assets:Investment:Stocks 1000 GBP +2006-11-02 trade Assets:Investment:Stocks 50 FTSE @10 GBP +2006-11-15 yield Assets:Investment:Stocks FTSE 10 GBP +2006-11-02 trade Assets:Investment:Stocks 50 VWRL @10 GBP C0.20 GBP +2006-11-15 yield Assets:Investment:Stocks VWRL 10 USD +2006-11-15 tfr Assets:Investment:Stocks Assets:Investment:Stocks 10 USD 9 GBP + +2005-07-26 open Income:Salary:GBP GBP + fundingAccount: Assets:Bank:England +2005-07-26 earn Salary 25000.00 GBP +2005-07-26 earn Salary Assets:Bank:England 25000.00 GBP + +; Earn some interest +2005-08-01 yield Assets:Bank:England 10 GBP + +1900-01-01 commodity FTSE + name: FTSE100 Index + category: equity/uk +``` + +Now browse various reports by looking at the menu + +Try adding new commands per the [reference](/docs/reference), or you can try via the UI. diff --git a/client/public/md/welcome.md b/client/public/md/welcome.md index 5057e96b..0e960d3e 100644 --- a/client/public/md/welcome.md +++ b/client/public/md/welcome.md @@ -1,21 +1,18 @@ # Welcome to gainstrack ## Why gainstrack? -Gainstrack's aim is for individuals to be have control over their own finances through information and insights on their networth +Gainstrack's aim is for individuals to be have control over their own finances through information and insights on their networth, tracking your path to financial independence. -Beyond knowing your networth, it tracks your wealth across multiple accounts in multipe currencies, helping you track your path to financial independence +Unique capabilities to achieve this include +* Uses [plain text accounting](https://plaintextaccounting.org/) philosophy so you control all your data +* Provides the most comprehensive Wall Street level [P&L explain](/pnlexplain) capability so you know exactly all the reasons your networth is changing +* Multiple account management with full multicurrency support -## How finances are recorded -Gainstrack allows you to record your finances in a simple text file. +## Gainstrack Help -Behind the scenes, Gainstrack converts this to a journal of double-entry bookkeeping records, allowing the generation of rich and powerful reporting that is usually the domain of advanced accounting software run by accountants. +Gainstrack provides a lot of documentation. A high-level overview of how it’s organized will help you know where to look for certain things: -For more information on how Gainstrack works, see the [help pages](/docs/help) - -## Getting started - -Creating an account allows your gainstrack data to be saved and updated with our UI tools or in-built editor - -## Anonymous mode - -No registration required - maintain your own Gainstrack finances file on your machine and import to the website as necessary using the import/export capability +- [Tutorials](/docs/tutorial) take you by the hand through setting up your first set of personal accounts +- [Background](/docs/background) discuss key topics and concepts at a fairly high level and provide useful background information and explanation. +- [Reference](/docs/reference) contains technical references +- [How-to](/docs/howto) guides are recipes. They guide you through the steps involved in addressing key problems and use-cases.