Development documentation

Introduction

This is the documentation for developers of the v2 version of Agora Ciudadana. The development of this version is currently ongoing and not yet finished. This should serve as a base for those who want to get a grasp of how the code is laid out and how it works. Hopefully you end up contributing too.

Agora is based in django for the server backend and backbone in the web frontend. The communication between those two is based on the Agora REST API v1. This JSON API allows all the operations needed to work in Agora: vote, create agoras, list users, anything.

Backend

The backend is based on the django framework and basically provides a JSON API. So it's not a typical traditional django web site with the usual views and templates. The core of the code is provided in the directory agora_site/agora_core.

Follows a short explanation of the important files and directories found in agora_site/agora_core:

admin.py

Django admin interface is defined here.

ajax.py

Legacy code, soon to be removed.

api.py

The REST API is constructed here. We use django-tastypie framework to define the API. In this file we only construct the API with the resources defined in resources/.

fixtures/

Directory containing json data (fixtures) that is loaded elsewhere. Currently it contains fixtures used in unit tests defined in tests.py

forms/

Django forms used in the API. It's organized as one file per django model (agora.py, election.py, etc). This organization is used also in other directories later.

It has turned out useful to use django forms in resources to parse data coming from the user, and then execute whatever is needed in the save function of the form if data was validated. Inside a resource, a form can be used this way, in an url calling to wrap_form function.

management/

Here you can find defined some handy django management commands for this agora_core django app.

migrations/

Agora uses south for controlling the migrations of the models. This directory contains those migrations.

models/

Here you can find defined, one per file, the models used in the application. There are not many: profile, used to extend the basic information django stores about an user; agora, which defines a decision taking space; election and castvote.

Useful member functions are defined in the models; for example, The "Agora" model defines a get_open_elections() function.

Agora features its own permission system. It's based on django model level permissions and django-guardian object level permissions, but more flexible: each model who wants to support agora-type permissions defines a has_perms(self, perm, user) function and/or static_has_perms(perm, user), and returns a boolean. Another useful function that can be defined is get_perms(self, user), which returns the list of allowed permissions for a given user.

This permission system is quite flexible because it's up to you what to do in those functions: for example Agora.static_has_perms('create', user) depends on django settings, Agora.has_perms('join') depends on the agora membership_policy field and Agora.has_perms('cancel_membership_request') depends on an object level permission set using django-guardian.

resources/

This directory contains the files defining, in a one per model basis, the resources of the REST API. An interesting note is that permissions can be checked using the permission_required decorator defined in agora_site/misc/decorators.py

search_indexes.py

Agora uses django haystack for search. This file is used by haystack to index models.

tasks/

Agora uses celery for delayed task execution. In the files inside this directory (a file per model as usual) you can find the tasks defined in Agora.

Delayed task execution is important so that for example an election can be programmed to start and end at a given date in an automatic manner. It's also important to use it when a task that can be quite large needs to be done: for example when sending mass emails to the users, instead of sending the emails directly within the view that triggers the mass mailing, it's should be done as a task. This allows the view to finish always rapidly while the mailing happens in background.

templates/

Directory containing the templates of the django application. Contains legacy code that will be removed soon, and also the email templates.

templatetags/

Directory containing files with useful template tags used in templates.

tests/

Directory containing the unit tests of the REST API. When adding new functionality to the API please always update and improve the unit tests, code that is not covered by unit tests gives us insecurity.

urls.py

Defines the urls of the django application. Contains lots of legacy urls that will be removed soon.

views.py

Defines lots of legacy views that will be removed soon.

Frontend

The work in the frontend in v2 has not yet started because the API is not mature enough. The frontend will be based on backbone and will also be based on the current Agora look of the application, that uses Twitter Bootstrap.