// Field Guide — The Archive — entry 08

Join the Expedition

Issues and pull requests are welcome — this is early, pre-1.0 work, and the dashboard itself (the part you’d actually click around in) is still being built. The woods are big and there’s room at the campfire.

Before you start

Read the repo’s CLAUDE.md for the conventions this codebase holds itself to. The short version:

  • Boring code, bigfoot-flavored UI copy only. See the Glossary house rules.
  • Dependencies stay minimal: ecto_sql, phoenix / phoenix_live_view, plug, telemetry, aws + finch. No Ash, no ex_aws, no Bamboo. SNS signature verification is hand-written against :public_key — don’t reach for a dependency to do it.
  • All Ecto schemas live in the squatch_mail Postgres schema. Never assume public.
  • Schema changes ship as versioned migrations behind SquatchMail.Migrations — never a raw, unversioned migration.

Found a vulnerability instead of a bug? SECURITY.md, not a public issue.

Local development: three loops

You need Elixir 1.15+ and a Postgres to point at (connection settings honor the standard PGUSER / PGPASSWORD / PGHOST / PGPORT env vars). From fastest to most realistic:

1. The test suite

mix test

Creates and migrates its own squatch_mail_test database. Run it before sending a patch. Also keep mix format happy and mix compile warning-free — warnings get fixed, not papered over.

2. The dashboard preview

iex -S mix dev

Boots a minimal Phoenix endpoint with the dashboard at http://localhost:4000/squatch, backed by an auto-created squatch_mail_dev database. This is the fast loop for UI work — send emails through SquatchMailDev.Mailer and watch them flow through the capture pipeline. The header of dev.exs has a copy-paste snippet.

3. A real host app

For anything touching the installer, migrations, or host integration:

bin/setup_test_host
cd test_host
docker compose up --build

This scaffolds a throwaway Phoenix app (gitignored) that embeds SquatchMail as a path dependency pointing back at your checkout — so it doubles as a smoke test of the igniter installer against a stock app. Dashboard at /squatch, Swoosh’s local mailbox at /dev/mailbox. Your checkout is bind-mounted, so library changes are picked up on recompile.

No Docker? mix phx.server works against whatever Postgres your PG* vars point at. Delete test_host/ and re-run the script whenever you want a fresh campsite.

Sending the patch

  1. Fork, branch, make the change.
  2. mix format && mix test — both clean.
  3. If you touched schema or migrations, make sure it’s behind a new SquatchMail.Migrations version.
  4. Open the PR with a plain-English description. Field-journal flavor in the PR body is optional but appreciated.

Pack out what you pack in. Leave the codebase tidier than the clearing you found.