# 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

```bash
# Start everything
docker compose up -d

# View logs
docker compose logs -f

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

## Tests

```bash
# 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