# Events & triggers — internal maintenance reference

**Audience:** BharatamVinyas dev, support, implementation  
**Full spec:** [02-events-and-triggers-maintenance.md](../../tech/02-events-and-triggers-maintenance.md)

---

## Why this doc exists

BvProperty uses **three layers** for events — not MySQL triggers for business logic:

| Layer | Maintain for |
|-------|----------------|
| `MessagingGatewayService` | Resident/guard SMS, email, push, in-app |
| `automation_rules` + `AutomationEngineService` | Society-specific if-then rules |
| Minimal MySQL triggers | Posted GL immutability, audit only |

---

## Minimum set to keep working (release checklist)

### Messaging — 14 P0/P1 events

`visitor.pending_approval`, `visitor.approved`, `visitor.checked_in`, `visitor.overstay`, `safety.sos`, `helpdesk.ticket.created`, `helpdesk.ticket.resolved`, `invoice.issued`, `billing.reminder`, `recovery.notice_sent`, `notice.published`, `amenity.booking.confirmed`, `amenity.booking.reminder`, `parking.pass.issued`

Config: `apps/cloud/config/messaging.php` → `event_module_map`

### Automation triggers (all wired in code)

| Trigger | Service |
|---------|---------|
| `helpdesk.ticket.created` | `HelpdeskService` |
| `helpdesk.ticket.resolved` | `HelpdeskService` |
| `invoice.issued` | `SocietyBillingService` |
| `recovery.notice_sent` | `FinanceRecoveryService` |
| `notice.published` | `NoticeService` |
| `visitor.approved` | `VisitorService` |
| `visitor.overstay` | `VisitorOverstayMonitorService` |
| `payment.received` | `PaymentGatewayService` |
| `amenity.booking.confirmed` | `AmenityService` |

Society UI presets: `AutomationRuleResource` → Trigger dropdown.

### MySQL — keep small

- `gl_journal_entries` / `payments` — block edit when posted/settled
- Optional row audit on tickets/invoices
- **Do not** add SMS/workflow triggers in MySQL

---

## Key code paths

| File | Role |
|------|------|
| `config/messaging.php` | Event → module map |
| `AutomationEngineService.php` | Rule execution |
| `MessagingGatewayService.php` | Channel dispatch |
| `MessagingEventWireSeeder.php` | Demo templates + sample rules |

---

## Training links

| Audience | Doc |
|----------|-----|
| MC admin (automation screen) | [09-configuration](../client/modules/09-configuration-and-dashboard.md) |
| Gate messaging | [36-messaging-gate-pass](../../tech/36-messaging-gate-pass.md) |
| Platform architecture | [01-database-and-platform](../../tech/01-database-and-platform-architecture.md) §5 |