STACK IT FAST
ALL RULES & SKILLS

Elixir + Phoenix LiveView + PostgreSQL

Raw .MD phoenix-liveview-postgres
CURATED RULE AGENTS.MD + CLAUDE.MD + .MDC + SKILL.MD

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

AGENTS.md
Paste in your project root
SKILL.md
Installs to .claude/skills/phoenix-liveview-postgres
INTERACTIVE RULE & SKILL VIEWER (AGENTS.MD, CLAUDE.MD, .MDC & SKILL.MD)
Optimized for:CursorClaude CodeWindsurfAGY
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.7+ 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.
ARCHITECTURE NOTES & IMPLEMENTATION GUIDE
Export as Markdown

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.

MORE AI AGENT CODING RULES & SKILLS
View All Rules & Skills