[App Name] · Phoenix LiveView

A LiveView app. Server-rendered HTML over WebSocket. Realtime updates without a JS framework.

Source of truth

Production runs as a Phoenix release on Fly.io (BEAM clusters across Fly regions). Postgres in the same primary region with read replicas elsewhere. The Phoenix release tarball is canonical.

Tech stack

Elixir 1.18 + Phoenix 1.8 + LiveView 1.0 + Phoenix.PubSub for cross-process messaging. Ecto + Postgres. Tailwind v4 (built via esbuild + tailwind ports). Oban for background jobs. ExUnit for tests. Deployed via Fly's Elixir launcher.

Deploy

fly deploy from local. Releases are built via mix release inside the Fly builder. Postgres on Fly.

File map

• lib/myapp/ business domain (Ecto schemas, contexts)
• lib/myapp_web/ web layer (LiveView modules, controllers, components)
• lib/myapp_web/live/ LiveView modules, one per major surface
• lib/myapp_web/components/ reusable function components
• lib/myapp/repo.ex Ecto repo
• lib/myapp/application.ex supervision tree (PubSub, Repo, Endpoint, Oban)
• priv/repo/migrations/ Ecto migrations
• assets/ Tailwind + esbuild entrypoints
• mix.exs deps + release config
• fly.toml

.env keys

• DATABASE_URL
• SECRET_KEY_BASE (generate with mix phx.gen.secret)
• PHX_HOST your prod hostname
• POOL_SIZE Ecto pool, default 10

Hard rules

• Business logic in contexts, NOT in LiveView modules. LiveView is the UI layer.
• assign everything you read in the template into socket.assigns. NEVER read from sockets implicitly.
• For lists with thousands of items, use streams (stream/4). Don't put 10k items into assigns.
• Phoenix.PubSub for any cross-LiveView communication. Don't hand-roll Channels.
• Migrations are reversible (up AND down). Tested with mix ecto.rollback.
• Use Oban for anything async. Don't Task.start in handlers; restarts will leak.

Recent significant changes

• 2026-05-13: Scaffolded. Locked: LiveView 1.0 (stable now), Oban over Quantum (better persistence), Fly over Render (BEAM clustering across regions matters).

Next session: start here

1. mix phx.new myapp --live to scaffold (or apply this CLAUDE.md over an existing scaffold).
2. Create the first context with mix phx.gen.live. Run it, click around.
3. Set up Tailwind v4 via the tailwind mix task.
4. Add Oban. Define one worker. Confirm it processes.
5. fly launch + fly deploy. Confirm /live heartbeat survives a deploy.