git.polytechnique.org Git - xnet/blob - doc/architecture.rst

   1 Architecture
   2 ============
   3
   4 The plat/al project relies heavily on Django's notion of applications.
   5
   6
   7 Applications
   8 ------------
   9
  10 Each functional unit (events, news, groups, accounts, profiles, payments, ...)
  11 should live in its own Django app.
  12
  13 Such apps should follow the following layout:
  14
  15 - ``__init__.py``: Mandatory for Python, should be empty
  16 - ``models.py``: Required by Django, contains all models
  17 - ``admin.py``: A (properly designed) Admin for each model
  18 - ``factories.py``: The set of `factories <http://factoryboy.rtfd.org/>`_ related to the models
  19 - ``tests.py``: The set of tests for the app
  20
  21 If the application contains views, it should include the following files:
  22
  23 - ``forms.py``: Home of the forms used in the app (if any)
  24 - ``views.py``: All view definitions
  25 - ``urls.py``: URL map of the application, to be included in ``xnet.urls``
  26 - ``templates/my_app/base.html``: Base template for the application.
  27   Can be simply:
  28
  29   .. code-block:: html
  30
  31       {% extends "base.html" %}
  32
  33 - ``templates/my_app/foo.html``: app-specific templates. They should all inherit
  34   from ``my_app/base.html``.
  35
  36
  37 External libraries
  38 ------------------
  39
  40 Whenever a functionality can be provided by an external, existing library,
  41 that library should be added to the dependencies (and not copied to our code).
  42
  43 - If it's a "production" dependency, add it to ``requirements.txt``.
  44 - If the dependency is only useful for development / testing / ..., add it to ``dev_requirements.txt``
  45 - Until plat/al has reached production, avoid too specific version ranges;
  46   use ``foo>=1.1.3`` if using a feature only available in v1.1.3,
  47   and avoid ``foo=1.1.3`` that would prevent us from seeing new features of the lib.
  48
  49
  50 Internal libraries (utilities)
  51 ------------------------------
  52
  53 Utilities should be placed in the ``xnet/utils/`` folder, with one "app" per subject.
  54 For instance, time-related functions could be provided in ``xnet/utils/time`` while
  55 image-related tools would live in ``xnet/utils/image``.
  56
  57
  58