qraat-ui_spec1.txt

QRAAT user interface v 1

A first cut version of the QRAAT user interface. This specification is meant to 
for a prototype web front end for managing the QRAAT system. Subsequent versions
will be have more adminstrator control and restrict user functionality in an 
intelleigent way. This version puts a lot of trust in users. Refer to 
QRAAT-doc/database/db_schema_proposal.sql for database schema on hand. 


Sessions & Users
----------------

Types:
 
  visitor
  user
  owner
  admin
  viewer (group)
  collaborator (group)  

A QRAAT user has a an account set up in our system. A visitor is someone who 
views our website without logging in. Sessions will be protected by using HTTPS
in conjunction with our web framework.

User authentication and access control will be handled in the web framework in a
database independent of the main QRAAT database. Administrators will create 
user accounts manually. Users will have the fields first_name, last_name, 
email, and password. We will send new users temporary passwords. They should be
able to change their password (by retyping the old one) at anytime [1]. 

Inactive sessions are not allowed. When a user ends the session, i.e. closes
the browser window, she must login again the next time she goes to the site. 


Projects & Deployments
----------------------

A project can be created by any user, who then becomes the sole owner of the project.
Transmitters, targets, deployments, and sites of interest are permannently 
associated to a project (`qraat.project.ID`). The owner maintains a group of 
'viewers', who are allowed to view these metadata as well as tracking data 
associated to deployments, and a group of 'collaborators'. The right to add, edit, 
or delete project metadata is granted to the owner and collaborators. Finally,
the owner can mark a project as public; in this case, the viewers group becomes 
all users and visitors. (`qraat.project.is_public`.)

Transmitters and targets can only be used in deployments within the same 
project. The purpose of this is to maintain provenance for tracking data 
associated to deployments. If project owners wish to exchange transmitter or
target metadata data, they must create new objects for their project.

A deployment associates a target with a transmitter and is marked active by a 
a flag `qraat.deployment.is_active`. This flag can be changed at any time. A 
transmitter or target may only be used in one deployment at a time. 

  [Future version.] we'll implement a mechanism for making sure there are no 
  collisions in the transmitter bandwidth space; for now, we'll trust users 
  to make sure their frequencies aren't being used. 

  [Future version.] For purpose of managing transmitter bandwidth among many 
  projects, we will implement a more sophisticated administrator role in which 
  the admin assigns bandwidth to a given project for a given period of time,
  e.g. Jan 2015 - Feb 2015. 


Transmitters 
------------

Users may add new transmitters and targets to their own projects, subject to the
constraints described above. Each transmitter has a frequency, name, serial 
number, and make. The user must choose a transmitter make from the choices 
provided in `qraat.tx_make`. This table contains transmitter manufacturuer and 
models, and the domodulation type of the transmitter make ('pulse', 'cont', 
'afsk'). The table `qraat.tx_parameters` contains algorithm parameters for the 
transmitters' signal demodulation. We provide default values for various 
transmiter models. 

The user experience of entering transmitters will be something like this: 

  Name:            Transmitter1
  Serial No.* :    134849y63104f
  Frequency (Mhz): 164.432 
  Make:            [Drop down menu, select manufacturuer and model] -> ATS #M1520

Table `qraat.tx_make` and `qraat.tx_make_parameters` are maintained by the
admins. Once the user has finished entering these values and has selected a 
make type, clicking "apply changes" will create a new entry in `qraat.tx` and 
several new entries in `qraat.tx_parameters`. In particular, suppose we build
a dictionary from `qraat.tx_make_parameters` like so: 

  a = {'param1' : ('val1', 'units1') ... 'paramN' : ('valN', 'unitsN'} <- 
                                           `SELECT * 
                                              FROM qraat.tx_make_paramters
                                             WHERE tx_makeID = <tx_make_id>;`

Then for each (name, (value, units)) in a, we do 

  `INSERT INTO qraat.tx_paramaters (txID, name, value, units) VALUE (<tx_id>,
    <name>, <value>, <units>;`

where tx_id corresponds to the transmitter just added. 

 
Targets
-------

These just have two fields (for now): name and description. There's no 
restrictions on data entry here. 
 
  [Future version.] Physical characteristics of target, such as height, weight,
  age, sex, etc. 
  
  [Future version.] Default algorithm parameters for tracking. 


Editing/removing metadata elements
----------------------------------

Actual data is restricted to read only for users. Tables in the schema containing
data are `est`, `estscore`, `position`, `bearing`, and `track_pos`. Each of these 
has an associated deployment, i.e., `qraat.*.deploymentID` references 
`qraat.deployment.ID`. It is critical for system integrity that we don't allow 
users to delete or modify deployments for which there is associated data. 

We have chosen a data model in which metadata can't be deleted directly by a 
user. This is meant to deal with the above criterion, as well as to prevent 
untrusted UI from inadvertantly affecting others' metadata. If a user wishes to 
delete a metadata element, the column `qraat.*.is_hidden` is marked as true. 
This affectively hides the entry in the user interface without actually deleting 
it. 

  [Future version.] A backend system process will be written to clean up junk 
  data, partially assisted (in some way) by an admin. 

Many metadata parameters can be modified safely (i.e. calling UPDATE on a row),
but there are some that must result in a new metadata element being created. For
example, suppose a user creates a new transmitter for a new deployment. If 
he accidently inputted the wrong frequency, the system could have already 
collected data for the deployment. Even though this is likely junk, one of our
design goals is to maintain provenance for all data collected. To deal with this,
we'll require the user to input a new transmitter and deployment. (The previous
deployment should be marked as inactive). 

In general, there are a number of parameters related to data capture which are 
unsafe to modify if involved in a deployment. These are qraat.tx.serial_no, 
qraat.tx.frequency, qraat.tx.tx_makeID, and anything in qraat.tx_paramters where
`txID` is the transmitter on hand. If the user wants to edit these and the 
transmitter is associated with any deployment (active or inactive, hidden or 
visible), then the UI should prompt them to insert a new transmitter.

  [Future version.] It should be possible to make this experience seemless for 
  users. In other words, if a user wants to modify a transmitter, a new 
  transmitter and deployment are created and the old deployment is hidden from
  view.


Input field validation
----------------------

The user interface will ensure that entered values are of the correct format 
and/or within a valid range. In order to prevent SQL injection attacks, we 
must take special care when performing database queries on user-inputted data. 
In Python, this is a matter of careful use of the cursor.execute() method. 
for example: 

  def handle_post_request(db_con, post_data):
    # Handle session authenticaiton, make sure UUID has 
    # write access on the current project ... 
    cur = db_con.cursor()
    cur.execute('''UPDATE qraat.project 
                      SET description = %s
                    WHERE ID = %s''', 
          (post_data.description, post_data.proj_id))

is OK. On the other hand: 

  def handle_post_request(db_con, post_data):
    # Handle session authenticaiton, make sure UUID has 
    # write access on the current project ... 
    cur = db_con.cursor()
    cur.execute('''UPDATE qraat.project 
                      SET description = '%s'
                    WHERE ID = %s''' %  
          (post_data.description, post_data.proj_id))

is BAD! The string `post_data.description` can be formatted to inject SQL
syntax into the string passed into execute(). If the data are passed into 
execute() as a tuple, then execute() escapes the input strings such that 
they're interpreted as such. 

  [Future version.] The database schema should be modified to specify correct 
  formats / valid data ranges. 



[1] [Future version.] We may require the user to wait a certain amount of time 
    (say 5 minutes) between password resets. 

[2] Need to make sure this is a valid assumption. However this is meant to be
    "good enough" for now.