STACK IT FAST
ALL RULES & SKILLS

Laravel + Livewire + PostgreSQL

Raw .MD laravel-livewire-postgres
CURATED RULE AGENTS.MD + CLAUDE.MD + .MDC + SKILL.MD

Production guidelines for Laravel 11 monoliths, Livewire reactive components, Eloquent ORM query discipline, and queued job workers.

Laravel Livewire PHP PostgreSQL Alpine.js Tailwind CSS
CLI & AI Agent Import Verified in 2 production projects
AGENTS.md
Paste in your project root
SKILL.md
Installs to .claude/skills/laravel-livewire-postgres
INTERACTIVE RULE & SKILL VIEWER (AGENTS.MD, CLAUDE.MD, .MDC & SKILL.MD)
Optimized for:CursorClaude CodeWindsurfAGY
AGENTS.md·38 lines · 3.5 KB
1# Project Architecture & Guidelines (Laravel + Livewire + PostgreSQL)
2
3## 1. System Architecture
4- **Framework**: Laravel 11 (PHP 8.3+), server-rendered monolith with Livewire for reactive UI components without a separate JS frontend build.
5- **Database & ORM**: PostgreSQL with Eloquent ORM; migrations in `database/migrations/`. Coolify (below) self-hosts its own Postgres because it's a self-hosted PaaS by design — for a typical Laravel app, a managed provider (Supabase, Neon, or your cloud's RDS) is usually the easier default unless you specifically want to self-host.
6- **Interactivity**: Livewire components (`app/Livewire/`) for dynamic UI; Alpine.js for lightweight client-side behavior Livewire doesn't cover.
7- **Styling**: Tailwind CSS compiled via Vite.
8
9## 2. Eloquent Query Discipline (Critical N+1 Prevention)
10- Always eager-load relationships accessed in a loop or a Blade/Livewire view: `Project::with('owner', 'tags')->get()`, never `Project::all()` followed by `$project->owner` inside a `@foreach`.
11- Enable `Model::preventLazyLoading()` in `AppServiceProvider::boot()` for local/testing environments so N+1 queries throw instead of silently degrading production performance.
12- Use query scopes (`scopeActive()`, `scopePublished()`) on models instead of repeating `->where(...)` chains across controllers and Livewire components.
13
14## 3. Livewire Component Conventions
15- One Livewire component per cohesive UI concern (e.g. `ProjectTable`, `ProjectForm`) — avoid a single mega-component handling an entire page.
16- Validate all public properties with Laravel's `#[Validate]` attribute or `rules()` method before persisting; never trust a Livewire property bound via `wire:model` without server-side validation.
17- Use `wire:loading` and `wire:target` for loading states instead of hand-rolled JavaScript spinners.
18
19## 4. Queued Jobs & Background Work
20- Anything that calls an external API, sends email, or processes a file goes through a queued Job (`php artisan make:job`), never inline in a controller or Livewire action.
21- Configure a real queue driver (`database` for small deployments, Redis for higher throughput) — never `sync` in production.
22- Run `php artisan queue:work` under a process supervisor (Supervisor, systemd, or Laravel Horizon for Redis queues) so failed workers restart automatically.
23
24## 5. Common Pitfalls / Coding Standards
25- ❌ Running Eloquent queries inside Blade templates or Livewire render methods without eager loading.
26- ❌ Trusting `wire:model`-bound properties without server-side validation rules.
27- ✅ Use Form Request classes (`php artisan make:request`) for controller-level validation to keep controllers thin.
28
29## 6. Testing Conventions
30- Pest (or PHPUnit) for feature tests covering controllers, Livewire components (`Livewire::test(...)`), and queued jobs.
31- Use Laravel's `RefreshDatabase` trait with a dedicated test PostgreSQL database — never SQLite-in-memory for tests if production runs PostgreSQL, since dialect differences (JSON operators, array types) can hide bugs.
32- Run `php artisan test --parallel` in CI for faster feedback on larger suites.
33
34## 7. Git Workflow & PR Conventions
35- Conventional Commits scoped to the module, e.g. `fix(livewire/project-form): validate slug uniqueness`.
36- Migrations ship in the same PR as the model/schema change they support; never edit a migration that has already run in a shared environment — add a new one.
37- Require `php artisan test`, `phpstan analyse` (or Larastan), and `npm run build` green before merge.
38- Squash-merge; run `php artisan migrate` as a deploy step, never manually against production.
ARCHITECTURE NOTES & IMPLEMENTATION GUIDE
Export as Markdown

Architecture Overview

Standardized production guidelines for Laravel 11, Livewire, and PostgreSQL — a server-rendered PHP monolith pattern that avoids a separate frontend build for most CRUD-heavy applications.

Verified Real-World Adoption

Coolify, a self-hosted PaaS for deploying applications and databases, is built on exactly this stack: Laravel + Livewire + Alpine.js + Tailwind CSS + PostgreSQL, run inside Docker.

Key Architectural Nuances

  • N+1 Prevention as a First-Class Concern: Model::preventLazyLoading() turns silent N+1 query degradation into a loud local exception, catching the single most common Eloquent performance bug before it reaches production.
  • Queues as the Default for Side Effects: Any external call (email, webhook, file processing) is expected to go through a queued Job rather than execute inline, keeping request/response cycles fast and retryable on failure.
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 Livewire instead of a separate React/Vue frontend?

Livewire lets a Laravel monolith ship reactive, dynamically-updating UI while keeping all state and logic in PHP on the server — no separate API layer, no client-server type duplication, and no second build pipeline. It trades some client-side interactivity ceiling for a much simpler architecture, which fits most CRUD-heavy SaaS and admin tools well.

Why does PHP/Laravel appear as its own stack instead of folded into the "Ruby / PHP" survey option?

Rails and Laravel solve the same class of problem (server-rendered monolith, batteries-included ORM, background job queue) but have distinct enough conventions -- Eloquent vs ActiveRecord, Livewire vs Hotwire, Artisan vs Rails generators -- that a single AGENTS.md covering both would blur the guidance. This rule is the Laravel-specific counterpart to the Rails + PostgreSQL + Redis rule.

MORE AI AGENT CODING RULES & SKILLS
View All Rules & Skills
4 FILE FORMATS Django, Python

Django + PostgreSQL + Redis + Celery

Production guidelines for Django 5 enterprise applications, PostgreSQL connection pooling, Redis caching, and Celery async workers.

6 techs Copy Rules
4 FILE FORMATS FastAPI, Python

FastAPI + Python + PostgreSQL (Async SQLAlchemy & Pydantic v2)

Production guidelines for FastAPI, Pydantic v2 validation, Async SQLAlchemy 2.0 (asyncpg), Alembic migrations, and PostgreSQL/Redis.

7 techs Copy Rules
4 FILE FORMATS Go, Echo

Go + Echo + SQLite (Embedded, Self-Hosted Tools)

Architecture guidelines for single-binary Go services using the Echo framework, embedded SQLite, and minimal-JS server-rendered UI.

4 techs Copy Rules
4 FILE FORMATS NestJS, Node.js

NestJS + PostgreSQL + Redis + BullMQ

Enterprise backend architecture guidelines for NestJS modular design, PostgreSQL connection pooling, Redis BullMQ background jobs, and DTO validation.

6 techs Copy Rules