Add basic documentation: README, INSTALL, Architectural overview

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.