CivitasVote Administrator Guide

1. Audience and responsibility

This guide is for technical superusers, Platform Administrators, association Owners/Administrators and senior election officers. It describes the administrative sequence and the boundaries between platform, association and election authority. Use ROLE_AND_PERMISSION_MATRIX.md for the detailed permission model and COMPLETE_SYSTEM_MANUAL.md for the full system reference.

2. Never solve access problems by granting superuser

An ordinary authorised user must receive the correct appointment or membership. Django is_staff and is_superuser are reserved for technical administration. Platform and election interfaces intentionally work without Django Admin.

3. Platform preparation

3.1 Technical superuser

Create one named technical superuser for installation and recovery. Protect it with a unique password, limited access and documented custody.

3.2 Ordinary users

Create users manually or through the controlled import. Supply the official email, full name, temporary password, active state and forced-password-change setting. Deactivate accounts rather than deleting historical users referenced by appointments, approvals or audit records.

3.3 Platform Administrators

Appoint active ordinary users through the Platform Administrator assignment workflow. Record appointment reference and dates. Revoke with a reason when authority ends.

4. Association setup

1. Create the association.
2. Enter the official name and abbreviation;
3. set branding colours;
4. identify the data controller and data-protection email;
5. set the approved retention period;
6. keep the association active only while it is authorised to operate;
7. assign an Owner and/or Administrator.

The normal association form supports an optional logo and approved institutional-email domains. Enter domains without @ and verify them before relying on institutional-email access.

5. Election-cycle creation

Association governance creates the cycle and enters:

• title and description;
• unique election reference;
• election type;
• nomination mode;
• nomination window where required;
• voting period;
• minimum independent result approvals;
• verification methods.

Voting may not remain continuously open for more than 48 hours. Nominations must close before voting opens. The ordinary annual election types are subject to harmonised scheduling validation.

6. Committee appointments

The software minimum is three distinct current people:

• Commissioner/Chairperson;
• Secretary;
• ICT and Data Protection Commissioner.

All other roles are optional. Each appointment must have a protected PDF letter, reference, validity period and active user. Appointment and voter eligibility are independent. Do not add a person to the voter register merely to make an appointment possible.

Governance should still appoint additional officers or an independent Appeals Panel where the constitution, election scale or risk requires them.

7. Voter directory and election register

The association directory is reusable; the election register is cycle-specific. Select a register source, review each status and certify the final register. Certification records a digest. Any later voter or eligibility change causes the digest to differ and requires recertification.

Do not place ballot choices, PINs or one-time codes in voter notes. The register records whether a voter participated, not how they voted.

8. Ballot and nomination administration

Create positions before candidates. Configure kind, seats, maximum selections, order, required status and abstention. Select the nomination workflow deliberately:

• Upload: Commission candidates only;
• Self: approved public self-nominations only;
• Mixed: both sources;
• None: no formal nomination workflow.

All approved candidates require valid photographs. Rejected and withdrawn nominations are complete decisions and remain audit records, but are excluded from the final list. In Self mode, unlinked direct candidates must be deleted before publication.

9. Objections and officer complaints

Election objections and officer complaints are separate queues. Election objections are reviewed by authorised Commission/registration roles. Officer complaints are reviewed by the competent appointing authority or Appeals reviewer, and the accused officer is excluded. Where no current Appeals reviewer exists, the project can route to the appointing authority.

Document decisions, evidence, reasons and operational consequences. Do not delete a complaint merely because it is inconvenient.

10. Readiness and mock election

Before opening, the system checks appointments, letters, certified register, eligible voters, ballot configuration, candidates, photographs, final-list publication and fingerprints. Resolve messages rather than bypassing service checks.

Conduct a witnessed mock election using non-production voters. Test verification, ballots, receipts, opening/closing, tally, approvals, exports and recovery. Destroy or clearly segregate mock data before a binding poll.

11. Voting operations

Only the Commissioner controls opening, closing, tally, recount and runoff through the election-control actions. Support officers may assist with verification without observing selections. Destructive actions require POST and CSRF protection.

Do not deploy code, alter schema, edit the database manually or rotate keys while voting is open.

12. Results

After closing:

1. generate a tally snapshot;
2. reconcile ballot count and participation count;
3. investigate incidents or rejected ballots;
4. create a reasoned recount only where authorised;
5. obtain at least the configured number of independent approvals;
6. publish results;
7. verify public results and archive links;
8. generate the system declaration;
9. attach a protected signed declaration where required.

The generated declaration includes approval records, incident/recount text, official signature blocks and two candidate-agent acknowledgement rows for each approved candidate.

13. Cancellation and invalidation

Only the currently appointed Electoral Commissioner may use the exceptional-action controls. Open the election dashboard, go to Commissioner controls, and select Cancel election or Invalidate election where the current status permits the action. The confirmation page requires a formal reason of at least 20 characters.

Cancellation is available while the election is Draft, Nominations open, Ready to open or Voting open. Invalidation is available while voting is Open or after the election has reached Voting closed, Tallying, Awaiting result approval or Results published. Once an election is Cancelled or Invalidated, the system does not permit a second exceptional status.

The action changes the election to a terminal status, stores the formal reason, clears any publication timestamp, creates a resolved critical incident and writes a hash-chained audit event containing the previous and new statuses. It does not delete appointments, registers, ballots, tallies, disputes or other evidence. Use the control only under documented authority and record any required public communication outside the system where the governing rules require it.

14. Retention and deletion

Election-cycle deletion is not the same as operational retention purge. A cycle should be permanently deleted only when it is a verified unused Draft and the supported action confirms that no appointment, nomination, register use, credential, ballot, tally, approval, declaration, dispute, incident or audit-dependent record exists. Established cycles must be cancelled, invalidated, retained historically or documented as replaced. Never use direct database deletion to bypass the control.

The retention-days field is a policy value, not a licence for immediate deletion. Before retention purge:

• complete petitions and audits;
• confirm no legal hold;
• make and test a backup;
• identify records protected by governance or law;
• obtain written authority;
• run only the supported command;
• verify and document the result.

Live media/ and protected_media/ are data, not disposable build artefacts. See PROJECT_FILE_CLEANUP.md.

15. Release administration

For each release:

1. use a clean Git working tree;
2. review migrations;
3. run checks and all tests;
4. verify audit ledger;
5. back up database and files;
6. deploy a tagged commit;
7. migrate and collect static files;
8. restart and smoke-test;
9. record checksum and rollback point.

16. Common administrative mistakes

• treating a user account as an appointment;
• appointing the same person to multiple core roles;
• assuming officers must be voters;
• failing to recertify a changed register;
• using Self mode and adding candidates directly;
• leaving approved candidates without photographs;
• describing a stored feature flag as fully enforced without testing it;
• committing .env, databases or media;
• deleting migrations or audit evidence;
• using the technical superuser for routine operations.