Developer/BMON-Architecture.md

@@ -109,3 +109,93 @@ These chart classes all must have a `result()` method that returns the report/ch
 
 Transforms are used to convert incoming sensor readings to different units and are described in [[this document|Transform Expressions]].  All code related to transforms is present in [[this module|https://github.com/alanmitchell/bmon/blob/master/bmsapp/calcs/transforms.py]].  [[Calculated Fields]] allow for new sensor readings to be created from mathematical combinations of other readings or from acquistion from the Internet.  The general code for creating calculated fields is in [[this module|https://github.com/alanmitchell/bmon/blob/master/bmsapp/calcs/calcreadings.py]].  The specific calculated field functions are currently found in the [[calcfuncs01.py|https://github.com/alanmitchell/bmon/blob/master/bmsapp/calcs/calcfuncs01.py]] module, although other modules could be created to hold specific calculated field functions.  A Cron job runs [[main_cron.py|https://github.com/alanmitchell/bmon/blob/master/bmsapp/scripts/main_cron.py]] which in turn runs [[calc_readings.py|https://github.com/alanmitchell/bmon/blob/master/bmsapp/scripts/calc_readings.py]] to control the process of creating calculated fields.
 
+### Main Cron Job
+
+BMON utilizes the Linux Cron utility to run a script that performs a number of tasks that are repeated at equal time intervals.  (A better design may have been to start a separate thread in BMON to perform this repetitive task.)  As shown in the [[BMON Installation Guide|How to Install BMON on a Web Server]], the Cron job entry looks like the following (the directory paths are dependent on your specific install):
+
+    */5 * * * * ~/webapps/bmon_django/bmon/manage.py runscript main_cron > /dev/null 2>&1
+
+This cron job:
+* creates calculated reading values and stores Internet weather data in the reading database every half hour,
+* checks for active Alert Conditions every five minutes,
+* creates a daily status line in the log file indicating how many sensor readings were stored in the database during the past day (viewable by browsing to `<Domain URL>/show_log`), and
+* creates a backup of the reading database every three days.
+
+The Cron job executes the [[main_cron.py|https://github.com/alanmitchell/bmon/blob/master/bmsapp/scripts/main_cron.py]] script by using the [[Django Extensions runscript feature|http://django-extensions.readthedocs.org/en/latest/runscript.html]].  This runscript command allows the scripts to operate within the Django context, having full access to Django models and the settings file, for example.
+
+---
+
+## Details on Django Web Browser Application
+
+The BMON Django server application delivers content to the BMON web browser application, which consists of HTML and JavaScript.  The browser application provides the user interface for users that are viewing and analyzing the sensor data and configuring the BMON application through the Django Admin interface.
+
+For the Alaska Housing Finance Corporation installation of the BMON application, there are three main BMON pages displayed for the data-viewing user (not the Admin user):
+
+* A Map page that displays a Google map with clickable dots at the locations of the buildings containing sensors.
+* The main Charts/Reports page of the application where the user can view and analyze the sensor data.
+* A Training page with some video tutorials and report information.
+
+The choice of main pages is somewhat configurable through the Django settings file.  Here is the section of the settings file that allows configuration and selection of the Default page that will show when a user browses to the base URL for the application:
+
+```python
+# Information about the Navigation links that appear at the top of each web page.
+#     First item in tuple is Text that will be shown for the link.
+#     Second item is the name of the template that will be rendered to produce the page.
+#          'reports' is a special name that will cause the main reports/charts page to be
+#          rendered.  For other names in this position, there must be a corresponding 
+#          [template name].html file present in the templates/bmsapp directory.  The custom
+#          template cannot match any of the URLs listed in urls.py.
+#     The third item (optional) is True if this item should be the default index page for
+#         the application.
+BMSAPP_NAV_LINKS = ( ('Map', 'map'),
+                     ('Data Charts and Reports', 'reports', True),
+                     ('Training Videos and Project Reports', 'training_anthc'),
+                   )
+
+```
+
+The main Charts/Reports page is the core of the application.  It functions as a [[Single Page Application|https://en.wikipedia.org/wiki/Single-page_application]].  With the initial loading of that page, all of the static HTML of the page and all of HTML Input elements are downloaded from the server.  As the user changes inputs, AJAX calls are made to the server to update the contents of various selection inputs (e.g. update the sensor selection dropdown due to a new building being selected) and to update the final chart or report results.  
+
+As discussed before, each type of chart or report has Python class on the server that is responsible for generation of the chart/report.  Each one of those classes also contains some configuration properties that control:
+
+* which HTML input elements are visible in the browser client for that chart type,
+* whether multiple sensors can be selected for this chart type,
+* whether the chart or report should be automatically refreshed when inputs change,
+* whether an automatic timed refresh of the chart or report should occur every 10 minutes.
+
+In the `BaseChart` class from which all chart/report classes inherit, you can see the class properties that control these elements of the browser interface described above:
+
+```python
+class BaseChart(object):
+    """Base class for all of the chart classes.
+    """
+
+    # Constants to override, if needed for the specific chart being created.
+    # These constants affect configuration of the browser user interface that 
+    # will be used for this particular chart.
+
+    # This is a comma-separated list of the client HTML controls that need to be
+    # visible for this chart.
+    CTRLS = 'time_period, refresh'
+
+    # 1 if the Sensor selection control should allow for selecting more than one
+    # sensor.
+    MULTI_SENSOR = 0
+
+    # 1 if the chart should automatically recalculate and refresh when the user 
+    # changes inputs.
+    AUTO_RECALC = 1
+
+    # 1 if the chart should automatically refresh every 10 minutes even without 
+    # changes in user inputs
+    TIMED_REFRESH = 0
+```
+
+The Django chart/report class that is responsible for creating the main content for the chart controls which Input elements are needed for the chart.  [[The main JavaScript file for the browser app|https://github.com/alanmitchell/bmon/blob/master/bmsapp/static/bmsapp/scripts/bmsapp.coffee]] controls the visibility of those Inputs.  
+
+
+* Config of pages
+* Single Page App
+* Chart type determines visibility of controls, recalc settings
+* AJAX calls to refresh input control contents & results
+* Two JS files, main and dashboard, created with CoffeeScript
\ No newline at end of file