# Swansea Airport Stakeholders' Alliance Membership Management System

A comprehensive membership management system built with FastAPI, MySQL, and Docker.

## Features

- **User Management**: Registration, authentication, and profile management
- **Membership Tiers**: Configurable membership levels with different benefits and fees
- **Payment Processing**: Support for Square payments, cash, and check payments
- **Admin Dashboard**: Complete administrative control over members and payments
- **Event Management**: Create and manage events with RSVP tracking (coming soon)
- **Volunteer Management**: Role assignments, scheduling, and certificates (coming soon)
- **Email Notifications**: Automated notifications via SMTP2GO (coming soon)

## Tech Stack

- **Backend**: FastAPI (Python 3.11)
- **Database**: MySQL 8.0
- **Authentication**: JWT tokens with OAuth2
- **Containerization**: Docker & Docker Compose
- **ORM**: SQLAlchemy

## Project Structure

```
membership/
├── backend/
│   ├── alembic/                     # Database migration scripts
│   │   ├── versions/                # Migration files
│   │   ├── env.py                   # Migration environment
│   │   └── script.py.mako           # Migration template
│   ├── alembic.ini                  # Alembic configuration
│   ├── app/
│   │   ├── api/
│   │   │   ├── v1/
│   │   │   │   ├── auth.py          # Authentication endpoints
│   │   │   │   ├── users.py         # User management
│   │   │   │   ├── tiers.py         # Membership tiers
│   │   │   │   ├── memberships.py   # Membership management
│   │   │   │   └── payments.py      # Payment processing
│   │   │   └── dependencies.py       # Auth dependencies
│   │   ├── core/
│   │   │   ├── config.py            # Configuration
│   │   │   ├── database.py          # Database setup
│   │   │   └── security.py          # Security utilities
│   │   ├── models/
│   │   │   └── models.py            # Database models
│   │   ├── schemas/
│   │   │   └── schemas.py           # Pydantic schemas
│   │   └── main.py                  # Application entry point
│   ├── Dockerfile
│   └── requirements.txt
├── database/
│   └── init.sql                     # Legacy database initialization (deprecated - use Alembic migrations)
├── docker-compose.yml
├── .env.example
└── README.md
```

## Getting Started

### Prerequisites

- Docker
- Docker Compose

### Installation

1. **Navigate to the project directory**

2. **The `.env` file is already configured** with default settings. You can customize:
   - Square API credentials (for payment processing)
   - SMTP2GO API key (for email notifications)
   - Database password (if desired)

3. **Start the services**:
   ```bash
   # Development mode (gateway + Vite hot reload)
   docker compose up -d

   # Production static frontend mode
   docker compose --profile prod up -d frontend-prod backend
   ```

4. **Wait for services to be ready** (about 30 seconds for MySQL initialization):
   ```bash
   docker compose logs -f
   ```
   Press Ctrl+C when you see "Application startup complete"

5. **Access the application**:
   - Frontend (HTTP): http://localhost:8050
   - Frontend (HTTPS for Square): https://localhost:8443
   - API: http://localhost:8050/api/v1
   - API Documentation: http://localhost:8050/docs
   - TLS certs are generated automatically by the gateway container on first start

## Frontend Development vs Production

### Development Mode (Vite)
```bash
docker compose up -d
```
- Single entry point on port 8050
- Nginx gateway routes `/api/*` to backend and all other traffic to Vite
- Hot reloading and development features
- Access at: http://localhost:8050

### Production Mode (Nginx)
```bash
docker compose --profile prod up -d frontend-prod backend
```
- Frontend served by Nginx on port 8050
- Optimized static files, production-ready
- Access at: http://localhost:8050

### Configuration

Set your preferred defaults in `.env`:
```bash
# Deployment mode (for reference only)
MODE=dev

# Single host entrypoint port
APP_PORT=8050

# HTTPS entrypoint port for self-signed TLS in dev
APP_TLS_PORT=8443
DEV_CERT_CN=localhost
DEV_CERT_SANS=DNS:localhost,IP:127.0.0.1,IP:::1

# Frontend allowed hosts (comma-separated)
VITE_ALLOWED_HOSTS=sasaprod,localhost,members.sasalliance.org
```

If you access via a LAN hostname or IP, add it to `VITE_ALLOWED_HOSTS`.
If you change `APP_PORT`, use that port instead of `8050` in URLs.
If you change `APP_TLS_PORT`, use that port for HTTPS URLs.
If you change hostnames, update `DEV_CERT_CN` and `DEV_CERT_SANS` accordingly.

### Stopping Services
```bash
# Stop all services
docker compose down

# Stop production profile services
docker compose --profile prod down
```

## Default Credentials

**Admin Account**:
- Email: `admin@swanseaairport.org`
- Password: `admin123`

⚠️ **IMPORTANT**: Change the admin password immediately after first login!

## API Endpoints

### Authentication
- `POST /api/v1/auth/register` - Register new user
- `POST /api/v1/auth/login` - Login (OAuth2 form)
- `POST /api/v1/auth/login-json` - Login (JSON)

### Users
- `GET /api/v1/users/me` - Get current user profile
- `PUT /api/v1/users/me` - Update current user profile
- `GET /api/v1/users/` - List all users (admin)
- `GET /api/v1/users/{id}` - Get user by ID (admin)
- `DELETE /api/v1/users/{id}` - Delete user (admin)

### Membership Tiers
- `GET /api/v1/tiers/` - List all tiers
- `GET /api/v1/tiers/{id}` - Get tier by ID
- `POST /api/v1/tiers/` - Create tier (admin)
- `PUT /api/v1/tiers/{id}` - Update tier (admin)
- `DELETE /api/v1/tiers/{id}` - Delete tier (admin)

### Memberships
- `GET /api/v1/memberships/my-memberships` - Get current user's memberships
- `POST /api/v1/memberships/` - Create membership
- `GET /api/v1/memberships/{id}` - Get membership by ID
- `PUT /api/v1/memberships/{id}` - Update membership (admin)
- `GET /api/v1/memberships/` - List all memberships (admin)
- `DELETE /api/v1/memberships/{id}` - Delete membership (admin)

### Payments
- `GET /api/v1/payments/my-payments` - Get current user's payments
- `POST /api/v1/payments/` - Create payment
- `GET /api/v1/payments/{id}` - Get payment by ID
- `PUT /api/v1/payments/{id}` - Update payment (admin)
- `GET /api/v1/payments/` - List all payments (admin)
- `POST /api/v1/payments/manual-payment` - Record manual payment (admin)

## Docker Compose Commands

### Basic Operations

```bash
# Start all services
docker compose up -d

# View logs (all services)
docker compose logs -f

# View logs (specific service)
docker compose logs -f backend
docker compose logs -f gateway

# Stop services
docker compose down

# Stop and remove volumes (clean slate)
docker compose down -v

# Restart services
docker compose restart

# Rebuild after code changes
docker compose up -d --build

# Check service status
docker compose ps
```

### Database Operations

```bash
# Access MySQL CLI (using environment variables)
docker exec -it membership_mysql mysql -u "${DATABASE_USER}" -p"${DATABASE_PASSWORD}" "${DATABASE_NAME}"

# Create backup
docker exec membership_mysql mysqldump -u "${DATABASE_USER}" -p"${DATABASE_PASSWORD}" "${DATABASE_NAME}" > backup_$(date +%Y%m%d_%H%M%S).sql

# Restore database
docker exec -i membership_mysql mysql -u "${DATABASE_USER}" -p"${DATABASE_PASSWORD}" "${DATABASE_NAME}" < backup.sql
```

### Database Migrations

The application uses Alembic for database schema migrations. Migrations are automatically run when the backend container starts.

```bash
# Create a new migration (after making model changes)
sudo docker compose exec backend alembic revision --autogenerate -m "Description of changes"

# Apply migrations
sudo docker compose exec backend alembic upgrade head

# View migration status
sudo docker compose exec backend alembic current

# View migration history
sudo docker compose exec backend alembic history
```

**Note**: The `database/init.sql` file is deprecated. All schema changes should now be made through Alembic migrations.

## API Testing

You can use the interactive API documentation at http://localhost:8050/docs to test endpoints:

1. Register a new user
2. Login to get access token
3. Click "Authorize" button and enter: `Bearer <your_token>`
4. Test protected endpoints

Or use curl:

```bash
# Register
curl -X POST "http://localhost:8050/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123",
    "first_name": "John",
    "last_name": "Doe"
  }'

# Login
curl -X POST "http://localhost:8050/api/v1/auth/login-json" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123"
  }'

# Get profile (replace TOKEN with actual token)
curl -X GET "http://localhost:8050/api/v1/users/me" \
  -H "Authorization: Bearer TOKEN"
```

## Default Membership Tiers

The system comes with three pre-configured tiers:

1. **Personal** - £5/year
   - Access to member portal
   - Meeting notifications
   - Event participation

2. **Aircraft Owners** - £25/year
   - All Personal benefits
   - Priority event registration
   - Aircraft owner resources

3. **Corporate** - £100/year
   - All benefits
   - Corporate recognition
   - Promotional opportunities
   - File access

## Security

- Passwords are hashed using bcrypt
- JWT tokens for authentication
- Role-based access control (Member, Admin, Super Admin)
- CORS protection
- Environment-based configuration

## Troubleshooting

### Services not starting
```bash
# Check status of all services
docker compose ps

# View all logs
docker compose logs

# View specific service logs
docker compose logs gateway
docker compose logs backend

# Restart all services
docker compose restart

# Full restart with rebuild
docker compose down
docker compose up -d --build
```

### Database connection issues
```bash
# Check backend connectivity and status
docker compose ps

# View backend logs for DB errors
docker compose logs backend
```

### Clean slate restart
```bash
# Stop everything and remove volumes
docker compose down -v

# Start fresh
docker compose up -d

# Wait for initialization
docker compose logs -f
```

## Next Steps

- [ ] Implement Square payment integration
- [ ] Add email notification system
- [ ] Create event management endpoints
- [ ] Add volunteer management features
- [ ] Build frontend interface
- [ ] Add file upload/management
- [ ] Implement automated renewal reminders
- [ ] Add reporting and analytics

## License

Copyright © 2024 Swansea Airport Stakeholders' Alliance

## Support

For issues or questions, please contact the development team.