# 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