  Copyright (C) 2011 Appora contributors.
  Licenced under CC BY-SA 3.0
  (see <http://creativecommons.org/licenses/by-sa/3.0/>)

This notice is intended for developers to understand and modify/make upgrades of
the software.

SERVER ARCHITECTURE
-------------------

The server is broken in multiple independent modules that can be implemented in
multiple ways. Each of these modules is represented by a directory giving
interfaces for all implementations and subdirectories for each implementation.

Thus the server can be set up with the desired modules implementations, but
requires an implementation for each one.

The env.php script sets the server architecture settings, i.e. where the modules
are.

All actions are targeted at the index.php script that will set an environment
(server configuration) and execute the requested service.


DIRECTORIES
-----------

TOOLS (set in $_TOOLS_DIR)

Tools is not a module. It holds independent scripts to be used by other modules.
The tools are not designed to be modular and reimplemented.


MODELS (set in $_MODELS_DIR)

Like tools, models is not a module. Models are scripts for data holding, as in
the Model/View/Controller pattern.


DESCRIPTORS MODULE (set in $_DESC_MODULES_DIR)

The descriptors modules support getting informations about applications
registered in the repository, but not the applications themselves.


DATA MODULE (set in $_DATA_MODULES_DIR)

The data modules are responsible of getting application data for installation
and other binary data such as icon or screenshots.


CLIENTS SERVICES (set in $_SERVICES_DIR)

Client services are implementation of actions. Theses services are included in
index.php.

Client services makes connection to other modules as required through the server
configuration.


LOGGER MODULE (set in $_LOGGER_MODULES_DIR)

The logger modules log information mainly for maintenance. When an error occurs
or something usefull should be registered somewhere while executing a script,
the logger module handles it.


CONFIGURATION MODULE (set in $_CONFIG_DIR)

The configuration module is used to set up the server, choose which module
implementation to use and configure them if necessary.

As the configuration module cannot configure itself, the index.php script
defines which configuration module to use and configure it.

This is the only module that requires source modification to change it.


RESOURCES

Resources holds samples and documentation about module setup and configuration.
This directory is not part of the effective server and can safely not be
deployed or even deleted.


SERVER ENVIRONMENT
------------------

Environment is set up in index.php in $server variable. This environment is
meant to be accessible only in client services. Other modules should not rely
on it to avoid strong dependency to server implementation.


CODING STYLE
------------

The following coding style is applyed to the source code :
- each line should be shorter than 80 characters (considering 4 spaces tabs)
- all classes name begins with an uppercase, the rest is camelCase
- multiple lines instruction gets a double identation (i.e. 8 spaces more on the
    second and following line as the first one)
- operators on multiple line instructions are at the begining of the line (and
    not at the end of the previous one)
- operators are separated of operands by a space
- a space is left after keywords and opening parenthesis, but not after
    functions
- opening curves are on the same line as code, separated by a space
- constants are in upper cases with underscores as word separators
- abstract classes have an uppercase A prefix
- interfaces have an uppercase I prefix
- classes and functions documentation is javadoc styled
