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