polis

a transparent political system where citizens can view, discuss,
and vote on projects, laws, and constitutional amendments.
designed to be simple and fast so it runs on low-end hardware,
preserving access for low-income people.


features

- view and filter documents by type, status, and location
- cast votes (positive, negative, blank) with one vote per day
- comment on discussion threads (rate-limited)
- create new documents (laws, projects, constitutional amendments)
- real-time vote counting and quorum display
- watch/favorite documents to track changes
- downloadable lawbooks and constitutions by level
- location-based eligibility (federal, state, city)


tech stack

- backend: Go (Golang)
- database: MongoDB
- frontend: HTML/CSS with server-side rendering
- authentication: CPF (Brazilian tax ID), email, password


core concepts

- document lifecycle: draft → open → approved/rejected
- quorum: 50% of eligible users must vote for validity
- voting period: 3 months for open documents (rolling)
- secret voting: only aggregate results are visible
- percentage: pos/(pos+neg+blank)


installation

prerequisites: Go 1.21+, MongoDB.

build from source:

  git clone https://github.com/blmayer/polis.git
  cd polis
  go build -o polis ./cmd/server

set environment variables:

  POLIS_MONGO_URI=mongodb://localhost:27017
  POLIS_MONGO_DB=polis
  POLIS_ADDR=:8080

run the server:

  ./polis


usage

- register with CPF, email, and password
- browse documents by level (federal/state/city) and status
- search and filter documents
- vote (positive, negative, blank) on open documents
- comment on document discussion threads
- create new documents (limit: 1 per month)
- watch documents to get notified of changes
- view your voting history and statistics


license

MIT License

(C) 2025-2026 Brian Mayer