# `audit_logs` — Platform Audit Trail

**Module:** Audit / System  
**Soft Delete:** No (immutable; append-only)

---

## Purpose

Platform-wide immutable event log. Records all significant actions by any actor type for security, compliance, and debugging. Soft (non-enforced) foreign keys allow logs to survive actor or entity deletion.

---

## Columns

| Column | Type | Nullable | Default | Description |
|--------|------|----------|---------|-------------|
| `id` | `BIGINT UNSIGNED AUTO_INCREMENT` | No | — | Sequential for ordering |
| `actor_type` | `VARCHAR(20)` | No | — | `super_admin \| couple \| crew \| guest \| system` |
| `actor_id` | `BIGINT UNSIGNED` | Yes | NULL | Soft reference to `users.id` — NOT enforced FK |
| `actor_display_name` | `VARCHAR(100)` | Yes | NULL | Snapshot of actor name at event time |
| `workspace_id` | `BIGINT UNSIGNED` | Yes | NULL | Soft reference. NULL for platform-level events |
| `action_category` | `VARCHAR(20)` | No | — | `authentication \| system \| business \| checkin \| configuration \| support \| data_change` |
| `action_type` | `VARCHAR(60)` | No | — | Machine-readable event code: `guest.imported`, `checkin.qr` |
| `target_entity_type` | `VARCHAR(30)` | Yes | NULL | `guest \| vendor \| workspace \| invitation \| checkin` |
| `target_entity_id` | `BIGINT UNSIGNED` | Yes | NULL | Soft reference to affected entity |
| `before_state` | `JSON` | Yes | NULL | Entity state snapshot before action |
| `after_state` | `JSON` | Yes | NULL | Entity state snapshot after action |
| `ip_address` | `VARCHAR(45)` | Yes | NULL | Request origin IP |
| `session_id` | `BIGINT UNSIGNED` | Yes | NULL | Soft reference → `sessions.id` |
| `occurred_at` | `DATETIME` | No | `CURRENT_TIMESTAMP` | UTC event timestamp. Immutable |

---

## Primary Key / Indexes

| Name | Columns | Type |
|------|---------|------|
| `PRIMARY` | `id` | Primary |
| `idx_audit_logs_workspace` | `workspace_id, occurred_at` | Index |
| `idx_audit_logs_action_type` | `action_type, occurred_at` | Index |
| `idx_audit_logs_actor` | `actor_id, occurred_at` | Index |

---

## Foreign Keys

**None enforced.** All references are soft (non-FK) to ensure logs survive the deletion of referenced entities.

---

## Business Rules

- Records are **never deleted or updated** — append-only
- All foreign-key-like columns are stored as plain values (soft references)
- `actor_display_name` is a snapshot — preserves the name even if the user is renamed/deleted
- `before_state` / `after_state` store JSON snapshots for field-level change tracking
- `occurred_at` is the authoritative UTC timestamp — never modified

---

## Notes

- This table will grow large over time — archival/partitioning strategy should be planned for DX003+
- `session_id` is stored for correlation with the `sessions` table, but not FK-enforced