427e7578-d7bf-49c8-aee9-2dd999e25316/specs/008-voting-system/README.md

status, created, tags, priority, created_at, depends_on, updated_at, related

status	created	tags	priority	created_at	depends_on	updated_at	related
planned	2026-03-16	voting core	high	2026-03-16T07:51:50.525Z	005-poll-creation-management	2026-03-16T09:18:58.099Z	011-mobile-first-ui

Voting System & Anonymity

Status: 🗓️ Planned · Priority: High · Created: 2026-03-16 · Tags: voting, core

Overview

Core voting functionality: participants can add options to a poll and cast votes. Supports both anonymous and non-anonymous modes as configured at poll creation. Votes are sent to the poll owner via PeerJS.

Design

Adding Options

• Participants and above can add options while the poll is open
• Options have text only (keep it simple)
• Owner validates the sender has permission before accepting

Casting Votes

• V1: single-choice (one vote per participant). Data model uses optionId: string which can later be extended to optionIds: string[] for multi-choice or a ranked array for ranked-choice.
• Vote is signed with voter's private key for authenticity
• In anonymous mode: owner records the vote but strips voterId before storing
• In non-anonymous mode: voterId is stored alongside the vote
• Vote changes: a participant can change their vote while the poll is open (replaces previous)

Results

• Results are visible to all roles (viewers included)
• Show: option text, vote count, percentage
• Non-anonymous: also show who voted for what
• Results update in real-time via PeerJS messages

Vote Flow

Participant                    Owner (relay)
    │                              │
    │─── poll:vote ───────────────▶│ validate permission
    │                              │ if anonymous: strip voterId
    │                              │ store vote
    │◀── poll:state:update ───────│ broadcast updated results

Plan

• Build "add option" UI and message handler
• Build voting UI (option list with vote button)
• Implement vote submission (sign + send to owner)
• Owner-side vote processing (validate, anonymize if needed, store)
• Build results display (bar chart or simple percentage view)
• Implement vote change (replace previous vote)

Test

• Participant can add an option
• Participant can cast a vote
• Anonymous vote does not leak voter identity
• Results update in real-time across connected peers
• Vote change replaces (not duplicates) previous vote
• Viewers can see results but not vote