.. 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.