plugin-voting/README.md

Voting Plugin

Overview

The Voting Plugin provides a comprehensive voting system for HOA board elections, decision-making, and community surveys. It enables HOAs to conduct various types of votes with proper tracking, result sharing, and audit trails.

Features

1. Campaign Types

• Board Elections: Vote for board members (Chairman, Treasurer, Deputy Manager, Members)
• Decisions: Vote on board decisions that require owner input
• Surveys: Collect public opinions on various matters

2. Form Builder (Placeholder)

Currently using a placeholder for form creation. Future versions will include:

• Drag-and-drop form builder
• External form builder integration
• Custom question types and validation

Form structure is stored as JSONB in the database, allowing flexibility for future enhancements.

3. Campaign Management

• Create, edit, and delete voting campaigns
• Set campaign dates (start and end)
• Configure result sharing (detailed, anonymous, none)
• Control public access (restrict/allow)
• Track campaign status (draft, scheduled, active, completed, cancelled)

4. Recipient Management

• Target all owners, board members, or authorized voters
• Create custom groups for targeted campaigns
• Support for multiple delivery methods (email, SMS, owner app)

5. Response Tracking

• Track participation percentage
• Monitor email/text delivery status
• Record answered dates and modifications
• Maintain audit trail with change logs

6. Results & Analytics

• View global and individual responses
• Export results as CSV or PDF
• Display participation statistics
• Generate analytics reports

Database Schema

Core Tables (pg_vt_* naming convention)

• pg_vt_campaigns: Voting campaign definitions
• pg_vt_forms: Form templates and structures
• pg_vt_responses: Individual response tracking
• pg_vt_response_answers: Detailed answer data
• pg_vt_response_change_logs: Audit trail
• pg_vt_groups: Custom recipient groups
• pg_vt_group_members: Group membership

All tables follow the plugin naming convention: pg_vt_* (pg_ = plugin, vt_ = voting plugin).

API Endpoints

Campaigns

• GET /api/plugins/voting/campaigns - List all campaigns
• GET /api/plugins/voting/campaigns/:id - Get campaign details
• POST /api/plugins/voting/campaigns - Create campaign
• PUT /api/plugins/voting/campaigns/:id - Update campaign
• DELETE /api/plugins/voting/campaigns/:id - Delete campaign

Forms

• GET /api/plugins/voting/forms - List all forms
• GET /api/plugins/voting/forms/:id - Get form details
• POST /api/plugins/voting/forms - Create form
• PUT /api/plugins/voting/forms/:id - Update form
• DELETE /api/plugins/voting/forms/:id - Delete form

Responses

• GET /api/plugins/voting/responses - List responses
• GET /api/plugins/voting/responses/:id - Get response details
• POST /api/plugins/voting/responses - Submit response

Groups

• GET /api/plugins/voting/groups - List all groups
• GET /api/plugins/voting/groups/:id - Get group details
• POST /api/plugins/voting/groups - Create group
• PUT /api/plugins/voting/groups/:id - Update group
• DELETE /api/plugins/voting/groups/:id - Delete group

Repository Pattern

All database operations use the repository pattern extending the core BaseRepository directly. This ensures:

• Database abstraction (works with all supported databases)
• Multi-tenant support via site_id
• Consistent CRUD operations
• No database-specific code

Repositories:

• CampaignRepository - pg_vt_campaigns
• FormRepository - pg_vt_forms
• ResponseRepository - pg_vt_responses
• ResponseAnswerRepository - pg_vt_response_answers
• ResponseChangeLogRepository - pg_vt_response_change_logs
• GroupRepository - pg_vt_groups
• GroupMemberRepository - pg_vt_group_members

Permissions

The plugin requires the following permissions:

• view_campaigns
• create_campaigns
• edit_campaigns
• delete_campaigns
• view_results
• manage_forms
• export_data
• view_analytics

Pricing Plans

Basic

• Board elections, decisions, basic surveys
• Email notifications
• 50 responses/month
• $39/month or $390/year

Professional

• Advanced elections and surveys
• Email & SMS notifications
• Custom forms
• Export results
• Analytics dashboard
• 1000 responses/month
• $79/month or $790/year

Enterprise

• Full voting suite
• Unlimited responses
• Advanced analytics
• API access
• White-label options
• $149/month or $1490/year

Future Enhancements

1. Form Builder: Drag-and-drop form creation UI
2. External Form Builder: Integration with tools like Typeform, JotForm
3. Advanced Analytics: Interactive dashboards and reporting
4. Real-time Updates: WebSocket support for live results
5. Mobile App: Enhanced voting experience on mobile
6. Integration: Connect with communication plugin for notifications

Installation

The plugin is automatically loaded by the PluginLoader on server startup. No additional configuration required.

Testing

All API endpoints should have comprehensive tests following TDD principles. Tests must use real database connections - no mocks allowed per project policy.

Architecture Compliance

This plugin follows all constitutional principles:

• ✅ Plugin-first architecture with prefixed table names (pg_vt_*)
• ✅ Repository pattern for database abstraction
• ✅ No mock data in tests
• ✅ TypeScript-ready structure
• ✅ Multi-tenant support
• ✅ RESTful API design