From initial setup
to an accountable review.

1. Connect your organization

1. A system administrator creates a PostgreSQL database, applies the versioned migration, and gives the application the limited truevote_app database role. Keep migration credentials out of the running web service.
2. Configure a confidential OpenID Connect application with the exact callback https://YOUR-HOST/api/staff/callback. Version 1 uses authorization code, PKCE S256, RS256 signed ID tokens, and client secret post authentication.
3. Set the trusted issuer, client ID, client secret, and required signed AMR and/or ACR claims. Configure the provider to require MFA. Test the actual claims with the provider before admitting staff.
4. Obtain the first administrator’s exact issuer and subject from the identity team. A database operator runs the one-time bootstrap command described in the repository’s administration manual. Email addresses do not create accounts.
5. Open Staff access and continue through your organization’s sign-in. Unprovisioned identities and missing MFA claims are rejected.

Sessions end after 15 minutes of inactivity or 8 hours in total. Approving configuration, changing assignments, provisioning or disabling staff, and archiving require a sign-in from the last 15 minutes. Sign out and sign in again when prompted.

2. Give each officer appropriate access

From Elections, an administrator selects Add staff, enters the exact provider subject, chooses a role, and selects assignments. Use Assignments to grant or remove election access later.

• Administrator: manages staff, accesses all elections, creates configuration, and archives it.
• Election manager: creates elections and manages assigned configurations. Newly created elections are assigned to their creator.
• Registration officer: currently reads assigned configurations. Citizen registration is not implemented in this service.
• Auditor: reads assigned configuration and its latest activity, and downloads the configuration manifest.

Disable a departing officer to revoke all their sessions immediately. The interface has no reactivation or role-change operation; follow a reviewed database maintenance procedure for corrections. A staff identity may not disable itself.

3. Create an election configuration

1. Select Create election. Enter a unique code, descriptive name, jurisdiction, and planned date. Do not use a test configuration for a real election.
2. Open the new election. It starts in draft and has its own revision number.
3. Add stations and contests. Each accepted change increments the revision. If another officer has changed it, refresh and review their changes before saving again.

The date is configuration information; it does not schedule polls. Creating an election does not import voters, open voting, or establish EC authorization. The current workspace lists up to 200 accessible configurations and 200 staff accounts.

4. Add or upload polling stations

One station

Open the election’s Polling stations tab and choose Add station. Enter its approved code, name, constituency, region, planning total, and team label. Codes use 3–20 letters, digits, or hyphens and are normalized to uppercase. The same code cannot appear twice within an election.

A CSV batch

1. Choose Upload CSV and download the template. Replace the example row with approved station information.
2. Keep these exact columns in order: id,name,constituency,region,registered,officer. The legacy column id means station code; officer means a team label, not a staff assignment.
3. Use UTF-8 CSV. Quote names containing commas. Upload 1–100 rows per batch, no larger than 256 KB. Planning totals must be integers from 0 to 100,000.
4. Review the validation result and preview. Correct every reported error before selecting Save. Duplicate codes or a failing row cause the entire database batch to roll back.

Station totals are planning figures. They neither register people nor establish an authoritative voter roll. Do not include Ghana Card numbers, personal phone numbers, photos, or biometric data.

Version 1 adds configuration records but does not offer station/contest editing or deletion. Correct a mistaken draft by archiving it and creating a replacement edition; arrange a reviewed migration for large corrections.

5. Configure contests

Open Contests, select Add contest, and enter the title and ballot style identifier. Add 2–30 options, one per line, using ID | Name | Affiliation. Option IDs must be unique within the contest and use uppercase letters, digits, or hyphens. The line order is preserved in the configuration export.

Ballot styles are labels in this administration version. There is no constituency-to-voter eligibility engine, ballot allocation, candidate nomination approval, ballot printing, or live tally.

6. Record evidence and request review

1. In Readiness, record the reference to each institutional or operational document in your controlled document system. The application stores references, not files or approvals.
2. When at least one station and contest are present, select Request review. Editing stops while the configuration is under review.
3. A different assigned election manager or administrator examines the stations, contests, evidence references, and downloaded manifest. Anyone who authored a configuration change in this election is prevented from approving it.
4. The reviewer chooses Approve & freeze or returns it to draft. A frozen manifest contains a SHA-256 digest and cannot be edited through the application.

Freezing confirms a version of administrative configuration. It does not verify documentary evidence, authorize a governmental election, open polls, or create a cryptographic proof of votes.

7. Inspect activity and export records

The Activity tab shows the latest 100 election events with UTC timestamps, actor references, and database sequence numbers. Download the configuration JSON before and after approval. A frozen export includes its stored digest; a draft export has no approved digest.

The runtime database role cannot update or delete audit rows. Database owners still can, so this is not an immutable ledger. Production requires independent log retention, monitoring, and reviewed audit export procedures. A consistent complete archive, backup restoration, and retention policy remain deployment responsibilities.

8. What remains before public elections

• EC sponsorship, applicable legal authority, agreed electoral procedures, and formally accepted requirements.
• An authorized voter register with constituency and station eligibility, duplicate-use controls, and an adjudication process.
• An approved NIA/TrueID contract, production credentials, mandatory server-side liveness policy, biometric privacy controls, and an accessible assisted-verification process.
• Independently designed and reviewed ballot secrecy, eligibility credential issuance, coercion resistance, paper evidence, counting, audits, and disputes.
• Independent security, cryptographic, accessibility, usability, and operational reviews followed by supervised pilots.
• Hardened hosting, device management, key custody, tested recovery, failover, load tests, monitoring, incident response, and election-day staffing.

None of these is satisfied by filling in a reference field. Public ballot endpoints remain unavailable. The implementation and staged acceptance plan are documented in docs/PRODUCTION-READINESS.md.

9. Citizen use and assistance

Citizens cannot register or cast an official vote in this deployment. The citizen page explains that voting is unavailable and directs people to the Electoral Commission’s voting information. Do not ask citizens to submit identity documents or selfies here.

The separately launched rehearsal includes synthetic citizen flows and its own user guide. Its credentials, receipts and counts are not accepted by this administration service.

10. If something goes wrong

• Sign-in unavailable: check database reachability, issuer discovery, callback URL, provisioned subject, signed MFA claims, and synchronized clocks. Do not remove MFA to make sign-in work.
• Session ended: sign in again. Unsaved form entries are not persisted; preserve non-sensitive configuration notes before leaving the page.
• Revision conflict: refresh, inspect the latest records, and retry after review.
• Duplicate station: correct the input; existing records are not overwritten.
• Independent review required: assign an officer who has not authored any configuration changes in this election.
• Uncertain network result: retry the unchanged form in the same page. The client preserves its request reference, so a successful earlier save is not repeated.