🗳️Election OS
Election OS · User manual

Run an election, end to end

The campaign & organising layer for panels, societies, unions and cooperatives — from voter roll to election-day turnout.

Build 3ddea46 · 2026-10-02

Written so a first-time campaign manager can run a whole election end-to-end, and a pro can find any lever fast. Every step is shown worked through the B-17 MPCHS 2026 demo election that ships with the app, so you always see what a completed step looks like.

Overview

Election OS takes a campaign from an empty page to election-day turnout. Work is organised as 18 steps in 6 phases — but it is not a rigid line: each step only waits on what it genuinely needs, and many run in parallel or continuously. The guided setup shows you, live, what to do next and what you can do right now.

  • Foundations are sequential: rules → areas → roll.
  • Candidates & content, strategy and team can progress together.
  • Reaching voters has one hard legal gate — opt-in then consent — after which messaging, canvassing and phone/text run in parallel.
  • Election day is the finish line: carpool + live turnout (GOTV).

Throughout, examples come from the B-17 MPCHS 2026 demo election that ships seeded with the app — a complete, 18/18 worked campaign you can open live to see what each finished step looks like. Open the B-17 example →

Quick start (the 10-minute path)

  1. 1Create your election. From the admin console, create a new election (name, region label, currency). A private admin space and a public page are created for you.
  2. 2Set the rules. Open Strategy Studio and choose the electoral system — this drives everything downstream.
  3. 3Add areas, then import the roll. Add your blocks/wards, then import the voter file (vendor export or paste).
  4. 4Add candidates & the manifesto, publish. Name the field, upload the manifesto, publish — the public page and pledge form go live.
  5. 5Set opt-in, collect consent, send. Set a keyword, gather consent, then send your first fact-checked message.
  6. 6War-game, canvass, and run turnout. Rehearse the outcome, work the doors and phones, then chase your pledges on election day.

Every one of these expands into a full step below, with sub-steps, a worked B-17 example, and a link to the exact page.

Foundations

How the election works and who's voting. Strictly sequential.

1

Set the electoral system

Do once

Everything downstream — the war-game, the seat maths, the ballot — depends on how this election is decided.

How: Choose the electoral system and turnout/threshold rules in Strategy Studio, then save.

Sub-steps
  1. 1Pick the electoral system (FPTP, popular vote, proportional, or threshold/referendum).
  2. 2Set the number of seats (proportional only).
  3. 3Set the base turnout and any threshold/quorum rules.
Worked example · B-17 · Popular vote

B-17 is a single society-wide, in-person vote, so the system is set to Popular vote with a 50% majority bar. This one choice drives the war-game maths and the ballot.

Open this step (B-17) →/admin/<your-election>/strategy#rules
2

Define constituencies / blocks

Do once
Needs first: Set the electoral system

Voters, canvass turf, the carpool map and the influence graph are all organised by area, so these come first.

How: Add each block / ward / constituency, with its electorate size and (optionally) map coordinates.

Sub-steps
  1. 1Add every voting area (ward / block / constituency / chapter).
  2. 2Set each area's electorate size.
  3. 3Add map coordinates so the carpool map can place them (optional).
Worked example · B-17 · 12 areas

The 12 residential blocks (A–G plus R/M/T/Mixed) are added with each block's electorate, so voters, turf and the carpool map all organise by block.

Open this step (B-17) →/admin/<your-election>?step=areas#roll
3

Import the voter roll

Do once
Needs first: Define constituencies / blocks

The roll is the campaign's foundation — every contact, pledge and projection runs off it.

How: Import a voter-file export (L2 / TargetSmart / PDI / NationBuilder) or paste the roll; voters attach to the areas you defined.

Sub-steps
  1. 1Import a vendor voter-file export, or paste/add voters.
  2. 2Confirm voters map to the correct areas.
  3. 3Mark locality (local vs out-of-city) for election-day transport.
Worked example · B-17 · 540 members (demo sample)

A representative sample of the 28,186-member roll is imported over the real block/locality split — every contact, pledge and projection runs off it. (Your live election imports the full file.)

Open this step (B-17) →/admin/<your-election>?step=roll#roll
Related: CRM connectors (VAN / Mailchimp / ActBlue)

Candidates & content

Name the field and prepare what voters read. Ratings, manifesto and the facts sheet run in parallel; publish the public page as soon as candidates and manifesto exist.

4

Add candidates & slates

Do once

Name the field — your slate and the opponents — so the ballot, public page and analysis have candidates to work with.

How: Create your slates/panels, add each candidate, and assign them.

Sub-steps
  1. 1Create the slates / panels (yours and the opponents').
  2. 2Add each candidate with their headline.
  3. 3Assign each candidate to a slate.
Worked example · B-17 · 37 candidates

The full official qualified field across all six posts is entered — the Multi Founder Group slate plus every opponent — so the ballot and analysis have a real contest.

Open this step (B-17) →/admin/<your-election>?step=candidates#candidates
5

Upload manifesto & documents

Do once
Needs first: Add candidates & slates

Your manifesto and notices are what voters actually read; they anchor the public page and outreach. Independent of ratings — do them in parallel.

How: Upload the manifesto and any polling notices.

Sub-steps
  1. 1Upload the manifesto.
  2. 2Add any polling notices or leaflets.
  3. 3Mark which documents are public.
Worked example · B-17 · 2 documents

The manifesto and a polling notice are uploaded and marked public, so they anchor the public page and outreach.

Open this step (B-17) →/admin/<your-election>?step=documents#documents
6

Rate your panel & opponents

Do once
Needs first: Add candidates & slates

Score your panel AND the opponents on stature, standing, organisation and effort — plus SWOT. This is what makes the simulator decide races on judgement, not a guess. Runs in parallel with the manifesto.

How: Open each candidate and enter the panel's 0–10 ratings and SWOT.

Sub-steps
  1. 1Score each candidate 0–10 on the rating attributes.
  2. 2Fill in the SWOT for your candidate and the key opponents.
  3. 3Repeat for opponents so the projection is a real contest.
Worked example · B-17 · 30 ratings

Panel and key opponents are scored 0–10 on stature, standing, organisation and effort, with SWOT — this is what makes the simulator decide races on judgement, not a guess.

Open this step (B-17) →/admin/<your-election>?step=ratings#candidates
Related: Strategy convergence (uses these ratings)
7

Build the facts sheet

Ongoing

Every number in a campaign message is checked against this sheet before it can be approved — so a send is BLOCKED until the claims it makes are sourced here. Build it before you draft, and add to it as new claims come up.

How: Add each factual claim with its source. The message guard reads directly from this list.

Sub-steps
  1. 1Add each claim you'll make (turnout figures, records, comparisons) with a citation.
  2. 2Keep it current — add a source whenever a message needs a new number.
  3. 3A message with an unsupported number can't be approved until its source is here.
Worked example · B-17 · 5 sourced claims

Five factual claims (turnout figures, roll counts) are entered with citations. Any campaign message that uses a number not on this sheet is BLOCKED from approval until its source is added.

Open this step (B-17) →/admin/<your-election>?step=facts#campaign
8

Publish the public page

Do once
Needs first: Add candidates & slates, Upload manifesto & documents

The public page hosts the manifesto and the pledge form that opt-in, consent and messaging all point supporters to — so publish it as soon as candidates and the manifesto exist, NOT at the very end.

How: Publish candidates so the public election page goes live.

Sub-steps
  1. 1Publish your candidates.
  2. 2Check the public election page and the pledge form.
  3. 3Share the public link — outreach and opt-in point here.
Worked example · B-17 · 9 published

The slate is published, so the public election page and its pledge form go live at /elections/mpchs-b-17-2026-multi-founder-group — the link every outreach message points supporters to.

Open this step (B-17) →/elections/<your-election>

Strategy

War-game BEFORE you spend on the ground, then re-run it as ratings and field data come in.

9

Run the war-game

Revisit
Needs first: Set the electoral system, Import the voter roll, Rate your panel & opponents

Rehearse the outcome BEFORE spending on the ground — it's a targeting tool, so it belongs before canvassing/outreach, not after. Re-run it as ratings and field data come in.

How: Run scenarios in Strategy Studio and bank the ones worth comparing; revisit as data lands.

Sub-steps
  1. 1Add past results to calibrate the projection (recommended).
  2. 2Run Monte-Carlo scenarios under different strategy levers.
  3. 3Save & compare scenarios; use the budget → seats optimiser to target the field program.
Worked example · B-17 · 4 scenarios saved

Four Monte-Carlo scenarios (do-nothing, GOTV, absentee mobilisation, full-throttle) are banked and compared, and the budget→seats optimiser targets the field program before a rupee is spent on the ground.

Open this step (B-17) →/admin/<your-election>/strategy
Related: Decision studio (AHP) · Strategy convergence

Team & presence

Recruit the people who do the work and start posting — both begin early and run continuously.

10

Recruit volunteers & shifts

Ongoing

Canvassing, phone banks and election-day driving all need real people — and 'assign canvassers to turfs' has no one to assign until you've built the roster. Recruit early.

How: Add your field team with contact details and roles, and schedule shifts.

Sub-steps
  1. 1Add volunteers with their role (canvasser / caller / driver …).
  2. 2Schedule shifts for canvassing, phones and election day.
  3. 3Keep the roster current as people join.
Worked example · B-17 · 5 volunteers

Five field-team members are added with roles (canvasser / caller / driver) and shifts — the roster canvassing, phones and election-day driving all draw from.

Open this step (B-17) →/admin/<your-election>/volunteers
11

Plan the social calendar

Ongoing

A planned calendar keeps the message consistent across platforms — it runs continuously from early on, not squeezed in behind the field program.

How: Schedule posts across your channels and keep them flowing.

Sub-steps
  1. 1Draft posts per channel.
  2. 2Schedule them across the whole campaign, starting now.
  3. 3Track status (draft → scheduled → posted).
Worked example · B-17 · 4 posts

Four posts are scheduled across channels (draft → scheduled → posted) to keep the message consistent from early on.

Open this step (B-17) →/admin/<your-election>?step=social#social

Reach voters

Opt-in then consent are hard legal gates. After consent, messaging, canvassing and phone/text run in parallel.

12

Set an opt-in keyword

Do once

A distinctive keyword (e.g. “VOTE2026”) builds a consented, legal contact list from your ads and posters.

How: Set the opt-in keyword and welcome message. Pick a keyword unique to your campaign — generic join words (JOIN, START, SUBSCRIBE…) are reserved and won't be accepted.

Sub-steps
  1. 1Choose a distinctive opt-in keyword (e.g. VOTE2026 or your campaign's short name — not a generic word like JOIN).
  2. 2Write the welcome/confirmation message.
  3. 3Print the keyword on posters and ads.
Worked example · B-17 · keyword “MFG”

The distinctive opt-in keyword MFG is set with a welcome message, so posters and ads build a consented, legal contact list. Generic words (JOIN, START…) are reserved and rejected.

Open this step (B-17) →/admin/<your-election>?step=optin#optin
13

Collect contact consent

Do once
Needs first: Set an opt-in keyword

You can only text or call voters who have consented — this is the hard legal gate for every send, call and text below.

How: Collect reminder/comms consent via pledges, opt-in, or import.

Sub-steps
  1. 1Gather consent via pledges, the opt-in keyword, or import.
  2. 2Confirm the consented audience size on the dashboard.
Worked example · B-17 · 870 consents

870 members have granted reminder/comms consent (via pledges, the opt-in keyword and import) — the hard legal gate every send, call and text respects.

Open this step (B-17) →/admin/<your-election>?step=consent#reach
14

Send a campaign message

Revisit
Needs first: Collect contact consent, Build the facts sheet

Turns the consented list into turnout. Every number is checked against the facts sheet, so that must exist first. Runs in parallel with the door and phone programs.

How: Draft and send a campaign message to your consented audience.

Sub-steps
  1. 1Create a campaign.
  2. 2Draft a message — numbers are checked against the facts sheet before approval.
  3. 3Approve it, then send to the consented audience.
Worked example · B-17 · 1 campaign message

A GOTV message is drafted with merge fields ({name}), fact-checked against the facts sheet, previewed for a sample voter, approved, then sent to the consented audience only.

Open this step (B-17) →/admin/<your-election>?step=campaign#campaign
Related: A/B test & schedule (in the campaign)
15

Canvass the doors

Ongoing
Needs first: Collect contact consent, Import the voter roll, Recruit volunteers & shifts

Doors are the highest-value contact — and where your survey learns what voters care about. Depends only on consent, the roll and a volunteer roster; it runs in parallel with phone/text, not before it.

How: Cut turf, assign your canvassers, build the doorstep survey, and record contacts.

Sub-steps
  1. 1Cut turf per area.
  2. 2Assign canvassers (from Volunteers) to turfs.
  3. 3Build the doorstep survey.
  4. 4Record contacts (works offline).
Worked example · B-17 · 182 door contacts

Turf is cut per block, canvassers are assigned, a doorstep survey is built, and 182 door contacts are recorded — offline-capable, syncing when back online.

Open this step (B-17) →/admin/<your-election>/canvass
Related: Volunteers & shifts (staff the doors)
16

Run phone / text outreach

Ongoing
Needs first: Collect contact consent, Import the voter roll

Phone and text reach the voters you can't knock — within legal contact hours. A parallel field channel to canvassing, gated only by consent and the roll.

How: Create a phone/text session and work the list.

Sub-steps
  1. 1Create a phone or text session with a script.
  2. 2Load the call/text list.
  3. 3Work dispositions and inbound replies.
Worked example · B-17 · 2 sessions

Two phone/text sessions with scripts work the voters you can't knock, within legal contact hours, tracking dispositions and inbound replies.

Open this step (B-17) →/admin/<your-election>/outreach

Election day

Get your supporters to the poll — the day it's all been building toward.

17

Set up election-day carpool

Do once
Needs first: Define constituencies / blocks, Import the voter roll

Getting your out-of-city and elderly voters to the poll is the whole game. Set drivers up early; activate the live map on the day.

How: Add drivers and share their live links; watch the coordinator map on the day.

Sub-steps
  1. 1Add drivers with capacity and area.
  2. 2Share each driver's live-location link.
  3. 3Watch the coordinator map on election day.
Worked example · B-17 · 4 drivers

Four drivers are added with capacity and area and share live-location links; the coordinator map runs on election day to get out-of-city and elderly members to the poll.

Open this step (B-17) →/admin/<your-election>/carpool
18

Run election-day turnout (GOTV)

Do once
Needs first: Collect contact consent, Import the voter roll

The finish line the whole campaign builds toward — chase your pledged supporters who haven't voted yet and mark them off as they turn out.

How: Work the live turnout board: the GOTV chase list of pledged supporters not yet voted, one-tap mark-voted, and a shareable poll-watcher link.

Sub-steps
  1. 1Open the live turnout board.
  2. 2Work the chase list of pledged supporters who haven't voted.
  3. 3Share the poll-watcher link so volunteers can mark voters off from their phones.
Worked example · B-17 · 266 marked voted

The live turnout board works the chase list of pledged supporters who haven't voted; 266 are marked voted, with a shareable poll-watcher link for volunteers.

Open this step (B-17) →/admin/<your-election>/turnout

Feature catalog

Everything beyond the linear 18 steps — the strategy, presence, governance and learning tools.

Strategy & analysis

Strategy Studio

Open →

The war-game engine: a seeded Monte-Carlo projection with a win probability and uncertainty band, plus the budget→seats optimiser and historical calibration.

Use it to: Set your electoral rules and levers (GOTV, persuasion, base support), run scenarios, then feed a budget and cost-per-contact to get the best-ROI target areas.

/admin/<election>/strategy

Decision studio (AHP)

Open →

Analytic Hierarchy Process — turn the team's subjective judgements into a defensible, weighted ranking with a consistency check and a fragility (sensitivity) read.

Use it to: Pairwise-compare your criteria, score the options, and read the ranking — the consistency ratio catches contradictory judgements before you act on them.

/admin/<election>/decisions

Strategy convergence

Open →

A strategy board that reconciles the war-game, the AHP decision and candidate ratings into an agreed set of moves.

Use it to: Adopt or archive candidate strategies and track where the analyses agree.

/admin/<election>/convergence

Influence graph

Open →

The mobilisation graph — who influences whom across the roll — used to seed outreach where it spreads furthest.

Use it to: Explore clusters and seed nodes. (Needs the Apache AGE graph extension on your database; it degrades to empty without it.)

/admin/<election>/graph

Reports & API keys

Open →

A cross-module report of the whole campaign, plus API keys for the public /api/v1 surface and CSV exports.

Use it to: Read the campaign snapshot, export data, or mint an API key for an integration.

/admin/<election>/reports
Presence & data

Brand studio

Open →

White-label the whole platform: logo, favicon, brand colours, hero and footer — plug-and-play so a client's election looks like their own product.

Use it to: Upload your logo and set brand colours; the public pages and admin adopt them instantly.

/admin/brand

CRM connectors

Open →

Import/sync bridges to VAN, Mailchimp, ActBlue and commercial voter files (L2 / TargetSmart / PDI / NationBuilder).

Use it to: Connect a source and map its columns; a district is created per precinct and duplicates are detected on import.

/admin/<election>/crm
Reach voters

Quick polls

Open →

Lightweight polls/surveys with shareable links, separate from the doorstep canvass survey.

Use it to: Create a poll, share the link, and read responses live.

/admin/<election>/polls
Governance

US compliance & readiness

Open →

A US campaign-finance readiness checklist and contribution controls (per-donor limits, itemization thresholds) for selling into US races.

Use it to: Work the readiness checklist and set the contribution limit and itemization threshold for your race.

/admin/<election>/compliance/us

Fundraising & donations

Open →

A public donate page with a payments processor, plus audit-ready records with limit and itemization checks.

Use it to: Connect a processor, share the public donate page, and reconcile contributions with the compliance panel.

/elections/<election>/donate

Governance & approvals

Open →

The human/AI governance checkpoint: an approvals queue and an immutable audit log of every sensitive action.

Use it to: Route messages and actions through approvals; review the audit log for a complete, tamper-evident history.

/admin/<election>/governance

Audit log

Open →

An append-only record of who did what and when across the election.

Use it to: Filter by actor or action to trace any change — the compliance backstop.

/admin/<election>/audit
Learn

Guided tutorials

Open →

Short, task-focused walkthroughs of the core flows (import the roll, first message, canvass survey, war-game, fundraising).

Use it to: Learn by doing — each tutorial deep-links into the page where you do it.

/admin/<election>/tutorials

Troubleshooting & FAQ

A solution for each issue operators actually hit. Most “problems” are a safety gate doing its job — the fix says which.

? I redeployed but the site looks unchanged

What you see: New features or copy don't appear after a deploy.

Why: A CDN/proxy in front of the app is serving cached HTML, or the container didn't restart with the new image.

Fix: Open /api/health (or read the build chip in the admin console header) and check the commit. If it shows the NEW commit but the page still looks old, purge your CDN cache (e.g. Cloudflare → Purge Everything) and hard-refresh. If it shows an OLD commit, your build isn't pulling latest — rebuild without cache. Election OS now serves HTML with no-store, so this stops recurring.

Health & build stamp →
? A setup step won't turn green

What you see: You did the work but the step still shows “to do”.

Why: Either a prerequisite step isn't done (the step is locked), or the done-detector counts a specific record that isn't there yet. Steps go green automatically from live data.

Fix: Open the step's guided page — it lists exactly what it “needs first”. Complete those, then add at least one real record (e.g. one candidate, one area, one consent). The tick updates on your next visit; no manual marking.

Guided setup →
? My campaign message won't approve

What you see: Approval is blocked with a note about an unsupported claim.

Why: The facts-sheet guard: every number in a message is checked against your facts sheet, and a send is blocked until each claim is sourced.

Fix: Open the facts sheet (setup step “Build the facts sheet”) and add the number with a citation, then re-approve. This is a feature — it keeps the campaign honest and audit-ready.

Build the facts sheet →
? My opt-in keyword is rejected

What you see: Saving the opt-in keyword fails or is refused.

Why: Generic join words (JOIN, START, STOP, SUBSCRIBE, YES…) are reserved so they can't collide across campaigns.

Fix: Pick a keyword distinctive to your campaign — your short name or a slogan like VOTE2026 or MFG.

Configure opt-in →
? I can't text or call some voters

What you see: Voters are missing from a send, call or text list.

Why: The consent gate: you can only contact voters who have granted reminder/comms consent, and unsubscribes are always honoured.

Fix: Grow the consented audience via pledges, the opt-in keyword, or an import that carries consent. The dashboard shows the consented count.

Review consented audience →
? How do I pause, edit, archive or delete a campaign / election?

What you see: You want to resume, rename or remove something.

Why: Lifecycle controls live on the item itself, not a separate menu.

Fix: Campaigns: open the campaign — Pause/Resume, Edit and Archive are on its page. Elections: the admin console (/admin) shows Edit, Archive/Restore and Delete on every election card (delete is owner/super-admin only and asks you to type DELETE).

Admin console →
? I don't see the left side panel

What you see: The persistent navigation panel is missing.

Why: The left sidebar shows on wide (desktop) screens; on phones/tablets it collapses into the top navigation to save space.

Fix: Widen the window or use a desktop. On mobile, use the grouped menus in the top bar — same destinations. “All pages” lists every feature.

All pages →
? The influence graph is empty

What you see: The graph page shows nothing.

Why: The graph needs the Apache AGE extension on Postgres; without it the app degrades gracefully to an empty graph rather than erroring.

Fix: Install/enable Apache AGE on your database (the production image includes it). Everything else works without it.

Influence graph →
? Importing the roll created duplicates or failed

What you see: A large paste/import errored or double-counted voters.

Why: Repeated external references in a big file used to break the batch upsert.

Fix: Election OS now de-duplicates by external reference on import (last-wins) and maps vendor columns automatically. Re-run the import; the Data completeness card flags any remaining likely duplicates.

Import the roll →
? There's a “confirm your email” banner

What you see: A gentle amber banner asks you to verify your email.

Why: Email verification is optional and only shown when email delivery is configured and your address isn't confirmed.

Fix: Click Resend link and confirm — it unlocks email features. Your account works either way; you're never blocked.

Admin console →
? Projected candidate marks all look identical

What you see: At-large candidates show the same number.

Why: Older builds allocated marks deterministically, so equally-rated candidates tied exactly.

Fix: The projection is now a seeded Monte-Carlo: each candidate shows expected marks, an 80% range and a seat probability. Add panel ratings (AHP/SWOT) to resolve genuinely contested seats.

See it in the case study →
? I can't read the sensitivity grid

What you see: The win-probability heatmap is unclear.

Why: It varies two assumptions at once — your support (rows) and how united the opposition is (columns).

Fix: Read the plain-English “bottom line” above the grid, find your planned-support row, and scan across: it turns green as the opposition splits. More rival blocs is better for you.

Sensitivity, explained →
? How do I download or print this manual?

What you see: You want a PDF or paper copy.

Why: The manual is a normal web page with a print stylesheet.

Fix: Use the “Print / Save as PDF” button at the top (or your browser's Print), then choose “Save as PDF”. All sections expand automatically for print.

Concepts & glossary

War-game
A seeded Monte-Carlo projection of the result under your strategy levers, with a win probability and an uncertainty band.
Cadence
Whether a step is done once, revisited (iterative) as data lands, or run continuously through the campaign.
Facts sheet
The sourced list of every number you'll claim; the message guard blocks any send whose claims aren't on it.
Consent gate
The legal rule that you may only text/call voters who granted consent — enforced on every send.
AHP
Analytic Hierarchy Process — turns pairwise judgements into a weighted, consistency-checked ranking.
Roll-off
The normal fall in participation down a multi-post ballot, modelled so later races tally lower.
Seat probability
For an at-large race, the share of Monte-Carlo trials in which a candidate wins a seat.
Build chip
The commit + deploy age shown in the admin console header and /api/health — your proof a deploy landed.