Improve docs.

[xnet] / doc / architecture.rst

diff --git a/doc/architecture.rst b/doc/architecture.rst
new file mode 100644 (file)
index 0000000..af7d77f
--- /dev/null
+++ b/doc/architecture.rst
@@ -0,0 +1,58 @@
+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``.
+
+
+