Add README and LICENSE

1 files changed, 74 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..ea18af5
--- /dev/null
+++ b/README
@@ -0,0 +1,74 @@
+JImbrella
+=========
+JImbrella (portmanteau of "JI Umbrella") is a suite of tools that track
+a number of umbrellas at the gate of Long Bin Building (LBL), Shanghai
+Jiao Tong University. This is an ongoing project managed by JI Belief,
+the aim of which is to shield everyone's commute from unexpected
+precipitation.
+
+Note that JImbrella is merely the software, and is independent from JI
+Belief's project. It may be abandoned at any time should JI Belief find
+a better competitor at tracking umbrellas. I, the developer of
+JImbrella, is NOT affiliated with JI Belief except for the agreement to
+develop, maintain and possibly provide sysadmin service for JImbrella.
+
+This is open source software licensed under BSD-2-Clause.
+
+Workflow
+--------
+Here is an image of what JImbrella would integrate with the workflow at
+version 1.0.
+
+For the time being, there are 20 umbrellas in service, each secured by
+a physical lock on a umbrella stand. A respective key, which is held by
+the security staff by default, is needed to unlock each one.
+
+Anyone who wishes to borrow one of the umbrellas must fill in a jForm
+answer sheet asking for the information as follows:
+
+- Name
+- Student/faculty ID
+- Phone number
+- Key number (must correspond to a lock with umbrella present)
+
+JImbrella will poll jForm for recent answer sheets, and update its own
+database accordingly. If a person is found to have borrowed their
+second umbrella or beyond, or if they are blacklisted (due to bad
+records), an SMS will be sent via an online service to them, warning
+them of their violation of the Honor Code - ahem, no, Terms of Service.
+(We do this because there is no way to tell jForm to reject particular
+answer sheets. However, because the interval between two polls cannot
+be infinitely small, the SMS warning might be way past the security
+handing over the key.)
+
+They will subsequently be handed the key to the lock, using which they
+may temporarily possess and use the umbrella. The person is now called
+a "tenant".
+
+The tenant may possess the umbrella for up to 3 days, which JImbrella
+interprets as 72 +/- 1 hours. Over this period, the tenant must keep
+the keys, with which to return the umbrella.
+
+In case the tenant has kept the umbrella past due, JImbrella will send
+an SMS reminding them to return it. If no action is taken on the tenant
+side for 48 hours, JImbrella will send a harsher SMS warning. The
+details of JImbrella's social aspects are left to JI Belief.
+
+JImbrella provides a web console for the administrators of JI Belief,
+on which to:
+
+- View or modify statuses of all umbrellas;
+- View logs;
+- View or modify the blacklist.
+
+Of course, the admins will have to be authenticated. Apart from a web
+console, which I will try to make JavaScript-free, a REST API will be
+available, some of its endpoints open to the public.
+
+Upon return, the tenant must hand over the umbrella and the key. Losing
+or damaging either will lead to human intervention, and is out of scope
+of JImbrella. Given both the umbrella and the key are intact, the
+tenant must fill in another jForm asking the same questions as the one
+above, to finish the cycle.
+
+This project is WIP.