## 1. Architectural Separation (The "Laravel Way/Code of Conduct")

- **Thin Controllers, Thick Services:** Controllers must only handle request reception, delegation, and response delivery. All business logic must reside in dedicated.
- **Encapsulated Validation:** Never execute complex validation logic within a controller body. You must use **Form Requests** (`php artisan make:request`) to encapsulate input validation rules and incoming authorization handshakes before hitting application logic.
- **Eloquent Domain Isolation:** Interact with the persistence layer exclusively through **Eloquent ORM** or the **Query Builder**. Raw SQL is banned unless explicitly required for micro-optimization of complex analytical queries. Never modify schemas outside of isolated database migrations.

## 3. Frontend Integration Stack (Vue.js + Inertia.js + Tailwind CSS)

- **Lean Payload Serialization:** Use `Inertia::render()` to dispatch data to Vue components. You must explicitly serialize or transform models (via Eloquent API Resources) to send only the exact fields required by the UI view layer. Do not leak internal system hashes or unneeded database columns.
- **Design System Continuity:** Implement pixel-perfect components conforming to the established UI/UX framework. Prioritize clean, modern styling utilizing organic shapes, large corner radii, and designated glassmorphic overlays where specified.
- **Utility-First Styling Cleanliness:** Rely cleanly on standard Tailwind utility classes. Do not embed inline CSS styles or arbitrary arbitrary-value brackets (e.g., `h-[432px]`) unless rendering a highly dynamic, runtime-calculated layout metric.

## 4. Resilient Asynchronous Queue Management

- **Offload IO-Bound Operations:** Heavy or time-consuming computations—including outbound mail delivery, third-party API dispatches, batch notifications, or bulk file processing (such as CSV voter/user registration imports)—must be offloaded to background **Queue Jobs**.
- **Idempotency & Fail-Safes:** Background jobs must be entirely idempotent. Design them to be safely retried multiple times without generating duplicate side effects, split-state anomalies, or corrupted records. Always define explicit `$tries`, backoff strategies, and robust exception handling.
- ask me...

## 5. Pragmatic Design Patterns & Clean Code (Anti-Overengineering)

- **Design Pattern Justification:** Leverage proven software design patterns (e.g., Factory, Strategy, Repository, or State) **only** when they explicitly resolve structural complexity, eliminate duplication, or manage polymorphic logic cleanly. If standard Laravel features or standard object-oriented patterns solve the problem elegantly, do not add unnecessary abstractions. Avoid over-engineering.
- **Readability & Maintainability:** Code must be written for human developers to read first and machines to execute second. Adhere strictly to SOLID principles, keep methods highly focused, and name variables/methods transparently according to their domain purpose.
- **Avoid Premature Optimization:** Do not build complex abstraction architectures for features that "might" happen in the future. Implement the cleanest, most maintainable solution for the immediate requirement while keeping the system open for extension.

## 6. Defensive Code Quality & Enterprise Type Safety

- **Strict Typing Compulsory:** Every custom PHP file must declare strict typing at the absolute top of the script: `declare(strict_types=1);`. Always enforce explicit primitive/object argument types and explicit return type hints across all functions, service layers, and architectural patterns.
- **Regression-Free Test Coverage:** Run the existing PHPUnit or Pest test suite before and after introducing modifications. Every new business rule, service abstraction, or routing endpoint must be covered by comprehensive unit or feature tests replicating both happy paths and boundary failures.

## Note: if you have any doubt or confusion or you have batter ideas about any implementation, just ask me...

## Always update docs after changing feature/business.