# FreshCloud Mail — deploy protocol (2026-07-18)

How `avidtech6/freshcloud-mail` (the MIT-licensed PHP IMAP/SMTP bridge)
ends up running at `https://oscar-platform.freshvibeapps.com/api/email/*`.

## The chain

```
[Local sandbox]
  /workspace/oscar-platform/vendor/freshcloud-mail/   ← git clone
                         ↓
                  git push (we don't do this — the repo IS its own source of truth)
                         ↓
[GitHub]
  avidtech6/freshcloud-mail (private, MIT)
                         ↓
                  git pull or rsync (on VPS)
                         ↓
[VPS at /var/www/freshvibeapps/clients/_vendors/freshcloud-mail/]
                         ↓
                  symlink
                         ↓
[VPS at /var/www/freshvibeapps/clients/oscar-platform/api/email/]
                         ↓
                  nginx PHP-FPM routing
                         ↓
[https://oscar-platform.freshvibeapps.com/api/email/*]
```

## Why this layering

1. **`avidtech6/freshcloud-mail`** is the canonical source of the API.
   It's MIT-licensed, app-agnostic, can be pulled into any PHP app.
2. **Oscar's `vendor/freshcloud-mail/`** is a development convenience —
   Mavis can edit the API here and `git push` to the canonical repo
   when ready. Not used for production (no push to a private repo from
   a deploy script).
3. **`/var/www/freshvibeapps/clients/_vendors/freshcloud-mail/`** on VPS
   is the deployed source. Updated by the deploy script.
4. **Oscar's `api/email/`** is a symlink to the vendor location.
   `oscar-platform.freshvibeapps.com/api/email/health` is the same code
   as the canonical repo.

## Deploy script (the only command you need)

```bash
bash /workspace/oscar-platform/pact/scripts/deploy-freshcloud-mail.sh
```

The script:
1. Reads the GitHub token from `$GITHUB_PAT_FG_1` or `$GITHUB_TOKEN`
2. Clones `avidtech6/freshcloud-mail` to `/var/www/freshvibeapps/clients/_vendors/freshcloud-mail/`
   (uses `--depth 1` for speed; not a rebase target)
3. Sets `www-data:www-data` ownership
4. Confirms the symlink `/var/www/freshvibeapps/clients/oscar-platform/api/email` exists
5. Tests the endpoint with `curl /api/email/health`

## Where the canonical source lives

- **Repo**: `https://github.com/avidtech6/freshcloud-mail` (private, MIT)
- **Local sandbox**: `/workspace/freshcloud-mail/` (Mavis's working dir)
- **Local Oscar vendor**: `/workspace/oscar-platform/vendor/freshcloud-mail/`
  (git clone of the canonical repo)
- **VPS deploy**: `/var/www/freshvibeapps/clients/_vendors/freshcloud-mail/`
- **VPS symlink**: `/var/www/freshvibeapps/clients/oscar-platform/api/email`

## When to update the canonical repo

- Bug fix in any of the 5 PHP files
- New endpoint added
- Vendor change (e.g. swap MailSo for a different IMAP lib)

Workflow:
1. Edit in `/workspace/freshcloud-mail/` (or `vendor/freshcloud-mail/`)
2. Test in Oscar (the symlink means local changes are live on VPS after a deploy)
3. `git -C /workspace/freshcloud-mail add . && commit -m "..." && push`
4. Re-run the deploy script on VPS
5. Verify with `curl https://oscar-platform.freshvibeapps.com/api/email/health`

## Future: other apps

When another app (e.g. a school deployment of Oscar) wants email:
1. Clone `avidtech6/freshcloud-mail` into its own vendor/
2. Symlink the same way
3. Same MailSo library path
4. Same nginx vhost pattern
5. Done — same endpoints, same JSON, different app