# Laravel + Livewire + PostgreSQL — AI Agent Guidelines & Architecture Rules

> Production guidelines for Laravel 11 monoliths, Livewire reactive components, Eloquent ORM query discipline, and queued job workers.
> Technologies: Laravel, Livewire, PHP, PostgreSQL, Alpine.js, Tailwind CSS

---

## AGENTS.md
```markdown
# Project Architecture & Guidelines (Laravel + Livewire + PostgreSQL)

## 1. System Architecture
- **Framework**: Laravel 11 (PHP 8.3+), server-rendered monolith with Livewire for reactive UI components without a separate JS frontend build.
- **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.
- **Interactivity**: Livewire components (`app/Livewire/`) for dynamic UI; Alpine.js for lightweight client-side behavior Livewire doesn't cover.
- **Styling**: Tailwind CSS compiled via Vite.

## 2. Eloquent Query Discipline (Critical N+1 Prevention)
- 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`.
- Enable `Model::preventLazyLoading()` in `AppServiceProvider::boot()` for local/testing environments so N+1 queries throw instead of silently degrading production performance.
- Use query scopes (`scopeActive()`, `scopePublished()`) on models instead of repeating `->where(...)` chains across controllers and Livewire components.

## 3. Livewire Component Conventions
- One Livewire component per cohesive UI concern (e.g. `ProjectTable`, `ProjectForm`) — avoid a single mega-component handling an entire page.
- 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.
- Use `wire:loading` and `wire:target` for loading states instead of hand-rolled JavaScript spinners.

## 4. Queued Jobs & Background Work
- 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.
- Configure a real queue driver (`database` for small deployments, Redis for higher throughput) — never `sync` in production.
- Run `php artisan queue:work` under a process supervisor (Supervisor, systemd, or Laravel Horizon for Redis queues) so failed workers restart automatically.

## 5. Common Pitfalls / Coding Standards
- ❌ Running Eloquent queries inside Blade templates or Livewire render methods without eager loading.
- ❌ Trusting `wire:model`-bound properties without server-side validation rules.
- ✅ Use Form Request classes (`php artisan make:request`) for controller-level validation to keep controllers thin.

## 6. Testing Conventions
- Pest (or PHPUnit) for feature tests covering controllers, Livewire components (`Livewire::test(...)`), and queued jobs.
- 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.
- Run `php artisan test --parallel` in CI for faster feedback on larger suites.

## 7. Git Workflow & PR Conventions
- Conventional Commits scoped to the module, e.g. `fix(livewire/project-form): validate slug uniqueness`.
- 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.
- Require `php artisan test`, `phpstan analyse` (or Larastan), and `npm run build` green before merge.
- Squash-merge; run `php artisan migrate` as a deploy step, never manually against production.
```

---

## CLAUDE.md
```markdown
# CLAUDE.md — Laravel + Livewire + PostgreSQL

Refer to @AGENTS.md for complete database configuration and architectural constraints.

## Common Commands
- `php artisan serve` - Start local Laravel development server
- `npm run dev` - Start Vite dev server for Tailwind/Alpine assets
- `php artisan migrate` - Apply pending database migrations
- `php artisan test` - Run the Pest/PHPUnit test suite
- `php artisan queue:work` - Start processing queued jobs locally

## Claude Specific Directives
- Always eager-load Eloquent relationships used in a loop; check for `Model::preventLazyLoading()` violations before finishing a change.
- Route external API calls, emails, and file processing through a queued Job, not inline controller code.
```

---

## .cursor/rules/stack.mdc
```markdown
---
description: Laravel + Livewire + PostgreSQL architecture rules
globs: ["**/*.php", "**/*.blade.php"]
alwaysApply: true
---

# Laravel + Livewire + PostgreSQL

- Laravel 11 monolith, Eloquent ORM over PostgreSQL, Livewire for reactive UI without a separate SPA build, Alpine.js for light client behavior.
- Always eager-load relationships (`->with(...)`) accessed in a loop or view — enable `preventLazyLoading()` locally to catch N+1s.
- Validate every public Livewire property server-side with `#[Validate]`/`rules()`; never trust `wire:model` bindings.
- Route external API calls, email, and file processing through queued Jobs; never `sync` queue driver in production.
- One Livewire component per UI concern; use query scopes on models instead of repeated `->where(...)` chains.
- Form Request classes for controller validation, keeping controllers thin.
- Migrations ship with their schema change; never edit a migration already run in a shared environment.
```

---

## Architecture Overview & Best Practices
## 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.