174 lines
5.4 KiB
Markdown
174 lines
5.4 KiB
Markdown
# 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
|
|
|