Add most of the structure! plus several Base Layer docs

docs/base/appdir.rst

@@ -0,0 +1,136 @@
+
+.. highlight:: sh
+
+App Folder
+==========
+
+Here we describe the "app folder" (aka. "app dir"), for instance at
+``/srv/envs/poser/app``, which contains all config and data for the app.
+
+Rationale
+---------
+
+We'll use a typical Linux example here.  Let's say we have a "poser" virtual
+environment in the default location.  By default the folder structure within
+the virtual environment may look something like this:
+
+.. code-block:: none
+
+   /srv/envs/poser
+   ├── bin
+   ├── include
+   ├── lib
+   │   └── python3.8
+   ├── man
+   └── share
+
+Once the Python package(s) for our app have been installed to the virtual
+environment, we will create an "app" folder in the environment root.  This app
+folder will contain all config, data and log files for the app.
+
+The idea here is that a proper (minimal) backup for the app, should only
+*require* this "app dir" but the other virtual environment folders need not be
+included in the backup (although they still can be, of course).
+
+
+Making the App Dir
+------------------
+
+This may be done with or without activating your virtual environment.
+
+If your env is activated::
+
+   rattail make-appdir
+
+If your env is *not* activated::
+
+   cd /srv/envs/poser
+   bin/rattail make-appdir
+
+
+Structure
+---------
+
+Keep in mind that the following is just an example.  Each app is unique and
+many of the folders described below can live elsewhere as long as the app is
+configured appropriately.  But this example is "typical" so its conventions
+should be used unless there is a good reason not to.
+
+For the sake of completeness here we will assume a fairly robust app, which
+uses several possible features and has been running a while.  Here is what the
+final virtual environment may look like:
+
+.. code-block:: none
+
+   /srv/envs/poser
+   ├── app
+   │   ├── data
+   │   │   ├── batches
+   │   │   │   ├── inventory
+   │   │   │   ├── vendor_catalog
+   │   │   │   └── vendor_invoice
+   │   │   ├── exports
+   │   │   │   ├── instacart_product_export
+   │   │   │   └── report_output
+   │   │   ├── templates
+   │   │   ├── upgrades
+   │   │   └── uploads
+   │   ├── log
+   │   ├── luigi
+   │   │   ├── 2020
+   │   │   ├── 2021
+   │   │   └── log
+   │   ├── luigitasks
+   │   ├── sessions
+   │   │   ├── data
+   │   │   └── lock
+   │   └── work
+   │       ├── csv
+   │       ├── generated-projects
+   │       └── user-files
+   ├── bin
+   ├── include
+   ├── lib
+   │   └── python3.8
+   ├── man
+   └── share
+
+First you may note that the above does not include a "config" folder.  All
+config files, and most scripts, will generally live directly within the "app"
+folder itself.
+
+And now for a rundown of the "important" folders you do see above:
+
+``app/data`` ideally contains all "true" data for the app.  What we mean by
+that is, any data which the app requires to be 100% fully functional.  Much of
+this data is generated by the app itself, but should remain available for later
+display within the app.
+
+``app/data/batches`` contains all data files used as input, or generated as
+output, for various "batches" within the app.
+
+``app/data/exports`` contains all "export" files generated by the app,
+e.g. when certain reports are ran etc.
+
+``app/data/templates`` may contain certain template files needed by the app
+when it is generating various kinds of output.
+
+``app/data/upgrades`` contains the before and after package snapshots, and
+command output etc. when an app upgrade is executed.
+
+``app/data/uploads`` is more of a temp folder, used to store files uploaded by
+a user within the web app, until they are further processed.
+
+``app/log`` is where all log files go for the app proper.
+
+``app/luigi`` is where Luigi (if used) will keep track of which individual
+tasks have already been ran for a given date.
+
+``app/luigi/log`` will contain log files for both the Luigi server and client.
+
+``app/luigitasks`` contains the task logic to be ran by Luigi.
+
+``app/sessions`` contains the "user session" data for the web app(s).
+
+``app/work`` is more of a temp folder; its contents may vary over time and are
+not considered essential to the app.