sasa-membership/QUICKSTART.md

# Quick Start Guide

## Starting the System

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

# Watch the logs until services are ready
docker compose logs -f
```

Wait until you see "Application startup complete", then press Ctrl+C.

**Access the API**:
- API: http://localhost:8050/api/v1
- Docs: http://localhost:8050/docs

API datetimes are stored and returned in UTC/Zulu. The frontend shows member-facing times in Europe/London and converts event input back to UTC before saving.

Set `APP_PORT` in `.env` / `.env.example` to change `8050`.
For Square payment form testing, use HTTPS at `https://localhost:8443`.
Set `APP_TLS_PORT` in `.env` / `.env.example` to change `8443`.
TLS certs are auto-generated by the gateway container on first start.

## Restart With Tests

Use the restart helper when you want to rebuild, run the fast test suite, and restart only after tests pass:

```bash
./restart.sh
```

It runs:
- `docker compose run --rm frontend npm test`
- `docker compose run --rm backend pytest -q`

The current tests cover frontend profile-question visibility/editability rules and backend profile-question answer normalization/validation. They are designed to complete quickly.

## Testing the API

### 1. Register a new user
```bash
curl -X POST "http://localhost:8050/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "testpass123",
    "first_name": "Test",
    "last_name": "User"
  }'
```

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

Save the `access_token` from the response.

### 3. Get your profile
```bash
curl -X GET "http://localhost:8050/api/v1/users/me" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
```

### 4. List membership tiers
```bash
curl -X GET "http://localhost:8050/api/v1/tiers/"
```

## Docker Compose Commands

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

# Stop services
docker compose down

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

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

# Restart services
docker compose restart

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

# Check status
docker compose ps

# Tail gateway logs
docker compose logs -f gateway
```

## Default Admin Access

- **Email**: admin@swanseaairport.org
- **Password**: admin123

⚠️ Change this password immediately!

## Common Tasks

### Create a membership tier (admin)
1. Login as admin
2. Use the token in the Authorization header
3. POST to `/api/v1/tiers/`

### Record a manual payment (admin)
1. Login as admin
2. POST to `/api/v1/payments/manual-payment`

### View all users (admin)
1. Login as admin
2. GET `/api/v1/users/`

### Manage profile questions (admin)
1. Login as admin or super admin
2. Open the dashboard Admin area
3. Create, edit, deactivate, and order configurable profile questions
4. Use dependencies to show questions only after a matching parent answer

### Edit member profile answers
1. Members can update normal profile questions from the Questions dashboard tab
2. Admin-only answers, such as verified training fields, must be updated by an admin

### Manage events and RSVPs
1. Admins can create and edit events from the dashboard
2. Members can view upcoming events and submit RSVP status
3. Admins can view RSVP lists and attendance data

### ESP RFID readers
1. Readers register with `/api/v1/esp/device/register`
2. Readers sync clocks from `/api/v1/esp/device/time`
3. Tap, heartbeat, and write-job timestamps are UTC-normalized in the backend
4. Admins can review readers, taps, attendance, and card-write jobs from the ESP screens

### Manage email templates and bounces
1. Super admins can edit database-backed email templates; previews are shown as escaped HTML text
2. SMTP2GO bounce webhooks are stored and visible in bounce management
3. Bounce cleanup and manual deactivation are available through the API/admin screens

## Troubleshooting

### Check service status
```bash
docker compose ps
```

### View all logs
```bash
docker compose logs -f
```

### View backend logs only
```bash
docker compose logs -f backend
```

### Restart everything
```bash
docker compose restart
```

### Clean start (removes all data)
```bash
docker compose down -v
docker compose up -d
```

## Next Steps

1. Update `.env` with your Square and SMTP2GO credentials
2. Change the default admin password
3. Create additional admin users
4. Configure membership tiers as needed
5. Test payment processing
6. Customize email templates
7. Configure profile questions for onboarding and volunteer data
8. Use `./restart.sh` before deploying changes so frontend and backend unit tests run first