| 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 | |