# 20 — Audit

**Overhead and Operations**

---

## Overview

Tenant **audit logs** capture security-sensitive and operational events (auth, register shifts, POS actions, staff, catalogs, invoicing). Data lives in the **tenant analytics** database (`audit_logs`). The Admin UI and reporting surfaces consume **`GET /api/audit/logs`** and related summary endpoints.

**HTML chapter (browsable):** [20-audit.html](./20-audit.html)

---

## Canonical taxonomy

**Source of truth:** `backend/constants/auditTaxonomy.js`

- **`AUDIT_CATEGORIES`** — Must align with the `audit_logs.category` ENUM in `audit.service.js`: `authentication`, `authorization`, `data_access`, `configuration`, `financial`, `system`, `general`.
- **`AUDIT_EVENT_TYPES`** — Named constants for `eventType` values the app emits (e.g. `staff_created`, `register_open`, `pos_cart_recalc`, `login_success`). Legacy rows may still use older strings (e.g. `payment` with `action` describing finalize); new code should prefer this vocabulary.
- **`AUDIT_ENTITY_TYPES`** — Common `entityType` values: `staff`, `cart`, `register_shift`, `user`, `catalog`, `invoice`.
- **`AUDIT_FILTER_PRESETS`** — Presets for Admin audit filters (financial, staff, register, authentication, etc.).

**API:** `GET /api/audit/taxonomy` (`audit:read`) returns `{ categories, eventTypes, entityTypes, filterPresets }` for the UI and integrators.

---

## Routes and auth

**File:** `backend/routes/audit.routes.js`

- **Middleware:** `requireSessionAuth`, `tenantResolver`, then **`requireScopes`** per route (`audit:read` / `audit:write`).
- **Base path:** `/api/audit`

| Method | Path | Scope | Purpose |
|--------|------|-------|---------|
| GET | `/taxonomy` | audit:read | Categories, event/entity types, filter presets |
| POST | `/record` | audit:write | Record an audit event |
| GET | `/logs` | audit:read | Filtered log query |
| GET | `/summary/event-type` | audit:read | Summary by event type (requires date range) |
| GET | `/summary/user` | audit:read | Summary by user |
| GET | `/security` | audit:read | Security-oriented summary |
| GET | `/data-access` | audit:read | Data-access summary |
| GET | `/financial` | audit:read | Financial summary |
| GET | `/compliance` | audit:read | Compliance summary |
| POST | `/entity-trail` | audit:write | Entity audit trail |
| GET | `/export` | audit:read | Export (JSON/CSV) |

---

## Services and storage

- **`backend/services/audit.service.js`** — Creates `audit_logs` if missing; `recordAuditEventWithTenantContext`, queries, summaries.
- **`backend/middleware/auditLogger.js`** — Optional auto-logging on selected routes.
- **`backend/models/auditEvent.model.js`** — Legacy Sequelize model; primary storage is raw SQL against `audit_logs` in analytics DB.

**Typical row fields:** `eventType`, `entityType`, `entityId`, `action`, `performedBy`, `performedByType`, `oldValues` / `newValues` (JSON), `severity`, **`category`** (ENUM above), `ipAddress`, `userAgent`, `deviceId`, `sessionId`, `timestamp`, `orgId`, `tenantId`.

---

## Integration points

| Area | Connection |
|------|------------|
| POS | Finalize and related flows — `AuditService.recordAuditEventWithTenantContext` |
| Register | `pos-register.routes.js` — open/close/admin events (`register_open`, `register_close`, etc.) |
| Staff / platform users | User-management and staff APIs — staff and platform user lifecycle event types |
| Catalog | Catalog mutations — `catalog_*` event types |
| Invoicing | Void/refund — `void`, `refund` event types |
| Gift cards | `giftCard.service` — issue/reload/redeem style events |
| HR | Separate **`hr_audit_log`** in tenant main DB for HR entities — see [11 — HR & Payroll](./11-HR-AND-PAYROLL.md) |

---

## Frontend

- **`/admin/audit-logs`** — Audit log viewer (see [Appendix F](./APPENDIX-F-FRONTEND-ROUTE-TREE.md)).