Code layout

Django apps

We try to use standard Django conventions for code layout wherever possible. On a small scale, that means that models go in models.py, serializers go in serializers.py and so on. On a slightly larger scale, it means that we try to structure the platform code as a set of small interacting Django apps, each ideally not containing more than about five main models.

API and "normal" Django code

The Cadasta platform provides both a "normal" HTML template based front-end and a RESTful API. As much code as possible is shared between these two interfaces, and all of our apps implement both HTML and REST views in parallel. We lay things out like this:

                                          HTML   API
.
├── forms.py                               X
├── migrations/                            X      X
├── mixins.py                              X      X
├── models.py                              X      X
├── serializers.py                                X
├── templates/                             X      X
│   ├── organization/                      X
│   │   ├── organization_add.html          X
│   │   ├── ...                            X
│   │   └── user_list.html                 X
│   └── org_invite.txt                     X      X
├── templatetags/                          X
│   └── wizard_state.py                    X
├── tests/                                 X      X
│   ├── factories.py                       X      X
│   ├── test_api.py                               X
│   ├── ...                                X      X
│   └── test_validators.py                        X
├── urls/                                  X      X
│   ├── api/                                      X
│   │   ├── organizations.py                      X
│   │   ├── projects.py                           X
│   │   └── users.py                              X
│   └── default/                           X
│       ├── organizations.py               X
│       ├── projects.py                    X
│       └── users.py                       X
├── validators.py                                 X
└── views/                                 X      X
    ├── api.py                                    X
    └── default.py                         X

Here, the urls directory has api and defaults subdirectories holding URLconf definitions for API and HTML-based endpoints, and the views directory contains API and HTML views in seperate files. Tests all go in the tests directory and share factories and other test utilities. All model code is shared between the HTML-base and RESTful endpoints.