.. vim: set fileencoding=utf-8 :

.. Copyright (c) 2016 Idiap Research Institute, http://www.idiap.ch/          ..
.. Contact: beat.support@idiap.ch                                             ..
..                                                                            ..
.. This file is part of the beat.web module of the BEAT platform.             ..
..                                                                            ..
.. Commercial License Usage                                                   ..
.. Licensees holding valid commercial BEAT licenses may use this file in      ..
.. accordance with the terms contained in a written agreement between you     ..
.. and Idiap. For further information contact tto@idiap.ch                    ..
..                                                                            ..
.. Alternatively, this file may be used under the terms of the GNU Affero     ..
.. Public License version 3 as published by the Free Software and appearing   ..
.. in the file LICENSE.AGPL included in the packaging of this file.           ..
.. The BEAT platform is distributed in the hope that it will be useful, but   ..
.. WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ..
.. or FITNESS FOR A PARTICULAR PURPOSE.                                       ..
..                                                                            ..
.. You should have received a copy of the GNU Affero Public License along     ..
.. with the BEAT platform. If not, see http://www.gnu.org/licenses/.          ..


.. _hardwarerequirements-applications:

Software Organization
=====================

BEAT is currently packaged as 5 separate projects. We describe them on this
section.


beat.backend.python
-------------------

``beat.backend.python`` defines the minimal set of components that are required
by **user code** to be able to run and communicate with the BEAT platform
backend. These are:

* **Data formats**: the specification of data which is transmitted between
  blocks of a toolchain;
* **Libraries**: routines (source-code or binaries) that can be incorporated
  into other libraries or user code on algorithms;
* **Algorithms**: the program (source-code or binaries) that define the user
  algorithm to be run within the blocks of a toolchain;


beat.core
---------

``beat.core`` defines a set of core components useful for the whole platform:
the building blocks used by all other packages in the BEAT software suite (c.f.
the BEAT public API). ``beat.core`` extends the models defined by
``beat.backend.python``, completing full experiment description:

* **Toolchain**: the definition of the data flow in an experiment, as a set of
  interconnected blocks;
* **Databases** and **Datasets**: means to read raw-data from a disk and feed
  into a toolchain, respecting a certain usage protocol;
* **Experiment**: the reunion of algorithms, datasets, a toolchain and
  parameters that allow the platform to schedule and run the prescribed recipe
  to produce displayable results.

All other BEAT packages depend directly on ``beat.core``.


beat.web
--------

``beat.web`` defines the application layer containing an implementation of the
web, scheduler and worker components of the platform. The web application, in
particular, provides a Representational State Transfer (ReSTful) API for some
of the services that are provided by the platform, together with a web-based
user interface in which users can register and interact with experiments and
generated results. The web server is written in Python using a well-established
library for such a purpose called `Django`_, while powerful Javascript
libraries are used for the dynamic behaviour of the client-side user interface.
A database backend is deployed to store all the information about the users,
experiments, their state and all other core objects. `Django`_ supports several
database backends, both serverless such as `SQLite`_ and dedicated running
servers such as `PostgreSQL`_.

``beat.web`` also ensures privacy and confidentiality, allowing users to access
resources, prepare new experiments and control the amount of information that
will be shared with other users of the platform.

The web application communicates with the scheduler, via the shared database,
to execute and to manage user experiments.


beat.examples
-------------

This package contains installable examples for all BEAT platform components and
can be used to bootstrap a new platform for development and testing purposes.
This package cannot be used by itself. It is automatically imported and used
from ``beat.web``.


beat.cmdline
------------

This package contains a command-line client that uses the BEAT web ReSTful API
to copy and synchronize local versions of objects installed in a given
platform. It can be used to copy full experiments locally and to **run**
experiments using the local machine for debugging purposes. This package
provides its own documentation set with instructions and examples show how to
use it.


.. Place your references here

.. _django: http://www.djangoproject.com
.. _sqlite: http://www.sqlite.org
.. _postgresql: http://www.postgresql.org