ledger

[chadwhitacre]

Redo of #3653.

Questions for Peter:

• Under what circumstances would you delete an account from the chart of accounts?
• Under what circumstances would you change an account name or number in the chart of accounts? (I have this impression that sometimes one will "recode" a chart of accounts, restructuring it.)
• What's the difference between a Trial Balance and a Ledger Summary?
• What's the most natural IA? Statements, Ledgers, Journals across the top? Or Statements, General, $Specific across the top?
• How about using the week for our accounting period?

[chadwhitacre]

[chadwhitacre]

My thinking here is that we should approach this by building out a mini-application with a chart of accounts and a general ledger, where admins can filter, sort, search, browse, and CRUD accounts and ledger entries, and then once we have the tables and UI in place, start porting existing processes and data over to the ledger in follow-on PRs.

[chadwhitacre]

[chadwhitacre]

[chadwhitacre]

[chadwhitacre]

Getting a little ahead of myself, starting to think about chart of accounts structure (after realizing that we don't need a separate "type" field since the type is encoded in the number) ...

[chadwhitacre]

We actually shouldn't need to manually add accounts that often, mostly when we set up a new bank account or payments vendor. I don't believe we'll ever want to delete an account that has any transactions on it (a question for Peter).

[chadwhitacre]

Alright, so let's get some accounts persisting, and then turn to transactions ...

[chadwhitacre]

[techtonik]

That looks like rocket science from finance world to me. Is it possible to call it somehow differently for people who is not an expert in accounting? I have a natural interest in this stuff, so tried to watch a few videos on khan academy, but I expect that majority of users are not that involved to learn what this ledger is about.

How about?

• ledger -- moneylog
• asset -- debts to me
• liability -- my debts

And hey! It looks like we will be able to do this - https://sfconservancy.org/npoacct/

[chadwhitacre]

Is it possible to call it somehow differently for people who is not an expert in accounting?

I think we should use standard accounting terminology, because eventually the goal is to have accountants on our Team, helping us manage our company. The point here is to build a system that accountants will be comfortable with. I'm meeting with an accountant next week to make sure we're achieving that.

[chadwhitacre]

I've started integrating HTML documentation with the new /api/ endpoints.

[chadwhitacre]

I really like how this is coming along, with the integrated API docs.

[chadwhitacre]

The next step on this PR is to implement the general ledger. I believe the accounts schema/API will need to change to support what we want for the ledger. One of the things we want is auditability. We want to be able to know who changed accounts when.

[chadwhitacre]

We also need to keep track of the balance for each account. I'm thinking about implementing this using our INSERT-only pattern as with payment_instructions, etc. Then balance here would be like is_funded there.

[chadwhitacre]

Oooooooo ... multicurrency? I'm looking at http://www.ledger-cli.org/3.0/doc/ledger3.html#Keeping-a-Journal.

[chadwhitacre]

"Commodities" are pretty low down in Ledger's design: http://www.ledger-cli.org/3.0/doc/ledger3.html#Internal-Design.

[chadwhitacre]

I think currency/commodity attaches to an account, so for a Coinbase payout we'd have 50 against a Gratipay account denominated in USD, and 0.1 against Gratipay's Coinbase account, which would be denominated in BTC.

[chadwhitacre]

"Ledgers summarize the balances of the accounts in the chart of accounts."

[chadwhitacre]

"Unlike other financial accounting statements, the general ledger is where all account activity is posted with debits and credits."

[chadwhitacre]

But, "You will take the information from these journals and place the information into your general ledger." So confusing. :-/

[chadwhitacre]

"Journal entries made into the general ledger [...]" not less confusing.

[chadwhitacre]

What's our accounting period? The week?

[chadwhitacre]

That would seem the most natural fit given our history.

[chadwhitacre]

Let's say it's the week.

[chadwhitacre]

I like the typography on the ledger detail in the book used in https://www.youtube.com/watch?v=D96wao4iZn8:

[chadwhitacre]

Alright, so let's show a ledger summary at:

./ledgers/general
./ledgers/~users
./ledgers/Teams

And a ledger account detail at:

./ledgers/general/100
./ledgers/~users/1234 (maybe redirect ~username to 1234 for convenience?)
./ledgers/Teams/2345

[chadwhitacre]

Let's not worry about a Trial Balance for this PR.

[chadwhitacre]

Let's move the account creation/modification to the general ledger summary. For ~users and Teams, account creation and modification happens in the course of ~user registration and Team application.

Do ~users and Teams subledgers make sense, though?

[chadwhitacre]

What are the GL control accounts that we would have? I suppose we'd have a "~user balances" and "Team balances."

[chadwhitacre]

The typical examples of subledgers are AR and AP, where the accounts in the former are customers, and the latter, vendors.

[chadwhitacre]

How do income and expense factor in? Seems like that gets us into Gratipay's operational accounting.

Braintree, etc.'s fees are expenses to Gratipay. We pass them through as fees to our ~users, which is income for us.

[chadwhitacre]

Cash Disbursement Journal - The accounting subsidiary ledger on which are listed all
checks disbursed from the escrow trust account in sequential order.

Cash Receipt Journal - The accounting subsidiary ledger on which are listed all funds
deposited to the escrow bank account.

http://www.tdi.texas.gov/title/documents/BASICS.pdf

[chadwhitacre]

Individual Escrow Ledger Record - Record maintained for accounting purposes to show
actual receipts and disbursements on a daily basis and determine the funds available in
a specific file at any given time.

[chadwhitacre]

What are our source documents?

[chadwhitacre]

I think "source document" in our case is blurred because we're so automated. The database record is the source document, or the source document is notional. E.g., we're going to generate a receipt from the database record, not the other way around.

[chadwhitacre]

Maybe we rename exchanges to receipts? Maybe we have triggers on exchanges and journal_entries that make records in journal_entries and ledger?

[chadwhitacre]

From the goofy one:

[chadwhitacre]

Maybe we rename payments to invoices, to reflect that those are the source documents for transactions that move money between Teams and ~users? But the meaning of the payment from a Team to a ~user depends on the relationship: owner, employer, or contractor. It's only an invoice in that case for the contractor relationship.

[chadwhitacre]

It would be a win and perhaps a more achievable one on this PR if we simply start with a general ledger that covers our top-level escrow accounts, without necessarily having the drill-down yet.

[chadwhitacre]

But first I want to redo the accounts schema to keep track of changes over time.

[chadwhitacre]

Alright, it is seeming foolish to me to reimplement an entire accounting system inside of Gratipay. Per the above comments #3786 (comment) and #3786 (comment), I'm now thinking about how the work on this PR relates to setting up accrual accounting for Gratipay as a whole. It seems that we want to use a proper accounting package (Xero!) for Gratipay-as-a-whole. In which case, gratipay.com effectively becomes a subledger for our escrow liability.

[chadwhitacre]

I'm looking back over http://www.tdi.texas.gov/title/documents/BASICS.pdf ...

[chadwhitacre]

Alright, thanks to @kaguillera we are off and running with gratipay/inside.gratipay.com#308. There's some great work on this PR towards a literate, integrated API. Perhaps one day we can scavenge it for parts. :-)