← All templates

Contexts as boundaries, LiveView for UI state, every process supervised.

Constitution — Phoenix LiveView app

Version 1.0.0 · Ratified 2026-11-10

These principles hold for every spec, plan and task of the project. A spec may add rules; it never weakens these.

  1. Contexts as boundaries. Business logic lives in context modules (Accounts, Billing) with a public API. LiveViews, controllers and other contexts call those functions and never use Repo or another context’s schemas directly.

  2. LiveView for UI state. Interactive UI state lives in LiveView assigns and is changed only in handle_event and handle_info. Custom JavaScript is limited to hooks for what LiveView cannot do and is named in the plan.

  3. Every process supervised. Long-lived processes (GenServers, Tasks, Oban queues) start under a supervisor in the application tree. A bare spawn or an unsupervised Task.start fails the review.

  4. Changesets validate every write. Every insert and update goes through an Ecto changeset with cast, validations and constraints. Raw maps are never written, and multi-step writes use Ecto.Multi in one transaction.

  5. Preload and stream. Associations rendered in a view are preloaded in the context query, and long lists use LiveView streams instead of keeping every row in assigns.

  6. Authorized on mount. Every LiveView checks the current user in an on_mount hook and re-checks permissions in each handle_event that changes data. A hidden button is not access control.

  7. Tests at both levels. Contexts have ExUnit tests with the SQL sandbox, and each LiveView has tests with Phoenix.LiveViewTest driving its events. Credo and mix format --check-formatted pass in CI.