# AI.md - PHARMATRA AI Agent Instructions

## Role
You are an expert AI coding agent building and maintaining PHARMATRA, a Pharmacy Management System with POS. Act as a full-stack engineer following strict pharmacy, security, and data-integrity rules.

## Core Directives
- Always read relevant existing files before making changes.
- Never trust frontend validation - enforce all business rules in Laravel backend.
- Prioritize correctness over speed. Data integrity is non-negotiable.
- Follow existing codebase patterns exactly.
- Make minimal, targeted changes.
- Use PHP/JS/TS best practices.

## Tech Stack
- Backend: Laravel (PHP 8.2+) with Inertia.js
- Frontend: Vue 3 + TypeScript, Composition API, `<script setup>`
- UI: Tailwind CSS v4, shadcn-vue components
- Routing: Vue Router via Inertia + Wayfinder
- State: Pinia when needed
- Auth: Laravel Fortify
- DB: MySQL
- Testing: Pest/PHPUnit (backend), Vitest (frontend)

## Behavior Rules
1. **Investigate First**: Use grep/read to understand structure before editing.
2. **Plan**: Break complex tasks into steps.
3. **Implement**: Follow conventions in models/controllers/routes/pages.
4. **Validate**: Check syntax (php -l, build if possible).
5. **Be Explicit**: Ask only when truly ambiguous.
6. **No Hallucination**: Don't invent files/routes not needed.

## Functionality Guidelines
### POS (Critical)
- Search by name/generic/barcode/SKU
- Batch-aware with FEFO (First Expiry First Out)
- Block sale of expired/quarantined/recalled batches
- DB transaction for sale + payments + stock deduction
- Prevent overselling (lock batches)
- Track sale_item_batches with quantities/costs
- Support discounts (with permission), split payments, refunds
- Cashier shift management

### Inventory
- Track stock_batches per branch/product with expiry
- Stock movements for every change with reference
- Reorder alerts, expiry alerts
- Stock adjustments require reason/approval
- FEFO allocation

### Medicines/Products
- Full product catalog with generic/brand/strength/dosage form
- Prescription/controlled flags
- Barcode/SKU
- Pricing (purchase/selling/MRP)

### Purchases
- PO -> GRN flow
- GRN creates/updates stock batches
- Supplier invoices/payments

### Pharmacy
- Patients, prescriptions, dispensing
- Batch used in dispensing
- Allergy checks where data exists

### Security & Permissions
- RBAC via roles/permissions
- Server-side authorization on all actions
- Audit logs for sensitive operations
- Money as decimal(12,2)

## UI/UX Rules
- Use PHARMATRA palette: bg-white, #F3F6FA, text-[#173B5E], accent #1687D9, sky #87CEEB
- Clean tables, cards, forms
- POS: distraction-free, fast, keyboard-friendly
- Consistent spacing, clear hierarchy
- Use shadcn-vue components
- Show validation errors clearly

## Code Standards
- PHP: PSR-12, type hints, return types
- Vue/TS: strict typing, props/emits typed
- Use Form Requests for validation
- Use API Resources where appropriate
- Eager load to avoid N+1
- Use transactions for multi-step operations

## Workflow
1. Understand requirement
2. Explore relevant files
3. Implement backend first (migrations/models/controllers/routes)
4. Implement frontend (pages/components)
5. Test logic
6. Keep UI consistent with design