Architecture
==================================

Overview
------------------------

Like many web applications today, PiAnoS is composed of 2 layers:
	
	- the server-side PHP application
	- the client-side Javascript (+ HTML + CSS) application

(general picture here, with client (FE+BE), server and database)

The server relies on PostgreSQL [#f1]_ for persistent storage, and (typically) on Apache for the execution of PHP scripts and the dispatching of static content [#f2]_. The client is downloaded by the user's browser as HTML, CSS and Javascript files. Note that unlike traditional, pre-2.0 web era applications, almost no HTML is generated by PHP itself - most is done on the client side, and PHP acts mainly as a RESTful interface to the data [#f3]_.

Further, the client-side is split into two parts: the "frontend" - the comparison interface, showing the images, tools, etc. - and the "backend" - the boring part with the menus, trees and so on. The main reason for this separation is the ability of PiAnoS to be embedded, using only the frontend. Another reason for the split is due to the development method used, where it was vital to ship the frontend before anything else, and be able to test it separately.

Also, it is to be noted that no MVC framework was used, neither for the client nor the server (only low-level libraries such as jQuery are used). This is a feature, not a political stance [#f4]_. It has the important implication that the source code may look alien at first sight - bear with it, it will not make more sense later, but you will at least know where things happen.

Finally, PiAnoS was first developed for the NIJ project (see :doc:`../credits`) and then made available as an open-source application. The initial release (4.0.0) was forked from the NIJ branch, and still has traces of this legacy. In addition, since PiAnoS is being actively used for our own research, some features are reserved for our use, and are not part of the published source code. This has numerous implications: 1) the source code you download (from the :doc:`../download` page) is different from our SVN, 2) there are undocumented features/configuration flags and 3) there is an :doc:`sdk` that provides the necessary files to develop PiAnoS.


.. rubric:: Footnotes

.. [#f1] It uses the ``pg_xxx()`` functions, not a DB abstraction layer. So, no, MySQL is not (and will never be) supported.
.. [#f2] These two components are *used by* PiAnoS, but of course, they are not *part of* it.
.. [#f3] Therefore, PiAnoS does not "degrade gracefully" when Javascript is turned off. It simply does not work at all.
.. [#f4] OK, I'm lying, but for reasons that are too long to explain here I `feel` there is something wrong/immature with these frameworks. Whether you as a developer would like to slap me, or praise me, for not using a framework is another story. And yes, there are solid frameworks emerging from the fuss (e.g. AngularJS looks promising). Maybe for PiAnoS 5.x ?
