Beans is a personal financial manager that's written in Java and uses a PostgreSQL database for its database back-end storage.
The platform choice of Java and PostgreSQL may appear a bit odd initially. I began writing Beans because I didn't want to reboot any more, in order to enter my receipts or print checks. I looked at Gnucash. It is a solid application, but I found a number of small issues with Gnucash that eventually made me abandon it. Gnucash couldn't import my existing financial records from a QIF file correctly. Bank accounts and credit card accounts imported fine; but investment accounts were completely messed up. Also, Gnucash apparently reads everything - transactions, and everything else - into memory. So memory is a limiting factor for Gnucash. It's user interface is sometimes a bit awkward to use. Gnucash was designed from a viewpoint of a double-entry accounting system. Although this is a sound design, the user interface implementation of double-entering transactions felt somewhat cumbersome.
I was playing with PostgreSQL and noticed that it had Java bindings. I realized that these two technologies could be used to quickly build a personal financial manager that I could use without rebooting into MS-Windows. So that's what Beans generally is: my personal financial manager that I've written for my own use.
There are several important points, positive and negative, regarding Beans' design:
Read the following overview before installing Beans for the first time. If you are installing Beans for the first time, the following information may appear to go off on a tangent, and not deal directly with the subject of installing and configuring Beans. It is highly recommended to skim the following overview before installing and using Beans for the first time. After reading the following introductory material proceed to the INSTALL file for the installation procedure.
It's desirable to have a working knowledge of the PostgreSQL database server before installing Beans, but it's not strictly required. A crash course follows.
The Beans world has three major players: databases, files, and users. A database is a plain, garden-variety PostgreSQL database. Data in the PostgreSQL server is divided into abstractions called 'databases'. Individual databases are completely isolated from each other. A dedicated database must be allocated in PostgreSQL for Beans. A single PostgreSQL server may have multiple Beans databases, however. The name of the database is specified when starting the Beans application. A separate small administrative application is used to create and initialize Beans databases.
Each Beans database may contain multiple "files". A "file" in this context is an abstraction for the collection of database tables that store all the financial information for a set of accounts. Transactions may freely move money between accounts in the same file, but may not move money between accounts in different files.
A userid and a password must be entered when starting Beans, in order to log on to the PostgreSQL server. Beans is a multiuser applications, and multiple users can log in, open, and work with files at the same times. The same file may also be opened by multiple users, this will generally work, although changes saved by one user may not be immediately seen by another user. Furthermore, at this time, only the login id that created a file may open it.
A file contains a list of accounts and transactions. An account may be what we commonly called an account: a bank checking account, a savings account, or a credit card account. In Beans, an account may also be what we commonly call an income or an expense category: "Salary" or "Groceries", for example. In Beans, all transactions simply transfer money from one account to another. For example, depositing a paycheck transfer the amount of the deposit from the "Salary" account to the "Checking" or the "Savings" account. Purchasing groceries on a credit card transfer the purchase amount from the "Credit Card" account to the "Groceries" account. Paying the credit card bill transfers the amount of the payment from the "Checking" account to the "Credit Card" account.
Every type of a transaction in Beans can be reduced to transfering money (TODO: or shares of stocks) between a list of accounts. Most transactions will only transfer some amount from one account to another account. Some transactions may involve transfers between three or more accounts. For example, one way to keep track of income taxes withheld from one's salary is to record each salary check as follows, for example: $1,000 from "Salary", $62.00 to "Social Security Tax", $14.50 to "Medicare Tax", $196.11 to "Federal Tax Withheld", and $727.39 to "Checking" (this being the actual amount of the paycheck, less taxes withheld).
In Beans, each transaction is simply a list of debits and credits applied against a set of accounts. All debits or credits in each transactions always add up to zero. In the previous example, the $1,000 transfer from the "Salary" account is recorded as a debit. Because the $1,000 amount is transferred from "Salary", it is recorded as a negative amount. The remaining credits to various tax accounts, and the checking account cancel out the negative $1,000 to zero.
In practice, Beans' user interface mostly hide the actual mechanical details of how transactions are saved in the database. The previous example is entered into Beans by beginning a Deposit entry, selecting "Edit" to enter the deposit details, and entering a "Salary" amount of $1,000, then "Social Security Tax", "Medicare Tax", and "Federal Tax Withheld" negative adjustments for their respective amounts. Beans automatically adds up all adjustments and automatically calculates $727.39 as the deposit amount.
... to be continued ...