sasa-membership/PROJECT_STRUCTURE.md

Project Structure

membership/
├── .env                          # Local environment configuration
├── .env.example                  # Environment variable template
├── .gitignore                    # Git ignore rules
├── docker-compose.yml            # Backend, frontend, gateway, and prod frontend services
├── restart.sh                    # Build, run fast tests, and restart the app
├── INSTRUCTIONS.md               # Product requirements and roadmap context
├── README.md                     # Full project documentation
├── QUICKSTART.md                 # Short operator/developer guide
│
├── backend/                      # FastAPI application
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── alembic.ini
│   ├── alembic/                  # Database migrations
│   └── app/
│       ├── main.py               # App, CORS, health check, router registration
│       ├── api/
│       │   ├── dependencies.py   # Auth dependencies
│       │   └── v1/
│       │       ├── auth.py       # Register, login, password reset/change
│       │       ├── users.py      # Users, profile questions, profile answers
│       │       ├── tiers.py      # Membership tiers
│       │       ├── memberships.py
│       │       ├── payments.py   # Manual, Square, refund, payment history
│       │       ├── email.py      # SMTP2GO email tests and bounce webhooks
│       │       ├── email_templates.py
│       │       ├── events.py     # Events and RSVPs
│       │       └── feature_flags.py
│       ├── core/                 # Config, database, security, default data
│       ├── models/               # SQLAlchemy models
│       ├── schemas/              # Pydantic schemas
│       ├── services/             # Email, bounce, Square, feature flags
│       └── tests/                # Fast backend pytest unit tests
│
├── docker/
│   └── gateway/                  # Nginx dev gateway and self-signed TLS setup
│
└── frontend/                     # React/Vite frontend
    ├── Dockerfile
    ├── package.json
    ├── vite.config.ts
    └── src/
        ├── App.tsx               # Routes, footer links, cookie notice
        ├── components/           # Dashboard, admin, payment, email, profile UI
        ├── contexts/             # Feature flag context/provider
        ├── pages/                # Login, register, dashboard, policy pages
        ├── services/             # API clients
        └── utils/                # Shared frontend logic and Vitest tests

Key Files

Configuration

• .env - Runtime configuration for database, auth, Square, SMTP2GO, ports, and gateway TLS.
• docker-compose.yml - Services for FastAPI backend, Vite frontend, Nginx gateway, and production static frontend.
• restart.sh - Rebuilds images, runs frontend/backend unit tests, and restarts the stack only if tests pass.

Backend Application

• backend/app/main.py - FastAPI app initialization, CORS, startup default-data seeding, routes, and health checks.
• backend/app/core/config.py - Settings management.
• backend/app/core/init_db.py - Default membership tiers, super admin, email templates, and profile questions.
• backend/app/core/security.py - JWT tokens and password hashing.
• backend/app/models/models.py - Database tables.
• backend/app/schemas/schemas.py - API request/response models.
• backend/app/tests/test_profile_question_logic.py - Fast backend unit tests for profile answer validation.

Frontend Application

• frontend/src/pages/Dashboard.tsx - Main member/admin dashboard.
• frontend/src/components/MembershipSetup.tsx - Membership tier selection and payment flow.
• frontend/src/components/SquarePayment.tsx - Square Web Payments SDK form.
• frontend/src/components/AdminProfileQuestionManager.tsx - Admin profile-question configuration.
• frontend/src/components/ProfileQuestionsForm.tsx - Member/admin answer form with dependency handling.
• frontend/src/components/EmailTemplateManagement.tsx - Email template editing.
• frontend/src/components/BounceManagement.tsx - SMTP2GO bounce management.
• frontend/src/utils/profileQuestionLogic.test.ts - Fast frontend unit tests for profile-question visibility/editability.

API Endpoints

• auth.py - Register, login, forgot password, reset password, change password.
• users.py - Current user profile, admin user CRUD, profile-question CRUD, member/admin profile answers, and role-guarded admin password reset emails.
• tiers.py - Membership tier CRUD.
• memberships.py - Member/admin membership management.
• payments.py - Payment history, manual payments, Square config/process/refund.
• events.py - Event CRUD, upcoming events, RSVP create/update, RSVP listing.
• email.py - SMTP2GO test emails, welcome email tests, bounce webhook, bounce stats, cleanup, deactivation.
• email_templates.py - Database-backed template listing, lookup, update, and default seeding.
• feature_flags.py - Public feature flag listing/lookup and super-admin-only reload.

Database Models

Fully implemented:

• User - Authentication, profile, roles, volunteer level.
• ProfileQuestion - Configurable profile fields, options, dependencies, admin-only edit flags.
• UserProfileAnswer - Per-user answers with update attribution.
• MembershipTier - Configurable tiers with fees and benefits.
• Membership - User memberships with status, dates, and auto-renew flag.
• Payment - Payment records for Square, cash, check, and dummy methods.
• Event - Event management records.
• EventRSVP - RSVP and attendance records.
• EmailTemplate - Editable database-backed email templates.
• EmailBounce - SMTP2GO bounce, complaint, and unsubscribe tracking.
• PasswordResetToken - One-time password reset support.
• VolunteerRole - Volunteer role definitions.
• VolunteerAssignment - Member-to-role assignments.
• VolunteerSchedule - Volunteer shift schedules.
• Certificate - Training/certificate records.
• File - File repository metadata.
• Notification - Email notification logs.

Quick Start

# Start everything
docker compose up -d

# View logs
docker compose logs -f

# Access API docs
# http://localhost:8050/docs

Tests

# Run both fast test suites and restart only if they pass
./restart.sh

# Run test suites individually
docker compose run --rm frontend npm test
docker compose run --rm backend pytest -q

Default Credentials

Admin: admin@swanseaairport.org / admin123

Database: Configured via environment variables in .env.

Remaining Roadmap

1. Expand authenticated API tests for member/admin workflows
2. Add member file repository endpoints and UI
3. Build richer volunteer assignment, schedule, and certificate screens
4. Add renewal reminder batch jobs
5. Add reporting and analytics