Improve docs.

[xnet] / doc / architecture.rst

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

The plat/al project relies heavily on Django's notion of applications.


Applications
------------

Each functional unit (events, news, groups, accounts, profiles, payments, ...)
should live in its own Django app.

Such apps should follow the following layout:

- ``__init__.py``: Mandatory for Python, should be empty
- ``models.py``: Required by Django, contains all models
- ``admin.py``: A (properly designed) Admin for each model
- ``factories.py``: The set of `factories <http://factoryboy.rtfd.org/>`_ related to the models
- ``tests.py``: The set of tests for the app

If the application contains views, it should include the following files:

- ``forms.py``: Home of the forms used in the app (if any)
- ``views.py``: All view definitions
- ``urls.py``: URL map of the application, to be included in ``xnet.urls``
- ``templates/my_app/base.html``: Base template for the application.
  Can be simply:

  .. code-block:: html

      {% extends "base.html" %}

- ``templates/my_app/foo.html``: app-specific templates. They should all inherit
  from ``my_app/base.html``.


External libraries
------------------

Whenever a functionality can be provided by an external, existing library,
that library should be added to the dependencies (and not copied to our code).

- If it's a "production" dependency, add it to ``requirements.txt``.
- If the dependency is only useful for development / testing / ..., add it to ``dev_requirements.txt``
- Until plat/al has reached production, avoid too specific version ranges;
  use ``foo>=1.1.3`` if using a feature only available in v1.1.3,
  and avoid ``foo=1.1.3`` that would prevent us from seeing new features of the lib.


Internal libraries (utilities)
------------------------------

Utilities should be placed in the ``xnet/utils/`` folder, with one "app" per subject.
For instance, time-related functions could be provided in ``xnet/utils/time`` while
image-related tools would live in ``xnet/utils/image``.