ROCKVIEW UNIVERSITY SLPS — ELECTORAL COMMISSION
================================================

WHAT IS INCLUDED
- Staff/administrator Electoral Commission workspace inside SLPS.
- Election creation and management.
- Position creation.
- Candidate registration with biography, manifesto and photograph.
- Public voter registration link (no SLPS login required).
- Manual voter approval/rejection by the Electoral Commission.
- Candidate gallery link with public profile cards.
- Approved-voter sign-in and ballot submission.
- One vote per approved voter per position.
- Separate participation records and anonymous ballot records.
- Private management results and optional public results release.

INSTALLATION ORDER
1. Back up the SLPS files and database.
2. Upload/replace the updated SLPS project files while preserving your existing
   database connection settings and production uploads.
3. Open phpMyAdmin and select the existing SLPS database.
4. Import database/migrations/20261102_electoral_commission.sql.
5. Confirm the following tables exist:
   ec_elections, ec_positions, ec_candidates, ec_voters,
   ec_ballots, ec_participation.
6. Confirm the folders uploads/electoral-candidates and its .htaccess file
   are writable by PHP (normally directory permission 755).
7. Sign in as Staff or Top Management and open Electoral Commission from the
   left navigation. If it does not appear immediately, refresh the dashboard.

PUBLIC LINKS
The module creates links automatically for each election:
- Voter registration: /shared/electoral.php?e=ELECTION_KEY&view=register
- Candidate gallery: /shared/electoral.php?e=ELECTION_KEY&view=candidates

Do not manually change or share the election key. Use the Copy link controls.

ELECTION WORKFLOW
1. Create an election.
2. Add positions.
3. Add candidates to each position and upload candidate photographs.
4. Open voter registration and share the registration link.
5. Review voter registrations and approve eligible students.
6. Open voting when the candidate list and voter register are ready.
7. Students open the candidate gallery, review candidate profiles and click a
   candidate card to preselect that candidate in the voting area.
8. Students sign in using the password created during voter registration.
9. Close voting after the election.
10. Publish results when authorised.

IMPORTANT SECURITY AND GOVERNANCE NOTES
- Only staff and administrators can manage elections.
- Public registration and candidate pages do not require SLPS accounts.
- Voter registration is not automatically proof of student identity. Staff
  must verify the student number/details before approving a voter.
- A voter password is stored as a password hash, never as plain text.
- Ballot records do not contain voter IDs. A separate participation table
  prevents repeat voting per position. This is a basic ballot-separation
  design; have the university's election rules and privacy requirements
  reviewed before a live high-stakes election.
- Each student can cast one vote per position. A ballot can contain selections
  for some or all positions; missing positions can be voted later while voting
  remains open.
- The first implementation does not integrate with the SLPS student master
  register, send email/SMS OTPs, or support recount/audit exports.
- Results are hidden from the public until the results control is published.
- Candidate images accept JPG, PNG or WebP up to 5 MB.

FILES ADDED
shared/views/modules/electoral-commission.php
shared/views/electoral_commission_workspace.php
shared/api/electoral_commission.php
shared/lib/electoral_commission.php
shared/electoral.php
shared/js/electoral-commission.js
shared/js/electoral-public.js
shared/css/electoral-commission.css
database/migrations/20261102_electoral_commission.sql
uploads/electoral-candidates/.htaccess

FILES MODIFIED
shared/views/module_shell.php
shared/lib/panel_permissions.php
shared/js/panel-navigation-policy.js
shared/js/portal.js

TESTING
Run PHP syntax checks on the added PHP files and JavaScript syntax checks on
the added JS files before deployment. Test in staging first:
- create election and positions;
- register a candidate and upload a photo;
- register a voter from a private/incognito browser;
- approve the voter in the staff workspace;
- sign in as that voter and cast one vote per position;
- attempt a duplicate vote;
- close voting and publish results.

This package contains the source changes and SQL migration. The migration must
be imported into the live database before the module can be used.
