PHX SaaS Starter

A production-grade Phoenix SaaS starter: multi-tenant organisations with roles, invites and activity logs; Stripe subscription billing; an admin hub (users, analytics, bulk email, error log, telemetry); Mailgun transactional email with prebuilt templates; Oban background jobs; user onboarding; and 32 DaisyUI themes. Standard Phoenix conventions throughout — contexts, generators, LiveView — so the codebase reads like the official guides.

🚀 Quick start

Prerequisites

Elixir >= 1.15 / Erlang OTP >= 26
PostgreSQL >= 15
Node.js (for the Tailwind/DaisyUI asset pipeline; mix setup installs the npm packages for you)

Setup

Environment: copy envs/.env.example to envs/.env.dev (and envs/.env.test for the test suite). Dev boots with the placeholder values; fill in Stripe/Mailgun/Google keys when you want those integrations live. All secrets load at runtime — nothing is compiled in.
Install and run:
```
mix setup          # deps, DB create+migrate+seed, npm install, assets
mix phx.server
```
Visit http://localhost:4000. Override ports with PORT (HTTP) and DB_HOST/DB_PORT (PostgreSQL).
Seeded logins (dev): admin@phxsaas.com / somePassword132! (admin), plus a second admin admin2@phxsaas.com.

Test suite

mix test           # DB_PORT=5433 mix test if your Postgres runs elsewhere

🔑 What’s included

Area	Where	Notes
Auth	`lib/phx_saas/accounts`	phx.gen.auth conventions + Google OAuth (Ueberauth)
Organisations	`lib/phx_saas/organizations`	Multi-tenant workspaces, roles, invites, activity logs, real-time updates
Billing	`lib/phx_saas/stripe_helpers.ex`, pricing components	Stripe checkout + webhooks for the subscription lifecycle (Pro/Enterprise price IDs via env)
Admin hub	`/admin`	User management, analytics, bulk email, email templates, telemetry, error log
Email	`lib/phx_saas/mailer.ex`, `lib/phx_saas_web/email_templates`	Mailgun (runtime-configured), prebuilt confirmation/reset/update templates; test mode writes to a local sink
Jobs	Oban	Configured queues; see `config/config.exs`
Onboarding	dashboard first-run	Name capture + workspace auto-creation
Theming	DaisyUI	32 themes, theme picker component

⚙️ Configuration

Everything secret or environment-specific is read at runtime from envs/.env.{dev,test} (via Dotenvy) or real environment variables in production — see envs/.env.example for the full list (SAAS_NAME, DOMAIN, Stripe keys/price IDs, Mailgun, Google OAuth).

Production deploys follow standard Phoenix releases (mix release); set the same variables in your platform’s secret store.

🤖 AI-readiness

AGENTS.md (mirrored by CLAUDE.md) documents commands, architecture, boundaries, and prohibited shortcuts for AI coding agents, and .mcp.json.example shows an MCP configuration without secrets.

📚 Project docs

CHANGELOG.md — release history
docs/RELEASE-NOTES-OVERHAUL.md — honest scope and known limitations
SECURITY.md, SUPPORT.md, LICENSE — policies and licence

PHX SaaS Starter README