Votes

The Votes domain allows the community to signal quality on competing suggestions. It bridges "Chaos" (Suggestions) and "Order" (Consensus).

How Voting Works

Users cast votes on suggestions to influence which content wins consensus:

Votes are idempotent -- casting the same vote twice has no effect. Changing your vote (e.g., from upvote to downvote) automatically adjusts the suggestion's score, upvote count, and downvote count in a single atomic operation.

Vote Overlay Pattern

Vote state is personal data that is never baked into public pages. Instead, after a page loads, the frontend fetches the current user's votes for the visible suggestions and overlays them onto the UI. This allows content pages to be aggressively cached while still showing personalized vote state.

To fetch your votes, pass a list of suggestion IDs:

Code
GET /votes/me?suggestionIds=sug-123,sug-456,sug-789

Response:

Code
{
  "votes": {
    "sug-123": 1,
    "sug-456": -1
  }
}

Suggestions not present in the response have no vote from the current user.

Cast Vote Request

Code
{
  "suggestionId": "sug-123",
  "value": 1
}

API Endpoints

Both endpoints require authentication -- votes are always user-scoped.