forked from jamesp/sasa-membership
188 lines
8.4 KiB
Markdown
188 lines
8.4 KiB
Markdown
# Swansea Airport Stakeholders' Alliance Membership Management System
|
|
|
|
## Project Overview
|
|
|
|
This project aims to develop a comprehensive membership management system for the Swansea Airport Stakeholders' Alliance. The system will handle member registration, payment processing, membership tracking, and administrative functions for a medium-sized alliance.
|
|
|
|
## Current Implementation Status
|
|
|
|
The app now includes a FastAPI backend, React/Vite frontend, Docker Compose development gateway, Alembic migrations, Square payment integration, SMTP2GO email integration, ESP RFID provisioning/time-sync/tap tracking, event/RSVP endpoints, configurable profile questions, privacy/terms pages, feature flags, UTC backend timestamps with London-facing frontend formatting, and a fast test gate in `restart.sh`.
|
|
|
|
## Core Features
|
|
|
|
### Public Member Features
|
|
- **Self-Service Registration**: Members can sign up online and select their membership tier
|
|
- **Payment Processing**: Integration with Square payment system for secure online payments, and a dummy payment system for initial testing
|
|
- **Membership Portal**: Secure login to view membership status, payment history, and upcoming meetings
|
|
- **Profile Questions**: Members can answer configurable profile questions, including conditional and volunteering-related questions
|
|
- **Event Management**: View upcoming events and RSVP to participate
|
|
- **Account Management**: Members can update profile details, change passwords, request password resets, and review privacy/terms pages
|
|
- **Renewal Reminders**: Planned automated email notifications for membership renewal deadlines
|
|
- **Volunteering**: Volunteer-related profile fields are implemented; richer role, schedule, and certificate screens are planned
|
|
|
|
### Administrative Features
|
|
- **Member Database Management**: Query and modify member records
|
|
- **Manual Payment Entry**: Record cash payments to activate memberships
|
|
- **Membership Tier Management**: Configure different membership levels and associated fees
|
|
- **Profile Question Management**: Create, edit, deactivate, order, and configure dependencies for member profile questions
|
|
- **Meeting/Event Management**: Create, edit, and manage events, track RSVPs and attendance
|
|
- **Timezone Handling**: Persist timestamps in UTC, display member-facing times in Europe/London, and convert event input back to UTC before saving
|
|
- **ESP RFID Readers**: Reader registration, time sync, taps, attendance sessions, and queued card-writing jobs are implemented end to end
|
|
- **Email Management**: Edit database-backed email templates with escaped previews, send test emails, and monitor SMTP2GO bounces
|
|
- **Feature Flags**: View backend feature flags and reload them from the super-admin interface
|
|
- **Reporting**: Planned reports on membership statistics and payment status
|
|
- **Files**: Planned repository for member files based on tier, such as meeting minutes and manuals
|
|
- **Event Management**: Create, edit, and manage events, track RSVPs and attendance
|
|
- **Volunteering**: Models exist for configurable volunteer roles, assignments, schedules, and certificates/training. Note: A member may not necessarily be a volunteer, but all volunteers are members.
|
|
|
|
|
|
## Technical Stack
|
|
|
|
- **Backend**: Python with FastAPI/Uvicorn for high-performance async web framework
|
|
- **Database**: MySQL for reliable data storage and complex queries
|
|
- **Authentication**: JWT-based authentication system
|
|
- **Payment Integration**: Square API for payment processing
|
|
- **Email Service**: SMTP2GO API for automated reminders and notifications
|
|
- **Frontend**: React 18, TypeScript, Vite, and Tailwind CSS
|
|
- **Testing**: Vitest for frontend unit tests and pytest for backend unit tests
|
|
|
|
## Membership Tiers
|
|
|
|
The system should support configurable membership tiers, including:
|
|
- Basic membership (Personal) £5 / year
|
|
- Group membership (Aircraft Owners) £25 / year
|
|
- Corporate membership (£100 / year)
|
|
- Other custom tiers as needed
|
|
|
|
Each tier will have associated annual fees and benefits.
|
|
|
|
## Payment System
|
|
|
|
- Primary payment method: Square integration for online payments
|
|
- Support for manual payment entry (cash/check payments)
|
|
- Annual fee collection with automatic renewal reminders
|
|
- Payment history tracking
|
|
|
|
## Security Requirements
|
|
|
|
- Secure user authentication and authorization
|
|
- Data encryption for sensitive information
|
|
- Role-based access control (members vs administrators)
|
|
- GDPR compliance for data protection
|
|
|
|
## Email Integration
|
|
|
|
- Welcome emails for new members
|
|
- Payment confirmation emails
|
|
- Renewal reminder emails (configurable timing)
|
|
- Meeting notification emails
|
|
- Administrative notification emails
|
|
|
|
## Database Schema (High-Level)
|
|
|
|
### Core Tables
|
|
- `users`: Member information and authentication
|
|
- `memberships`: Membership records with tier and status
|
|
- `payments`: Payment transactions
|
|
- `tiers`: Membership tier definitions
|
|
- `profile_questions`: Configurable profile/onboarding questions
|
|
- `user_profile_answers`: Per-member profile answers
|
|
- `events`: Event information and details
|
|
- `event_rsvps`: Event registration and attendance tracking
|
|
- `volunteer_roles`: Configurable volunteer role definitions (e.g., Fire, Radio, General)
|
|
- `volunteer_assignments`: Member-to-role assignments
|
|
- `volunteer_schedules`: Volunteer shift scheduling and availability
|
|
- `certificates`: Training certificates and qualifications
|
|
- `email_templates`: Editable SMTP2GO email templates
|
|
- `email_bounces`: Bounce/complaint/unsubscribe tracking
|
|
- `password_reset_tokens`: One-time reset tokens
|
|
- `notifications`: Email notification logs
|
|
|
|
## Testing and Restart Workflow
|
|
|
|
`./restart.sh` rebuilds Docker images with cache, runs the fast frontend and backend unit tests, shuts down the current stack, and starts it again only if tests pass.
|
|
|
|
```bash
|
|
./restart.sh
|
|
```
|
|
|
|
Individual test commands:
|
|
|
|
```bash
|
|
docker compose run --rm frontend npm test
|
|
docker compose run --rm backend pytest -q
|
|
```
|
|
|
|
## Development Phases
|
|
|
|
1. **Phase 1**: Core API development (authentication, user management) - implemented
|
|
2. **Phase 2**: Payment integration and membership management - implemented
|
|
3. **Phase 3**: Admin interface development - implemented for users, tiers, payments, emails, bounces, profile questions, and feature flags
|
|
4. **Phase 4**: Member portal, email system, event management, and volunteering features - partially implemented; richer volunteer screens and renewal reminders remain
|
|
5. **Phase 5**: Testing, deployment, and documentation - active; fast unit tests and documentation are in place
|
|
|
|
## Deployment Considerations
|
|
|
|
- Containerized deployment using Docker
|
|
- Scalable architecture for medium-sized alliance
|
|
- Backup and recovery procedures
|
|
- Monitoring and logging
|
|
|
|
## Future Enhancements
|
|
|
|
- Mobile app development
|
|
- Advanced reporting and analytics
|
|
- Integration with other alliance systems
|
|
- Multi-language support
|
|
- **Asynchronous Batch Processing**: Implement automated renewal reminder system using scheduled batch jobs
|
|
- Create containerized renewal reminder script that runs daily
|
|
- Query memberships expiring within configurable timeframe (e.g., 30 days)
|
|
- Send personalized renewal reminder emails using existing email templates
|
|
- Add batch job scheduling with cron or similar scheduler
|
|
- Include logging and monitoring for batch job execution
|
|
- Extend pattern for other automated tasks (payment reminders, membership expiration processing)
|
|
|
|
## Project Requirements
|
|
|
|
### Functional Requirements
|
|
- User registration and authentication
|
|
- Membership tier selection and management
|
|
- Payment processing and tracking
|
|
- Email notification system
|
|
- Administrative dashboard
|
|
- Member self-service portal
|
|
- Event management and RSVP system
|
|
- Volunteer role assignment, scheduling, and certificate/training management
|
|
|
|
### Non-Functional Requirements
|
|
- High availability and performance
|
|
- Data security and privacy
|
|
- Scalable architecture
|
|
- User-friendly interface
|
|
- Comprehensive documentation
|
|
|
|
## Team Considerations
|
|
|
|
- Backend developers (Python/FastAPI)
|
|
- Frontend developers (if separate frontend)
|
|
- Database administrators
|
|
- DevOps engineers
|
|
- QA testers
|
|
- Business analysts for requirements refinement
|
|
|
|
## Risk Assessment
|
|
|
|
- Payment system integration complexity
|
|
- Email deliverability issues
|
|
- Data migration from existing systems
|
|
- User adoption and training
|
|
- Regulatory compliance requirements
|
|
|
|
## Success Metrics
|
|
|
|
- Successful member registration rate
|
|
- Payment processing success rate
|
|
- User engagement with portal
|
|
- Administrative efficiency improvements
|
|
- System uptime and performance
|