Polls v1 for the Raklet social wall

01TL;DR

02What we're building

A "Poll" post type that sits inside the existing Announcement system on the community wall. Admins create a poll the same way they create an image-or-text post today, with a new toggle at the top of the create form. Members see the poll in their feed and vote with one tap. Results render inline.

Two important per-poll settings the admin picks at create time:

The differentiated framing is that v1's defaults (lock-after-vote, anonymous, eligibility = audience) are safe enough for non-binding informal elections in associations and non-profits — the customer set Raklet actually serves. v1.5 adds the formal-election features (eligibility scoping, voter-roll snapshot, k-anonymity warnings, audit log) when customer demand validates that framing.

The member poll card — three states

Members see the same card layout regardless of where they are in the flow. Card morphs between states without a page reload. The trust microcopy is conditional on the per-poll PollVoteVisibility setting.

Public mode — vote attribution visible

The same card with PollVoteVisibility = Public. Notice the microcopy changes — Raklet is upfront with members that their name will appear next to their vote when they cast it.

Admin create-poll form

The admin form lives in the existing create-post modal. A segmented Post / Poll toggle at the top swaps the editor in place. No new admin nav, no separate page.

End-to-end flow (admin to member to closed)

03How we got here

The original CEO ask was simple: "add a polls post type with a results-visibility setting and anonymity." Over the course of five review passes, the design accumulated election-grade features (eligibility scoping, k-anonymity warnings, audit log, member-created polls + moderation queue, the EntityLeakageGuard reflection assertion, 3-step migration trilogy, email-results rendering, etc.). At the end of that process the CEO observed that v1 had become roughly 3× the original ask without customer validation.

The plan was recut to minimum-v1. Everything the reviews surfaced is preserved as a v1.5 / v2 roadmap inside the design doc, but ships only when real customer demand surfaces it. This presentation reflects the post-recut state.

04V1 scope

05What's deferred and why

Most deferrals are election-grade features (eligibility scoping, voter-roll snapshot, audit log, k-anonymity warning) that the design reviews surfaced as worthwhile once customers validate the governance use case. v1 ships safe enough for informal elections (lock-after-vote, server-enforced close, anonymity-by-policy with the integration test) without yet committing the architecture to formal governance.

A second group of deferrals is UX polish (publish-confirmation modal, drag-and-drop options editor, email-results rendering) — defensible additions that don't block the core flow. They join the roadmap.

The third group is platform infrastructure (EntityLeakageGuard reflection assertion, EligibilityRollSnapshot generalized for Events) that only earns its complexity once Raklet has multiple consumers. IdempotencyKey is the one platform primitive we kept in v1, because naming it correctly is a one-way decision — refactoring after Events RSVP and Payments adopt it is expensive, doing it right at first commit is cheap.

06Architecture

Approach A from the design doc: a discriminator on the existing Announcement table. Survived four reviews and one Codex challenge.

The hot path is PollService.SubmitVoteAsync. Read order: idempotency-key replay check, poll-state validation, audience + eligibility check, lock-after-vote check, transactional insert. The DB unique constraint catches concurrent racers; the service maps the constraint violation back to "you already voted" with the caller's current vote.

Component view of the vote-submission hot path

Blue path = vote submission (the hot path). Grey = standard reads + create. Dashed boxes = SQL tables. IdempotencyKey stores the per-request hash so a network-retried vote returns the cached response instead of double-counting.

07The anonymity promise

PollVote.OrganisationMembershipId exists in the database (we need it to enforce lock-after-vote and to surface the caller's own vote). The promise is that no V2 endpoint, no admin response, no export ever surfaces the link between a member and their vote choice on Anonymous polls. Pseudonymous-in-DB, anonymous at every wire.

Three layers of protection in v1:

1. Service-layer scoping — GetResultsAsync only returns the calling member's own MyVoteOptionIds; other members' votes are never serialized.
2. Razor DTO surface — PollPayloadDto carries aggregates only. Per-option voter names are deferred to v1.5 for Public-mode polls; v1's Public-mode distinction is microcopy only.
3. Integration test — Raklet.UnitTests/Polls/PollAnonymityTest.cs has three sub-tests:
   • Reflection DTO whitelist — fails fast if any future refactor adds OrganisationMembershipId, MemberId, Member, or Voter to a poll-vote-adjacent DTO.
   • Live PollService exercise — seeds an anonymous poll plus three voters, asserts per-caller MyVote isolation, serializes results to JSON and asserts the forbidden property names do not appear.
   • V2 HTTP test skeleton — [Ignore]'d placeholder for OwinTestServer wiring.

What the database stores vs what the API returns

For an Anonymous poll where Sarah, Marcus, and Jenny voted, here's what lives in PollVote vs what any caller sees on GET /v2/.../social/announcements:

Id        AnnId     OrgMembershipId  OptionId
─────────────────────────────────────
guid-1    poll-A    sarah-id         opt-A
guid-2    poll-A    marcus-id        opt-A
guid-3    poll-A    jenny-id         opt-B

{
  "id": "poll-A",
  "poll": {
    "totalVotes": 3,
    "options": [
      { "id": "opt-A", "voteCount": 2 },
      { "id": "opt-B", "voteCount": 1 }
    ],
    "myVote": { "optionIds": ["opt-A"] }
  }
}

OrganisationMembershipId exists in the DB row (we need it to enforce lock-after-vote and to surface the caller's own vote at myVote.optionIds) but is never serialized adjacent to vote data on any V2 endpoint when the poll is Anonymous. PollAnonymityTest asserts this via reflection (DTO whitelist) + live JSON serialization grep.

08PRs and deploy branch

Stacked review surfaces, in merge order:

09How to test locally

git fetch origin
git checkout polls-v1-deploy
git pull origin polls-v1-deploy

# Restore packages once if your main checkout hasn't recently
.\.nuget\NuGet.exe restore Raklet.sln

# Apply migration (Visual Studio Package Manager Console, Models project)
Update-Database -ConfigurationTypeName Models.Migrations.Configuration

# Build + run via your normal local flow
# (build-fast.ps1 for Application; MSBuild per-project for Models,
#  Services, Raklet.Api, Raklet.WebJobs, Raklet.UnitTests)

Then walk this script on gercek.raklet.org:

1. Admin: Open the community wall. Click new post. Toggle to Poll. Fill question, 2–4 options, close date 1h+ out. Pick selection mode + results visibility + vote visibility. Publish.
2. Verify it lands on the wall as the first item.
3. Member: open the wall as a different member. The card should render with options as radios (or checkboxes for Multi). Microcopy below the options matches the vote-visibility you picked (Anonymous: "Raklet does not show…"; Public: "Your name will be shown…").
4. Vote. Pick an option. Vote button enables. Click. State morphs to results — inline bar chart with percentages, "Your vote" badge on the chosen option.
5. Try to vote again after refresh. Expect 409 with a friendly "You have already voted" message. (Lock-after-vote is v1 behaviour.)
6. Close the poll. Wait for the WebJob (every ~5 min if scheduled) or call POST /v2/.../social/polls/{id}/close manually. Card flips to closed state with a "Poll closed" pill plus final results.
7. Anonymity sanity check. Open DevTools network tab during the wall load. The GET /v2/.../social/announcements response on an Anonymous poll should not contain OrganisationMembershipId anywhere adjacent to vote or option data. Your own myVote.optionIds is the only member-link.

10The Assignment (blocking PR-1 deploy)

11V1.5 / v2 roadmap

The full roadmap with rationale, effort estimates, and dependencies lives in docs/features/polls/design.md under "V1.5 / V2 Roadmap." Headline items in rough priority order if customers validate governance use:

If casual polls dominate the customer calls, the UX polish items pull in first instead:

12Process record

What ran before any code was written. Useful context when reviewing the PRs — most decisions have a documented "why" behind them in the design doc.

13Standing rules to follow

Project conventions from the Raklet team that the implementation already honours and v1.5 work should keep honouring:

• Never commit to master. Use feature branches and PRs.
• Always worktree-first. Even small fixes get a worktree off latest master. Don't pollute the main checkout.
• EF migrations branch first. Migrations ship in their own branch, released before logic code that depends on them. (v1 honored this — PR-1 is schema-only.)
• Build per-project with MSBuild. build-fast.ps1 --all only rebuilds Application.csproj; call MSBuild for Models, Services, Raklet.Api, Raklet.WebJobs, Raklet.UnitTests individually.
• Don't --no-verify. Pre-commit hooks exist for a reason.
• Pre-PR-ready smoke. Every user-facing PR runs scripts/dev/pr-ready-check.ps1 before mark-ready / merge.
• QA evidence to Azure Blob. PR screenshots upload to rakletlocalfiles/customcodes/pr-evidence/<num>/ via the documented PowerShell snippet — never commit images to the repo.
• Don't assert prod scale without measurement. Check docs/agents/hot-tables.md before claiming a table is hot. (Announcement is not in the hot-tables registry.)
• Worktree cleanup after merge. Remove the worktree and local branch once its PR is merged. Five temporary agent worktrees have already been cleaned up.