sasa-membership/INSTRUCTIONS.md

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.

./restart.sh

Individual test commands:

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