+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``.
+
+
+