Add basic documentation: README, INSTALL, Architectural overview

brmbar3/INSTALL.md

@@ -0,0 +1,67 @@
+BrmBar v3 Installation
+======================
+
+This is woefully incomplete; if you are deploying BrmBar, at this
+point you will likely need to learn at least something aobut its
+structure and internals. Some code modifications might even be
+required too. Patches enhancing user configurability are welcome!
+
+Maybe some things are missing. Ask the developers if you get in trouble,
+e.g. in #brmlab on FreeNode.
+
+Hardware Requirements
+---------------------
+
+* Display. Current UI is optimized for 4:3, 1024x768 display.
+* Touchscreen. In emergency, you can use a mouse too, but it's
+  clumsy and scrolling is not too intuitive.
+* Barcode reader. We want the kind that will behave as a HID device
+  and on scanning a barcode, it will send a CR-terminated scanned string.
+* Physical keyboard stashed in vicinity will help. It is possible
+  to enter text (inventory names, receipt reasons) on the touchscreen,
+  but it's a bit frustrating.
+* You will want to print a sheet of barcodes with names of all user
+  accounts; these will be then used by people to buy stuff using their
+  accounts - first scan barcode of the item, then scan your barcode,
+  voila. Scanning your barcode directly can bring the user to a screen
+  where they can see their credit and charge it too.
+
+Software Requirements
+---------------------
+
+* Developed and tested on Debian, but should work on other systems too.
+* Python 3.
+* QT4 with Python bindings:
+  * QT4 with the "Declarative" module, e.g. libqt4-declarative package.
+  * The PySide Qt4 bindings, e.g. python3-pyside.qtdeclarative package.
+  * Installing the qtcreator program may be helpful for QML testing
+    and development.
+* PostgreSQL with Python pindings:
+  * The database server itself, e.g. postgresql package.
+  * PsyCoPg2, e.g. python3-psycopg2 package.
+
+Software Setup
+--------------
+
+* Create psql user and `brmbar` database.
+* The SQL schema in file `SQL` contains the required SQL tables,
+  but also INSERTs that add some rows essential for proper operation;
+  base currency and two base accounts.  You *will* want to tweak the
+  currency name; default is `Kč` (the Czech crown), replace it with
+  your currency symbol. Then do `git grep 'Kč'` and replace all other
+  occurences of `Kč` in brmbar source with your currency name.
+* Load the SQL schema stored in file `SQL` in the database (redirect
+  it to psql command standard input).
+* You should be able to fire up the GUI now and start entering data.
+  If you want to make sure all works as expected, execute the SQL
+  statements in file `SQL.test` (revisit for currency names too) which
+  will populate the database with a bit of sample data for testing.
+
+TODO: Mention the actual commands to execute.
+
+Troubleshooting
+---------------
+
+Assuming that you run brmbar from a terminal, if something gets
+stuck, you can switch to the terminal by Alt-TAB, then kill brmbar
+by the Ctrl-\ shortcut (sends SIGQUIT) and restart it.

brmbar3/README.md

@@ -0,0 +1,71 @@
+BrmBar v3
+=========
+
+BrmBar is a management system for running a tiny hackerspace shop
+with self-service usage based on trust and support for user accounts
+and inventory tracking.
+
+BrmBar offers a touchscreen-based user interface, identifies items
+and users by barcodes scanned by a barcode reader, should run on any
+decent Linux machine and stores its data in PostgreSQL database.
+
+Features
+--------
+
+* Very simple user interface (using big touchscreen buttons and
+  barcode reader) that should enable even non-technical users to
+  do basic shopping with little to no training.
+* Users may have their accounts they can load with money by
+  depositing larger sum of money in advance, then charging their
+  account when buying stuff. Of course, paying direct for cash
+  is also supported.
+* Inventory and cash accounts are tracked so that you can make sure
+  there is no Club Mate mysteriously disappearing or if the amount
+  of cash in the cash box is not less than expected by the system.
+* You can enter receipts for duct tapes and other necessities to be
+  financed by cash surplus generated by brmbar.
+* Simple management operations (depositing and withdrawing money
+  from user accounts, entering receipts, stocking in new inventory)
+  can be also performed in the user interface even by non-technical
+  users with basic training.
+* The database is based on the classical accounting paradigm.
+  This means no information is needlessly lost, you could even
+  make a GNUCash export and your accounting geeks will feel warm
+  and fuzzy.
+* Multiple user interfaces available (and possible). The primary
+  user interface is based on QtQuick (Qt4 QML QtDeclarative).
+
+User Interfaces
+---------------
+
+These UIs are provided:
+
+* **brmbar-gui-qt4**: The default touchscreen-based UI. The Python side
+  provides an adapter object whose methods can be executed by the QML
+  code; ad-hoc directionary objects are used to exchange complex data
+  like account information.
+* **brmbar-tui**: A trivial text-based "shell" UI that mimics a historic
+  interface used in the Brmlab hackerspace in the past. It supports only
+  selling items, querying item price and user account balance and
+  depositing money for the user accounts.
+* **brmbar-cli**: A command-line interface intended for use in scripts
+  and remote usage when fixing problems. It is also meant to provide
+  advanced functionality like inventory revision that is too tedious
+  to implement in the Qt4 GUI and only the brmbar admins are expected
+  to do these tasks.
+
+TODO
+----
+
+* The user interface needs some improvements, mainly regarding
+  scrolling in large lists.
+* The brmbar-cli.py admin script for advanced/remote management
+  operations is largely unfinished. In the meantime, you need to use
+  SQL statements, sorry. Or finish it yourself. :-)
+* It is common to have two stashes of cash, one in a cash box
+  in the shop, another in a vault (sometimes called "overflow")
+  where extra cash is stored.  The brmbar model supports this,
+  but UI support needs to be added.
+* Bitcoin support, somehow...
+
+Some more TODO items may be listed in the GitHub issue tracker.

brmbar3/doc/architecture.md

@@ -0,0 +1,106 @@
+BrmBar v3 - Architectural Overview
+==================================
+
+BrmBar v3 is written in Python, with the database stored in PostgreSQL
+and the primary user interface modelled in QtQuick. All user interfaces
+share a common *brmbar* package that provides few Python classes for
+manipulation with the base objects.
+
+Objects and Database Schema
+---------------------------
+
+### Account ###
+
+The most essential brmbar object is an Account, which can track
+balances of various kinds (described by *acctype* column) in the
+classical accounting paradigm:
+
+* **Cash**: A physical stash of cash. One cash account is created
+  by default, corresponding to the cash box where people put money
+  when buying stuff (or depositing money in their user accounts).
+  Often, that's the only cash account you need.
+* **Debt**: Represents brmbar's debt to some person. These accounts
+  are actually the "user accounts" where people deposit money. When
+  a deposit of 100 is made, 100 is *subtracted* from the balance,
+  the balance is -100 and brmbar is in debt of 100 to the user.
+  When the user buys something for 200, 200 is *added* to the balance,
+  the balance is 100 and the user is in debt of 100 to the brmbar.
+  This is correct notation from accounting point of view, but somewhat
+  confusing for the users, so in the user interface (and crbalance
+  column of some views), this balance is *negated*!
+* **Inventory**: Represents inventory items (e.g. Club Mate bottles).
+  The account balance represents the quantity of items.
+* **Income**: Represents pure income of brmbar, i.e. the profit;
+  there is usually just a single account of this type where all the
+  profit (sell price of an item minus the buy price of an item)
+  is accumulated.
+* **Expense**: This type is currently not used.
+* **Starting balance** and **ending balance**: This may be used
+  in the future when transaction book needs to be compressed.
+
+As you can see, the amount of cash, user accounts, inventory items
+etc. are all represented as **Account** objects that are of various
+**types**, are **named** and have a certain balance (calculated
+from a transaction book). That balance is a number represented
+in certain **currency**. It also has a set of **barcodes** associated.
+
+### Currency, Exchange rate ###
+
+Usually, all accounts that deal with cash (the cash, debt, income, ...
+accounts) share a single currency that corresponds to the physical
+currency locally in use (the default is `Kč`). However, inventory
+items have balances corresponding to item quantities - to deal with
+this correctly, each inventory item *has its own currency*; i.e.
+`Club Mate` bottle is a currency associated with the `Club Mate`
+account.
+
+Currencies have defined (uni-directional) exchange rates. The exchange
+rate of "Kč to Club Mate bottles" is the buy price of Club Mate, how
+much you pay for one bottle of Club Mate from the cash box when you
+are stocking in Club Mate. The exchange rate of "Club Mate bottle to Kč"
+is the sell price of Club Mate, how much you pay for one bottle of Club
+Mate to the cash box when you are buying it from brmbar (sell price
+should be higher than buy price if you want to make a profit).
+
+Exchange rate is valid since some defined time; historical exchange
+rates are therefore kept and this allows to account for changing prices
+of inventory items. (Unfortunately, at the time of writing this, the
+profit calculation actually didn't make use of that yet.)
+
+### Transactions, Transaction splits ###
+
+A transaction book is used to determine current account balances and
+stores all operations related to accounts - depositing or withdrawing
+money, stocking in items, and most importantly buying stuff (either for
+cash or from a debt account). A transaction happenned at some **time**
+and was performed by certain **responsible** person.
+
+The actual accounts involved in a transaction are specified by a list of
+transaction splits that either put balance into the transaction (*credit*
+side) or grab balance from it (*debit* side). For example, a typical
+transaction representing a sale of Club Mate bottle to user "pasky"
+would be split like this:
+
+* *credit* of 1 Club Mate on Club Mate account with memo "pasky".
+* *debit* of 35 Kč on "pasky" account with memo "Club Mate"
+  (indeed we _add_ 35Kč to the debt account for pasky buying
+  the Club Mate; if this seems weird, refer to the "debt" account
+  type description).
+* *debit* of 5 Kč on income account Profits with memo "Margin
+  on Club Mate" (this represents the sale price - buy price delta,
+  i.e. the profit we made in brmbar by selling this Club Mate).
+
+The brmbar Python Package
+-------------------------
+
+The **brmbar** package (in brmbar/ subdirectory) provides common brmbar
+functionality for the various user interfaces:
+
+* **Database**: Layer for performing SQL queries with some error handling.
+* **Currency**: Class for querying and manipulating currency objects and
+  converting between them based on stored exchange rates.
+* **Account**: Class for querying and manipulating the account objects
+  and their current balance.
+* **Shop**: Class providing the "business logic" of all the actual user
+  operations: selling stuff, depositing and withdrawing moeny, adding
+  stock, retrieving list of accounts of given type, etc.