Skip to content
STACK IT FAST
Share

Elixir + Phoenix LiveView + PostgreSQL

Curated rule SaaS / Web App · Collaboration & Productivity Updated Oct 2026 Which file does my tool read?
phoenix-liveview-postgres.md

Real-time reactive web architecture for Elixir 1.20, Phoenix 1.8+, LiveView HTML-over-WebSockets, OTP supervision trees, and Ecto.

Elixir Phoenix LiveView PostgreSQL Ecto Tailwind CSS
Formats
4 files
AGENTS.md
42 lines
CLAUDE.md
17 lines
Languages
Elixir
Updated
Oct 2026
Used by
2 projects
Install

Writes .claude/skills/phoenix-liveview-postgres/SKILL.md

$ curl -s --create-dirs -o .claude/skills/phoenix-liveview-postgres/SKILL.md https://stackitfast.com/rules/phoenix-liveview-postgres/SKILL.md

Rule files

AGENTS.md· 42 lines · 3.1 KB
1# Project Architecture & Guidelines (Elixir + Phoenix LiveView + PostgreSQL)
2
3## 1. System Architecture
4- **Platform & Language**: Erlang/BEAM runtime with Elixir (v1.17+).
5- **Web Framework**: Phoenix 1.8+ with Phoenix LiveView for reactive, zero-bundle real-time interfaces.
6- **Database & Persistence**: PostgreSQL accessed via Ecto (`Ecto.Repo`, `Ecto.Changeset`).
7- **Real-Time Communication**: Phoenix Channels & PubSub over persistent WebSockets.
8
9## 2. Directory & Application Structure
10- `lib/my_app/`: Core business logic domains, Ecto schemas, and context modules (e.g. `Accounts`, `Catalog`).
11- `lib/my_app_web/`: Web layer containing:
12 - `live/`: LiveView modules (`*_live.ex`) paired with colocated HEEx templates or `render/1` functions.
13 - `components/`: Reusable function components (`core_components.ex`) using Tailwind CSS.
14 - `controllers/`: REST and webhook fallback endpoints.
15- `priv/repo/migrations/`: Sequential Ecto database migrations.
16
17## 3. LiveView State & Event Lifecycle
18- Handle initial page loads via `mount/3`, checking `connected?(socket)` before establishing heavy background subscriptions.
19- Manage user interactions in `handle_event/3` and asynchronous process messages in `handle_info/2`.
20- Use `assign/2` and `assign_async/3` to update socket state reactively; avoid accumulating unbounded lists in memory without LiveView Streams (`stream/3`).
21
22## 4. Ecto & Data Integrity
23- Encapsulate all database mutations inside Context modules; never query `Repo` directly from LiveView templates.
24- Validate business constraints through dedicated `Changeset` functions with descriptive validation errors.
25- Wrap multi-table operations in `Ecto.Multi` transactions for atomic rollbacks on failure.
26
27## 5. Fault Tolerance & OTP Concurrency
28- Design supervision trees (`Application.start/2`) to isolate crashing worker processes from critical web connections.
29- Broadcast real-time changes using `Phoenix.PubSub.broadcast/3` to notify active LiveViews across distributed nodes.
30- Enforce English-only documentation, `@doc` attributes, and `@spec` type specifications on all public context functions.
31
32## 6. Testing Conventions
33- Use `ExUnit` with `Phoenix.LiveViewTest` (`live/2`, `render_click/2`, `render_submit/2`) to test LiveView interactions without a browser.
34- Test Context modules independently of LiveView — a Context function should be testable with plain `ExUnit.Case`, no web layer required.
35- Use `Ecto.Adapters.SQL.Sandbox` in async mode for isolated, parallel test transactions that roll back automatically.
36- Run `mix test --cover` in CI; Context modules and Changesets should carry the highest coverage since they own data integrity.
37
38## 7. Git Workflow & PR Conventions
39- Conventional Commits (`feat:`, `fix:`, `refactor:`) scoped to the context or LiveView, e.g. `fix(accounts): validate email uniqueness case-insensitively`.
40- Ecto migrations ship in the same PR as the schema/Changeset change that requires them.
41- Require `mix test`, `mix format --check-formatted`, and `mix credo --strict` green before merge.
42- Squash-merge; run `mix ecto.migrate` in CI against a throwaway database to catch migration errors before deploy.

Works with Cursor · Claude Code · Windsurf · AGY

Architecture notes

Architecture Overview

Standardized production guidelines for Elixir, Phoenix LiveView, and PostgreSQL.

Key Advantages

  • Zero JavaScript Overhead: LiveView computes differential DOM diffs on the server and pushes minimal binary payloads over WebSockets.
  • BEAM Fault Tolerance: Erlang’s battle-tested actor model isolates failure so individual user crashes never take down the system.
  • Instant Real-Time Sync: Built-in Phoenix PubSub coordinates live updates across millions of concurrent users with negligible CPU footprint.

Frequently asked questions

Does this AGENTS.md work with Cursor, Claude Code, and Windsurf?

Yes — AGENTS.md is the open, cross-tool standard read by Cursor, Claude Code, Windsurf, and 30+ other agents. A dedicated .mdc file is also included for Cursor's native .cursor/rules format.

Why check connected?(socket) inside mount/3?

Phoenix LiveView calls mount/3 twice: once during the initial static HTTP render (disconnected, for fast first paint and SEO), and again after the WebSocket connection is established. Subscribing to PubSub topics or starting expensive processes during the disconnected pass wastes work that gets thrown away, so that setup should only happen once connected?(socket) is true.

Why use Ecto.Multi instead of a plain database transaction?

Ecto.Multi composes a sequence of named operations — inserts, updates, function calls — into a single atomic transaction with clear, inspectable steps and per-step error attribution. A raw Repo.transaction/1 with imperative code inside makes it much harder to tell which specific operation failed when a multi-step mutation rolls back.

Used in production

Explore all stacks

ElectricSQL

Local-First Sync Engine · 6-20 People

Postgres logical replication and shape-based HTTP sync live in a dedicated Elixir OTP service so any TypeScript, React, or Elixir client can subscribe to partial replicas without each client re-implementing replication.

Plausible Analytics

Privacy Web Analytics · 2-5 people

Pairing the BEAM virtual machine with ClickHouse allows Plausible to ingest high-volume telemetry surges reliably with minimal RAM and fast analytical queries.
Every stack ships as files

More AI agent coding rules and skills

View all
django-postgres-redis/AGENTS.mdDjango + PostgreSQL + Redis + CeleryDjango · Python · PostgreSQLfastapi-python-postgres/AGENTS.mdFastAPI + Python + PostgreSQL (Async SQLAlchemy & Pydantic v2)FastAPI · Python · PostgreSQLnestjs-postgres-redis/AGENTS.mdNestJS + PostgreSQL + Redis + BullMQNestJS · Node.js · TypeScriptnextjs-ai-sdk-jev/AGENTS.mdNext.js + Vercel AI SDK + Jev (System One + LLM)Next.js · React · TypeScript