___ _ / __(_)_ __ __ _ _ __ ___ ___ _ __ / _\ | | '_ \ / _` | '_ \ / __/ _ \ '__| / / | | | | | (_| | | | | (_| __/ | \/ |_|_| |_|\__,_|_| |_|\___\___|_| 1. About 2. Overview 3. Architectural overview 4. Account types 5. Booking rules 6. Account groups 7. Transactions 8. Recurring transactions 9. Reporting 10. FQL 11. Setup 12. Planned features 1. About ======== This is the manual for the financer application - a simple app to support you in managing your personal finances. The main goal of the financer application is to keep things simple by not attempting to provide sophisticated automation. Instead it is merely a tool that provides basic key values to support you. 2. Overview =========== 3. Architectural overview ========================= The financer application currently consists of two components - a server and a client. They communicate via a JSON REST API. The only available client is a web client that supports a boiled down view for mobile devices, though. Both client (-web-client) and server (-server) reside in dedicated Maven modules, with a common (-common) module that holds common model classes and DTOs. Both components are layered: ____________ C | Controller | L |------------| I | Chart | E S ____________ |------------| N E | Controller |<-------REST--------| Template | T R |------------| '------------' V | Service | E |------------| R | DBA | '------------' | | ,-------, | DB | '-------' Each component is contained in a distinct artifact. 4. Account types ================ The financer application defines various account types that enable the formulation of bookings that match real world financial actions. This chapter details those account types and explains their proper usage. Currently there are six account types in total: - Income: marks an account that acts as a source of money, e.g. monthly wage - Bank: indicates a real account at a bank, e.g. a check payment account - Cash: marks an account as physical cash, e.g. the money currently in the purse - Expense: marks an account that acts as a destination of money, e.g. through buying goods - Liability: marks an account as a liability at a third party, e.g. credit card or loan - Start: marks the start account that is to be used to book all the opening balances for the different accounts Note that there can be more than one account of a certain type, except for the Start type. This enables fine grained specification of financial actions via different accounts of the same type. For example there can be one account of type Income named 'Monthly wage' and another one named 'Gift' - both act as source of income, but the actual account name specifies what exact type of income it is and thus enables the modelling of real financial actions. This is especially interesting for reporting. The same principle applies to the account type Bank: it is advised to create one account of type Bank in financer for every real bank account. Also for accounts of type Cash ('Cookie jar', 'Purse', 'Under the mattress'). One certainly wants multiple accounts of type Expense as this is were the true power of the financer applications lies: with multiple accounts of type Expense one can track the actual spending as fine grained as required. For example there can be Expense accounts named 'Rent', 'Gasoline', 'Groceries' or 'Netflix' - or if one smokes cigarettes one could even create a 'Cigarettes' Expense account to track ones expenses for cigarettes. With accounts of type Liability one can track the liabilities at third parties. For example there could be an account named 'Mortgage' to track the liability at the bank. The logic behind accounts of type Liability is different than that behind other account types: the debt is booked as positive amount to the account and installments lower the current balance of the account according to the amount booked. So after the last installment the current balance of the account should be 0, indicating that the liability has been fulfilled. The account types described so far are common and mostly self-explanatory there is one special account type: Start. There can be only one account with type Start as mentioned before. This special account is used during the initial setup of the financer application only. It enables the initial booking of current balances to Bank, Cash and Liability accounts. 5. Booking rules ================ The previous chapter described the various account types available in financer. This chapter now explains the booking rules based on these account types. The following matrix shows all theoretically possible bookings: ___________________________ |\T | | | | | | | | \ | I | B | C | E | L | S | F = From account type | F\| | | | | | | T = To account type |---|---|---|---|---|---|---| | I | | X | X | | | | I = Income |---|---|---|---|---|---|---| B = Bank | B | | X | X | X | X | | C = Cash |---|---|---|---|---|---|---| E = Expense | C | | X | | X | X | | L = Liability |---|---|---|---|---|---|---| S = Start | E | | | | | | | |---|---|---|---|---|---|---| empty = booking disallowed | L | | X | X | X | | | X = booking allowed |---|---|---|---|---|---|---| | S | | X | X | | X | | Read: booking from type F to type T allowed/disallowed '---'---'---'---'---'---'---' So lets have a look at the allowed bookings in more detail, including an example real world financial action and the effect on the current balances of the involved accounts: - From Income to Bank, e.g. monthly wage, I+ -> B+ - From Income to Cash, e.g. cash gifts, I+ -> C+ - From Bank to Bank, e.g. making an account transfer, B- -> B+ - From Bank to Cash, e.g. making a withdrawal at an ATM, B- -> C+ - From Bank to Expense, e.g. buying goods, B- -> E+ - From Bank to Liability, e.g. making an installment, B- -> L- - From Cash to Bank, e.g. making a deposit, C- -> B+ - From Cash to Expense, e.g. buying goods, C- -> E+ - From Cash to Liability, e.g. making an installment, C- -> L- - From Liability to Bank, e.g. payout of a credit, L+ -> B+ - From Liability to Cash, e.g. lending money from your neighbor, L+ -> C+ - From Liability to Expense, e.g. making a credit buy, L+ -> E+ - From Start to Bank, e.g. initial setup of current bank account balance, S+ -> B+ - From Start to Cash, e.g. initial setup of cash under the mattress, S+ -> C+ - From Start to Liability, e.g. initial setup of liability amount, S+ -> L+ 6. Account groups ================= Account groups are a simple way to group account into topics. Imagine the following accounts: - Rent - Electricity - Water - Groceries - Takeaway - Coffee shop - Cinema - Netflix They could be grouped via the following three groups: - Housing for Rent, Electricity and Water - Food for Groceries, Takeaway and Coffee shop - Entertainment for Cinema and Netflix This additional hierarchy level is actively used by reports to provide a better picture about where money is spent. The financer application makes no hard guidelines on how to model your accounts and account groups, so you can model them matching your needs. 7. Transactions =============== 8. Recurring transactions ========================= 9. Reporting ============ 10. FQL ======= 11. Setup ========= This chapter explains how to setup a financer instance. It requires PostgreSQL as a database backend and a Java Servlet Container (e.g. Apache Tomcat) as a runtime environment. 11.1 Database setup ------------------- First install PostgreSQL. Then create a user for financer: sudo -iu postgres createuser -P -s -e financer This creates a user named 'financer' and prompts for the creation of a password for this user. The expected default password is 'financer'. Then create the actual database: createdb financer Using 'financer' for the name of the user, its password and the database name is the expected default. If you want any other values you need to adjust the database connection settings of the financer application. Then you need to grant the created user permission to the created database: psql GRANT ALL PRIVILEGES ON DATABASE "financer" to financer; \q exit 12. Planned features ==================== This chapter lists planned features. The list is in no particular order: - Transaction import from online banking (file based) - Extended reports, e.g. forecasting based on recurring transactions and average spending - Receivable account type - Edit masks for accounts, transactions, recurring transactions