Design document

[Magnus Gustavsson]

Klistrar här in Roberts designdokument, det finns även tillgängligt som pdf-fil.
http://aktivdemokrati.se/wp-content/uploads/2012/01/001-Design.pdf

Design Specification: The Democracy System
This document describes the design outline for the democracy system which is a web
application for continuous direct democracy.
Release numbers
Anything which does not have a release number is assumed to be in the first release. A release
tag looks like "[release 4]"

Notes of things to change
1. The whole process of reviewing approved propositions before they become
"activated" will be removed. Instead there will only be one single list of approved
propositions and if some proposition contradicts the constitution or regulation of the
organization, someone has to make an independent report to the suitable authority
within the organization. This will largely simplify that part of the system. This change
is yet to be done in the rest of the document. (this is anyway an issue for release 3 or
more)
English/Swedish dictionary
Some documents of Aktiv Demokrati are written in Swedish, so this dictionary of used terms
might be useful, especially to Swedish developers.
English Swedish
Overview Page
Member Listing Page
Member Profile Page
User Settings Page
Login Page
Admin Page
Active Propositions Page
New proposition Page
View Proposition Page
Propositions vote Page
Propositions view Page
Propositions Waiting for Permission Page
Grant permission to proposition page
Approved Propositions Page
Propositions under review Page
Review Propositions page
Pending decisions Page
Activated decisions Page
Cancelled propositions Page
Rejected propositions Page
Accumulated support
Momentary support
Democratic constant
Översiktssida
Medlemslista
Användarprofil
Användaringställningar
Loginsida
Administratörssida
Förslag under omröstning
Nytt förslag
Förslagssida
Omröstningssida
Förslagslista
Förslag på remiss
Hantera förslag på remiss
Bifallna förslag
Beslut under granskning
Granska beslut
Oaktiverade beslut
Aktiverade beslut
Refuserade beslut
Förkastade förslag
Acumulerat stöd
Momentant stöd
Demokratikonstant
Entity Summary
There are a number of important entities in the system:
• Members
• Functions (i.e. for party functionaries)
• Votes
• Propositions
• Owned Categories [release 5]
Members
For each user the following information should be kept:
• Id number (an integer)
• Date of registration
• Swedish ID number
• Forename
• Surname
• Pseudonym (i.e. signature)
• Pseudonym history [release 5]
• Automatic Pseudonym [release 4]
• Email
• Photo [release 3]
• Party functions [release 3]
• Login Preferences [release 4]
• Password
For each user there are in addition certain anonymity settings:
• Proposition author anonymity level (see following section) [release 3]
• Proposition executor anonymity level (see following section) [release 3]
• Member profile anonymity settings (see following section)
A member can also have one or more of the following unary roles in the system:
• Ordinary member
• Admin
• Accountant
• Membership administrator [release2] (is this the same as Admin?)
• Rule Maintainer [release 3]
In addition, a member can have binary roles in relation to a specific Proposition/Decision in
the system:
• Author of <Proposition/Decision>
• Executor of <Proposition/Decision> [release 3]
Login preferences
This is so that the user should be able to select what name to type in at the login prompt. The
options are
1. Swedish ID number (e.g. “770705-1459”)
2. Auto pseudonym (e.g. “robwe359”) [release 4]
3. Pseudonym (e.g. “Santaclause”) [release 4]
Anonymity Levels and Settings
For proposition authors there are the following anonymity levels available:
1. Swedish ID number + full name + link to user profile [release 4]
2. Swedish ID number + link to user profile [release 4]
3. Full name + link to user profile
4. Pseudonym + link to user profile [release 3]
I.e. only anonymity level 5 gives full anonymity. For proposition executors there are the
following anonymity levels available:
1. Swedish ID number + full name + link to user profile
Each member also has member profile anonymity settings. Information about a member will
show up in the Member Listing Page, and it will be possible to look at the Member Profile
Page. Through the member profile anonymity settings it is possible to hide information in
both of them. It should be possible to toggle the following options on and off:
• Show Swedish ID number
• Show Email
Votes
Each member can vote on each proposition. A vote can be one of the following:
• Yes (1, For)
• No (-1, Against)
• Blank (0)
The numbers indicate how the system thinks of the votes as integer values ranging from -1 to
1. If a person has not voted on a proposition, he or she is considered to have voted blank (0).
Thus, from the system’s point of view all persons have already voted on all questions, but
there are a lot of blank votes to begin with.
Propositions
The system needs to store the following information about a proposition:
• Id number
• Title
• Text
• Authors Id number
The system also needs information about the executor of a proposition: [release 3]
• Id number of executor [release 3]
• Fee (in some currency) for executor [release 3]
The following dates needs to be stored for each proposition:
• Creation date (when the referendum starts if there is no executor)
• Permission granted date (when the referendum starts if there is an executor) [release 3]
• Approval date
• Review date [release 3]
• Decision cancellation date [release 3]
• Decision activation date [release 3] (always = Approval date in release 1)
• Rejection date
In order to keep track on the voting, a proposition has the following properties which are all
updated daily:
• momentary-support*
• accumulated-support*
• Prediction [release 2]
• Last sign of momentary support [release 3]
The star after the support variables signify that we store an integer value to avoid
accumulation of rounding errors which could be the case if we stored momentary and
accumulated support directly. To get either of those, use the following equations:
Momentary support = momentary-support* / (population-size × democracy-constant)
Accumulated support = accumulated-support* / (population-size × democracy-constant)
The democracy constant is typically set to 1, 7, 30 or 356 for pedagogical reasons.
Finally, the system needs to keep track of the current status of a proposition. The status might
change automatically due to the results of the voting, but the change might also be caused by
the actions of some member of a certain role.
• Status, one of:
• waiting-for-executors-permission [release 3]
• in-voting
• under-review [release 3]
• rejected-by-members
• cancelled-by-reviewer [release 3]
• activated-decision
• decision-waiting-for-activation [release 4]
Daily Update
Between 00:00 and 02:00 each day the system runs an update on all propositions in the
system that have the status in-voting. This chapter describes how.
Momentary and Accumulated Support Update
When a proposition is first created its values momentary-support* and accumulatedsupport*
are both set to 0. Once each day the support values for a proposition P is updated as
follows:
1. Set momentary-support* to the sum of all votes on P (all who have not actively
voted on P are assumed to have voted blank).
2. Increase accumulated-support* with momentary-support*. (since momentarysupport*
could have a negative value, this could in practice mean a decrease)
Cut Condition Check [release 3]
If a proposition has had negative accumulated support, and once again picks up a positive
momentary support and starts to climb, it seems reasonable to reset the accumulated support
to 0, because otherwise there is a risk that someone just creates a new proposition with exactly
the same proposition text, but which starts from 0. To avoid such a possible confusion, the
accumulated support should be reset whenever the momentary support changes sign (i.e. goes
in between positive and negative).
Finish Condition Check
In addition, we have to check if the voting on a proposition is finished. To do so we need to
calculate the accumulated support (without the star). Just follow these steps:
1. Set the accumulated support to the accumulated-support* divided by the total
number of members and the democratic-constant (which is typically 7).
2. If the accumulated support is:
• < -1 mark the proposition as rejected-by-members, and set its rejection-date.
• > 1 mark the proposition as under-review, and set its acceptance-date.
• Otherwise, do nothing.
This is all it takes to perform a continuous voting. (A smart implementation of this does not
even need division, simple subtraction would be sufficient)
The democracy constant
The democracy constant determines the pace of decision making linearly. It should typically
be set to some pedagogical value so that some easy-to-remember property holds for the
system.
For example, if the democracy constant is set to 7, then it takes the whole population exactly
one week to make a decision out of a completely new proposition. That is if we assume that
the whole population (no exception) votes for the proposition from day one. This is of course
highly unlikely to happen in any larger population, but it gives some sort of idea of the speed
of decision making. In our example it would also take X amount of weeks for one person to
single-handedly make a decision out of a new proposition, where X is the size of the
population; in a population of millions, it would take millions of weeks to make a decision all
alone. That is tough, but if the number of voters is doubled, the time is cut in half etc., so it is
probably a good idea to stir up at least some public opinion.
If the democracy constant is set to 1, then you could replace all occurrences of “week” by
“day” in the example above.
Prediction [release 2]
It is necessary for the members to be able to sift out the propositions which actually have a
chance of becoming approved by the members in the near future. It is possible to see this by
looking at the accumulated support and the momentary support, but it is much more practical
for the members if this information is combined into a prediction. Since the accumulated
support grows linearly with the momentary support that is pretty simple. The different cases
should be treated as follows:
If the momentary support is zero, set the prediction to: “Nothing will happen”
If the momentary support is positive, calculate the prediction as follows: Let the approvallimit
be the total number of members times the democratic constant (typically 1 or 7). Let the
remaining-support* be the approval-limit minus the momentary-support*. Calculate the
estimated-time-until-approval as remaining-support* divided by the momentarysupport*.
If the momentary support does not change, this is the number of days until
approval. If the estimated-time-until-approval (ETA) is:
• < 3000 then the prediction is “Acceptance in <ETA> days”, high numbers could be
presented by counting years instead of days.
• > 3000 then the prediction is “Acceptance in the distant future”. This is just to
avoid silly predictions like “Acceptance in a million years”. The value 3000 could be
adjusted.
If the momentary support* is negative the prediction is calculated correspondingly, except
that we use the phrases “Rejection in <ETR> days” and “Rejection in the distant future”
instead. For clarity, here is how to calculate the ETR:
Let the rejection-limit be minus the total number of members, times the democratic constant
(typically 1 or 7). Let the remaining-negative-support be the rejection-limit minus the
momentary-support*. Calculate the estimated-time-until-rejection (ERT) as remainingnegative-
support divided by momentary-support*.
Example
The following example illustrates that the momentary support (without star) could be plotted
in a graph, and then the accumulated support is the area between the x-axis and the
momentary support curve. When the accumulated support reaches >= 1 the proposition is
approved by the members.
The red vertical lines represent occasions when the cut condition has been fulfilled, and the
accumulated support has been reset.
Categories [release 5]
To be able to quickly search among large quantities of propositions it is necessary to organize
them. The tool for doing so is the concept of categories. A category is a set of propositions,
and two categories may intersect each other (meaning that they have some propositions in
common). There are three kinds of categories in the system
1. Owned categories
2. Free categories [release 6]
3. Automatic categories [release 6]
Owned Categories
An owned category is managed by one particular member who owns the category. The name
of an owned category can therefore be of one of the following formats:
• <Swedish ID number for member>.<category name>
• <Pseudonym for member>.<category name>
For example: “770705-1459.InterestingPropositions”,
“Falcon.PropositionsAboutTheDemocracySystem” or “Alef0.PropositionsAboutPartyRules”
An owned category is managed by a Category Setup Page, which could be reached via the
User Settings Page of the owner. In the Category Setup Page is a complete list of all
Propositions, ordered by their creation date. The category owner can then checkbox all
propositions which should belong to that category.
Free Categories
A free category is essentially a category where every creator of a proposition can choose to
place the proposition. A free category is simply identified by its simple name, which is used
like keywords on the Internet, e.g. “School”, “Business”, “Democracy system” etc. Upon
creation of a proposition the author can name a number of free categories in which the
proposition is to be placed. Because of the anarchy in creating them, free categories are
expected to be less precise than owned categories.
Automatic Categories
An automatic category is a category that is based on other available information in the system.
Like for example, “all propositions created by Falcon”, “all propositions created after 2004-
03-11” or perhaps “all propositions without executor”.
Category Subscription
o subscribe for certain categories. This means that the particular
on a filter which makes it possible to only se a smaller set of
2. A switch between:
3. e filter
Op om the User Settings Page. Option 3 should be
ccessible from wherever propositions could be viewed.
the necessary pages for the site.
Each member should be able t
member should be able to turn
all selection of propositions. For each user the following personal filter information should be
stored:
1. A set of subscribed categories
• Intersection (and)
• Union (or)
An on/off switch for th
tion 1 and 2 should be accessible fr
a
Pages of the Site
This section describes all
Overview Page
Login Page
Member Settings Page
Member Profile Page
View Proposition Page
Make New Proposition Page
Propositions View Page
Propositions Vote Page
Propositions Waiting for Permission Page [release 3]
Member Listing Page
Propositions under review Page [release 3]
Pending Decisions Page [release4]
Activated Decisions Page
Cancelled Propositions Page [release 3]
Approved Propositions Page
Rejected Propositions Page
Active Propositions Page
Review Propositions Page [release 3]
Grant Permission to Proposition Page [release 3]
Admin Page
Legend:
Authority Switch:
(Navigation
alternatives are
login dependent)
<Page name> Navigation page:
Login required:
HTML t Dummy Site
To get a more concrete feeling for the design, please take a look at a dummy site which is
written in plain HTML/J t. It can be downloaded from the following address:
http://aktivdemokrati.se okrati/Teknikverkstad?action=AttachFile&do=get&target=
/JavaScrip
avaScrip
/direktdem
valsystem_html.zip
Please note that in order to ummy site as it is meant to be viewed, you need to
unpack the zip-f directory first.
The screenshots in this document are taken from that dummy site.
Login Procedures
With exception of personal set ould be possible to view the entire contents of
the democracy system without logging in.
At every page there should be a login link to the l e actions should also make
the login prom lly, among such actions are: Navigation to the
propositions vote page or navigation while not logged in. After
the login is completed the user should be transferred to the page that was previously viewed,
or the page which the user was going to ser to be logged in.
Authority Switches
Some navigation items will chang n if the user is logged in or not,
the typical case is the “Login”-link that will change to “User S en the user is
logged in. Only strator will see a link to the A next to the “User
Settings”-link.
The Propositions Waiting for Permission Page will discreetly be replaced by the Grant
Permission to Proposition Page if the user is logged in. This is not something the user
should notice unless he is set as the executor of some proposition on that page, in which case
sion. The name “Grant Permission to Proposition
ference between Propositions Vote Page and Propositions View
ns
The overview page provides three ways of navigating the system: A menu with indentations
n menus to the top, and a clickable image down to the right.
view the d
ile properly into a
tings pages, it sh
ogin Page. Som
pt appear automatica
to the new proposition page
, and which required the u
e appearance depending o
ettings” wh
dmin Page, the system admini
extra buttons appear for granting permis
Page” should never be seen by the users.
imilarly the rule maintainer will be the only one to see the Review Propositions Page which S
contains extra buttons for cancellation or activation of propositions.
here will still be a dif T
Page. The idea is that logged in members should be able to browse through the propositio
without the disturbance of voting buttons (which could perhaps be pressed by accident).
Overview Page
down to the left, dropdow
Dropdown menus should be used on all pages of the system, so that the user can quickly reach
any part of the site.
Member Listing Page
The member listing page just contains a list of all members, with some information. Some
formation will be crossed out according to the user’s member profile anonymity settings. in
For an example to see what information should be included in the list, see:
http://aktivdemokrati.se/direktdemokrati/Medlemmar
should be clickable, opening a member profile page, containing more
ing information about a specific member; this is a page that could be
viewed by other members. The page should contain the following:
• Id number
• Date of registration
• Swedish ID number (optional, see member profile anonymity settings)
• Forename
• Surname
• Pseudonym
• Email (optional, see member profile anonymity settings)
• A list of all unary roles, such as if the member is an Admin, Rule maintainer etc.
• Pseudonym history [release 5]
• Automatic Pseudonym [release 4]
• Photo [release 3]
• Party functions [release 3]
Each item in the list
detailed information about a specific member
Member Profile Page
This is a page contain
It should also be possible to view all the binary roles of a member, for example by giving a
list of all propositions which the member is author to, or all propositions which the member is
executor of [release 5].
Login Page
This is just a simple login form. By default Swedish ID number is used for login.
By using the login preferences the user should be able to use other means of login than by
using the Swedish ID number [release 4]
If the member was navigating to a page requiring the member to be logged in, the user shou
be transferred to that page after login is completed. Thus, the login page might need to store
nd submit some hidden navigation information upon login.
ld
ation:
o be unused) [release 3]
• Email [release 3]
Login Preferences [release 4]
ymity settings
• Proposition author anonymity level (see following section) [release 4]
Ad i
The ld be able to modify essentially all information about all users,
exc i
Id number
Active
Thi as the figure indicates. But it could also be a page that
onta n Propositions Waiting for Permission
Page and the Propositions View Page, just for the convenience of having it all in one view.
a
Member Settings Page
he user settings page should allow the user to modify the following inform T
• Pseudonym (The new pseudonym has t
• Photo [release 3]
• Password [release 3]
•
• Member profile anon
• Proposition executor anonymity level (see following section) [release 4]
m n Page
admin page shou
ept ons are:
••
Date of registration
Propositions Page
s is either just a navigation page
i s all information which is contained in the c
Make New Proposition Page
A member is already logged in when this page is reached, so the author information that will
be shown at the View Proposition Page is shown at the top of this page (e.g. Full name and
ber). Then there will be a form collecting the following information about a
:
• Title
• Proposition Executor’s fee [version 3]
Propositions Waiting for Permission Page [release 3]
This page just contains a list of propositions which are waiting for the proposition executor’s
permission. The columns shown for each proposition should be:
• Title
• Author (according to the author’s corresponding anonymity level)
• Executor (according to the executor’s corresponding anonymity level)
or Permission Page, except
mn in the table when logged in. The extra column occasionally
ons. A person which is the executor to a certain proposition
Alt
Ins d f all propositions waiting for permission, perhaps each
exe o of propositions waiting for permission in his Member Settings
Pag
Alt
Granting permission could perhaps also be done through the view proposition.
Pro o
It ju c sition the
following information should be available:
n the proposition became in-voting (one of the dates depending on release)
• Accumulated support
support
according to:
Swedish ID num
new proposition
• Text
• Proposition Executor [version 3]
Grant Permission to Proposition Page [release 3]
This is basically the same page as the Propositions Waiting f
that there is an additional colu
contains grant and decline butt
will have the possibility to decline or grant permission for it.
ernative design I:
tea of having buttons in the list o
cut r should get a list
e.
ernative design II:
p sitions View Page
st ontains a list of all propositions whose status is in-voting. For each propo
• Title
• Date whe
• Momentary
• Prognosis
The propositions should be sorted
• Date when the proposition became in-voting
• Prognosis [release 2] (release 2 does not have to support sorting after date also)
The user should be able to sort the propositions according to any column in the proposition
This page can only be viewed if logged in. It should contain and present information in the
sam additional columns
wit a uld be a save
button which saves the current votes,
table [release 5].
ropositions Vote Page P
e way as the Propositions View Page, except that there should be three
h r dio buttons allowing the user to vote. At the bottom of the page there sho
and navigates the user back to the Propositions View
Page.
Instead of radio buttons, a single column with dropdown menus could be used instead.
Thi
inform
section). The only exception might be the support information since that could be viewed
from h age.
just be a navigation hub. But it could
also
en n .
There should never be any need to sort the propositions according to the voting columns
[release 5].
View Proposition Page
s is just a simple page displaying all information about a particular proposition. All
proposition should be displayed (see previous ation stored in the database about the
t e propositions view p
Approved Propositions Page
Similarly to the Active Propositions Page this could
contain information from the following pages: Propositions under Review Page,
di g Decisions Page, Activated Decisions Page and Cancelled Propositions Page P
Propositions under review Page [release 3]
This page should just contain a list of propositions which are under review. This means that
they have been approved by the members, but the Rule maintainer needs to verify that they
do not conflict with the constitutional documents of the organization. For each proposition it
should present:
• Title
• Approval date
Review Propositions Page [release]
This is what the member of the role Rule maintainer sees instead of the propositions under
erification.
Pending Decisions Page [release 4]
This page should just contain a list of propositions which are pending. This means that they
have been approved by the members, verified by the Rule maintainer but there are not
sufficient funds in the organization to pay the executors fee. [Warning: This part of the design
is not completely finished] The Accountant should be able activate propositions which are in
this page.
Activated Decisions Page
This page should just contain all propositions which have been activated. For each proposition
the following information should be displayed.
• Title
• Date of activation
Propositions Page [release 3]
ich have been cancelled. For
information should be displayed.
• Title
review page. In addition to the information of that page, there should be buttons for
cancellation and v
Alternative solution I:
This could perhaps be done through the Member Settings Page instead.
Alternative solution II:
This could perhaps be done through the View Proposition Page instead.
• Date of creation
Cancelled
This page should just contain information about propositions wh
each proposition the following
• Title
• Date of creation
• Date of cancellation
Rejected Propositions Page
This page should just contain information about propositions which have been rejected. For
each proposition the following information should be displayed.
• Date of creation
• Date of rejection
Notes
This design specification is developed by “Aktiv Demokrati”, a Swedish democracy
organization. Their web page has the address: http://www.aktivdemokrati.se