The Democracy App: A platform for Free-Market Representation

• Overview
• The CrowdVote Vision
• Key Features
• Tech Stack
• Installation
• Project Goals
• Contributing
• Looking for Communities
• License

CrowdVote is a Django-based web application that enables communities to make decisions together through a revolutionary voting system that combines STAR Voting (Score Then Automatic Runoff) with transitively delegative democracy. Unlike traditional voting systems, CrowdVote allows community members to either vote directly on issues or delegate their voting power to trusted members on specific topics through a tagging system.

TL;DR: CrowdVote unlocks representation from fixed electoral terms by creating a free market where community members can:

• Vote directly on each referendum
• Delegate their vote to other members they trust on specific topics
• Compete to earn and retain that trust

CrowdVote brings a process I've been calling Social Democracy (as in "Social Media" …not the political ideology) to local communities such as condo associations, town councils, student governments, and anywhere else you might want to "crowdsource" decisions to a community of people.

Unlike a conventional, web-based polling application, CrowdVote allows community members to delegate their votes to one or more other members whose judgement they trust, whenever - and, specifically, on whichever issues they like. When you follow multiple people, their star ratings are averaged to calculate your ballot.

This is done through tagging the decisions you are voting on with terms like "budget" or "environment", which allows other members of the community who trust your judgement on such issues, to then follow you (inherit your votes) on those tags.

Because votes (and their tags) are transitive, the people from whom you inherit your votes may be inheriting theirs from someone else, and they from someone else, and so on.

Trees of influence can emerge organically and evolve to more accurately reflect community sentiment in real time, rather than only once every election cycle.

…because Real Democracy happens between elections.

A concrete example: say a condo board will decide next Tuesday what color to paint the community room.

Mary is a board member, and wants to crowdsource her decision on CrowdVote, along with any specific color choices, whether or not folks can write in their own colors, supporting documentation like color codes/swatches, contractor proposals, etc…

Her neighbor Jack sees Mary's published question, and responds by casting a Ranked Choice ballot: [ 'Cathedral Gray', 'Aqua Chiffon', 'Oceanside' ]. And if Jack wants to encourage other members of the community to follow him (again, to inherit his ballot) …he'll want to take a moment to further tag Mary's decision with terms he feels characterize her question and, more importantly, on which others in the community can follow him: [ "maintenance", "beautification", "community room" ].

Now, if their neighbor Sophia is out of town or fails to cast a ballot before next Tuesday for whatever reason, CrowdVote can attempt to calculate a ballot on her behalf …but only if she has previously identified in her profile other community members whose judgement she trusts sufficiently to follow their positions on decisions like this one. Moreover, she may be inheriting votes from lots of people, on a variety of matters. She may follow Mary on "environmental" issues, Jack on "maintenance" and "budget," and also Susan on "budget". …CrowdVote just figures out who's following whom, on which issues, and averages all their star ratings to calculate Sophia's ballot (which may result in fractional stars like 3.7 or 4.2), which she is of course free to override anytime before Tuesday by logging in to CrowdVote and casting her own.

CrowdVote = Free Market Representation.

…Rather than tying Representation to a fixed term in office, CrowdVote does something not unlike what Social Media has done to traditional media: it gives everyone a voice, even if it's only a re-tweet, +1, Pin or a Like, …all of which are functionally analogous, in the CrowdVote marketplace, to inheriting a vote.

People seeking to expand their influence in the community, like Jack above, will compete for followers by voting and tagging decisions thoughtfully, perhaps in conjunction with blogging and tweeting or otherwise promoting a reputation for expertise in the issues they care about. Lobbyists will turn their attention to those members with the most followers at any given time. Nobody has to wait until the next election to be heard. And all of this happens right out of the gate, because when you first fire CrowdVote up and begin publishing decisions to be voted on, your constituents will all effectively default to inheriting your vote, leaving you in a position of voting in accordance with the wishes of people who are all just inheriting your vote…but who are all free now to cast their own vote, or to follow someone else. They're not stuck with you until the next election!

Now, CrowdVote won't be able to enforce being used in any particular way. If you run for office on the pledge to CrowdVote all your decisions and then neglect to do so, or if your community decides to use CrowdVote itself in lieu of electing representatives at all, CrowdVote has no way to follow up on what happens after a decision's voting period closes. What CrowdVote can do, however, is make all data completely transparent and easily queried and audited through a friendly REST-ful API. Anyone can re-run the numbers anytime they like. And the calculation and tallying of every ballot is easily delineated in verbose tally reports. Finally, CrowdVote also provides a mechanism to verify everyone's membership in the community, while preserving the anonymity of the relationship between their identity and their voting record, thereby allowing voters to remain anonymous, if they like.

…I really appreciate any feedback or words of encouragement at support@CrowdVote.com, @CrowdVote or Facebook/CrowdVote! Beyond just being Open Sourced, I'd love to see this built such that any non-technical community leader could just deploy their own instance to the cloud with a simple click of a button. For now, I'm slowly building this thing between work and family, but figured I oughta get the idea out there and protected for everyone under:

CrowdVote and all ideas expressed above by Jason Blum are licensed under the GNU Affero General Public License v3.0.

• STAR Voting: Score Then Automatic Runoff voting system
• Tansitively Delegative Democracy: Delegate your vote to trusted members on any or specific topics, and those members can in turn delegate their votes to someone else and so on.
• Tag-Based Following: Follow different people for different topics (e.g., follow Alice on "budget", Bob on "environment")
• Transitive Voting: Inherit votes through chains of trust
• Vote Override: Always maintain the ability to cast your own vote directly
• Anonymous Voting: Optional anonymity while maintaining verifiable membership (enhanced system coming soon)

• Multi-Community Support: Host multiple communities on a single instance
• Transparent API: RESTful API for complete data transparency and auditability
• Detailed Tally Reports: Verbose logging of all vote calculations
• Member Verification: Secure membership verification system
• Bot Protection: Cloudflare Turnstile CAPTCHA prevents automated signups while remaining invisible to legitimate users
• One-Click Deploy: Simple deployment for non-technical users (coming soon)

• Backend: Django 5.2.6
• Database: PostgreSQL
• Styling: Tailwind CSS
• Container: Docker
• Deployment: Railway
• Version Control: GitHub

• django-allauth: Authentication and registration
• django-service-objects: Service layer for business logic
• django-taggit: Tagging system for issue categorization
• django-extensions: Development utilities
• django-debug-toolbar: Development debugging

No environment variables needed! Docker Compose provides everything:

• Database runs in db container (auto-configured)
• DEBUG=True by default
• Sensible defaults for all settings

Required Variables:

DATABASE_URL          # Automatically provided by Railway PostgreSQL
SECRET_KEY            # Generate: python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
DEBUG                 # Set to False

Recommended Variables:

ALLOWED_HOSTS         # Defaults: .railway.app,crowdvote.com (usually fine as-is)
ADMIN_URL             # Defaults: zanzibar (access admin at /zanzibar/ instead of /admin/)
ANONYMITY_SALT        # Generate unique salt for production ballot anonymity

Optional Email/Captcha Variables:

SENDPULSE_API_ID      # For magic link emails (15k/month free)
SENDPULSE_API_SECRET  # Get from sendpulse.com account settings
DEFAULT_FROM_EMAIL    # Default: noreply@crowdvote.com
TURNSTILE_SITE_KEY    # Cloudflare Turnstile for bot protection
TURNSTILE_SECRET_KEY  # Get from Cloudflare dashboard

For Railway Cron Service (weekly demo reset):

• Reference DATABASE_URL from main service
• Reference SECRET_KEY from main service
• Set DEBUG=False

See PRODUCTION_ENV_EXAMPLE.md for detailed setup instructions.

• Docker and Docker Compose
• Git

1. Clone the repository

   git clone https://github.com/jasonblum/crowdvote.git
   cd crowdvote

2. Configure environment variables

   # For development, the Docker setup works with defaults
   # No .env file needed for basic Docker development
   # (Docker Compose provides the database connection)

3. Start the development environment

   docker-compose up -d

4. Run initial setup

   # Apply migrations
   docker-compose exec web python manage.py migrate
   
   # Create superuser
   docker-compose exec web python manage.py createsuperuser
   
   # Load demo data (optional but recommended)
   docker-compose exec web python manage.py generate_dummy_data

5. Visit the application

   • Main app: http://localhost:8000
   • Admin interface: http://localhost:8000/admin

Once your Docker environment is running, these commands are essential for development:

# Watch live application logs (essential for debugging!)
docker-compose logs -f web

# Watch logs from all services
docker-compose logs -f

# Run Django management commands
docker-compose exec web python manage.py migrate
docker-compose exec web python manage.py shell
docker-compose exec web python manage.py createsuperuser

# Check container status
docker-compose ps

# Stop all services
docker-compose down

# Restart services (only needed for settings changes or new dependencies)
docker-compose restart web

Pro tip: Keep docker-compose logs -f web running in a separate terminal window while developing to see real-time HTTP requests, errors, and Django auto-reload messages.

CrowdVote has a comprehensive test suite with 525 tests covering all core functionality. The test suite maintains 100% reliability with excellent coverage of critical components.

# Run all tests (recommended)
docker-compose exec web python -m pytest

# Run tests with verbose output
docker-compose exec web python -m pytest -v

# Run specific test file
docker-compose exec web python -m pytest tests/test_views/test_follow_views.py

# Run tests with coverage report
docker-compose exec web python -m pytest --cov

# Generate HTML coverage report (opens in browser)
docker-compose exec web python -m pytest --cov --cov-report=html
open htmlcov/index.html

• 525 passing tests, 0 failing (100% success rate)
• Test execution time: ~12 seconds for full suite
• Overall coverage: 67% with excellent coverage in core areas:
  • Follow/Unfollow UI: 98% coverage
  • Delegation Tree Service: 97% coverage
  • User Models: 96% coverage
  • STAR Voting Services: 86% coverage

• Models: User accounts, communities, decisions, voting
• Views: Authentication, profiles, voting, delegation
• Forms: User input validation, follow/unfollow UI
• Services: STAR voting calculations, delegation trees
• Integration: End-to-end workflows and user journeys

The test suite ensures CrowdVote's democratic processes work reliably and accurately handle complex delegation scenarios.

If you prefer to run without Docker:

1. Prerequisites

   • Python 3.11+
   • PostgreSQL 14+

2. Set up virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

   # Install uv (fast Python package installer)
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Install dependencies
   uv pip install -r requirements.txt

4. Configure database and run setup

   # Configure environment (create .env file with your settings)
   # See PRODUCTION_ENV_EXAMPLE.md for environment variable reference
   
   # Run migrations and setup
   python manage.py migrate
   python manage.py createsuperuser
   python manage.py generate_dummy_data
   python manage.py runserver

Experience a fully functional democratic system with real communities making actual decisions:

• Minion Collective: Community governance decisions like "World Domination Meeting Schedule" and "Banana Budget Allocation"
• Springfield Town Council: Municipal decisions including "Nuclear Safety Inspections" and "Donut Shop Zoning"
• Real-time voting and delegation: See tag-based delegation in action
• Complete STAR voting: Score choices 0-5 stars, then automatic runoff
• Transparent audit trails: Track how votes flow through delegation networks

Visit http://localhost:8000 after setup to see 454+ users participating in real democratic processes!

Making CrowdVote accessible to non-technical community leaders through:

• Railway deploy button
• Automated setup wizard
• Pre-configured templates for different community types
• Zero technical knowledge required

Actively seeking partnerships with:

• Condo Associations: Building maintenance, budget decisions, community rules
• Town Councils: Local ordinances, budget allocation, community projects
• Student Governments: Campus policies, event planning, budget distribution
• Co-ops and Collectives: Operational decisions, member policies
• Small Organizations: Teams of 50-500 people making regular decisions

We welcome contributions from developers, designers, and democracy enthusiasts!

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

• Frontend Development: Improving the UI/UX with Tailwind CSS
• Visualization: Creating engaging real-time vote visualization
• Testing: Writing comprehensive test suites
• Documentation: Improving docs and creating tutorials
• Community Outreach: Finding real communities to pilot the platform

• Follow Django best practices
• Write tests for new features
• Keep commits atomic and well-described
• Update documentation as needed
• Maintain docs/CHANGELOG.md with development session history

Are you part of a community that makes decisions together?

We're actively seeking communities to collaborate with for real-world testing and implementation. Ideal communities:

• Have 50-500 members
• Make regular decisions together
• Want more democratic participation
• Are open to trying new approaches

If this sounds like your community, please reach out to support@crowdvote.com

• Email: support@crowdvote.com
• Twitter: @CrowdVote
• Facebook: Facebook/CrowdVote
• Issues: GitHub Issues

This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.

Real Democracy happens between elections.
Built with ❤️ for communities everywhere