___ _
/ __(_)_ __ __ _ _ __ ___ ___ _ __
/ _\ | | '_ \ / _` | '_ \ / __/ _ \ '__|
/ / | | | | | (_| | | | | (_| __/ |
\/ |_|_| |_|\__,_|_| |_|\___\___|_|
1. About
2. Overview
3. Architectural overview
4. Account types
5. Booking rules
6. Account groups
7. Transactions
8. Recurring transactions
9. Transaction upload
10. Reporting
11. FQL
12. Setup
13. Links
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.
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
===============
Transactions have a type that denotes the business case:
- Asset swap: Transferring money from one asset type account (Bank, Cash) to another account of an asset type
E.g. from Bank to Cash, e.g. making a withdrawal at an ATM, B- -> C+
- Expense: Booking money for an expense from a Bank, Cash or Liability account to an Expense account
E.g. from Cash to Expense, e.g. buying goods, C- -> E+
- Liability: Paying a credit installment from an asset type account (Bank, Cash) to a Liability account
E.g. from Bank to Liability, e.g. making an installment, B- -> L-
- Income: Increasing the assets from a Start, Income or Liability account to an asset type account (Bank, Cash).
Start -> asset type account bookings need to counted as the money that was there at the starting time of
a financer instance is used for expanses.
Liability -> asset type account bookings need to counted as the money is used for expenses.
E.g. from Liability to Bank, e.g. payout of a credit, L+ -> B+
- Start liability: Booking the current balance of a liability at the inception of a financer instance
E.g. from Start to Liability, e.g. initial setup of liability amount, S+ -> L+
8. Recurring transactions
=========================
9. Transaction upload
=====================
File types + regex
10. Reporting
=============
11. FQL
=======
12. 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.
12.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
13. Links
=========
This chapter contains useful links:
- financer web page: https://financer.dev/
- financer git repository: https://77zzcx7.de/gitea/MK13/financer