20 — Audit

Audit logging, compliance, tracking

CEO Summary

Audit is the compliance backbone. Every critical action (login, payment, config change, data access) is logged. Business value: Regulatory compliance, dispute resolution, security forensics. Key metrics: Audit coverage, retention, query performance. If this breaks: Compliance gaps; cannot trace who did what.

Architecture

flowchart TB subgraph sources [Event Sources] POS[pos finalize] Reg[register open/close] GC[giftcards] HR[HR services] Auth[auth] end subgraph api [API] AR[audit.routes] AL[auditLogger middleware] end subgraph svc [Service] AS[audit.service.js] end subgraph db [Tenant Analytics DB] Logs[(audit_logs)] end subgraph reports [Reporting] RS[reporting.service] BC[Business Center] end POS --> AS Reg --> AS GC --> AS HR --> AS Auth --> AL AL --> AS AR --> AS AS --> Logs RS --> AS AS --> BC

Overview

Audit logs every critical action. Stored in tenant analytics DB. Used by reporting, Business Center, compliance.

Base path: /api/audit
Auth: requireSessionAuth + tenantResolver on the router; each route uses requireScopes (audit:read or audit:write)
Storage: audit_logs table in tenant analytics DB
Taxonomy: GET /api/audit/taxonomy — vocabulary from auditTaxonomy.js

File Structure

backend/
├── routes/
│   └── audit.routes.js          # Record, logs, summaries, export
├── services/
│   └── audit.service.js        # AuditService class
├── middleware/
│   └── auditLogger.js          # Auto-attach to routes
└── models/
    └── auditEvent.model.js     # Legacy Sequelize (audit_logs raw)

API Endpoints

Method	Path	Scope	Purpose
GET	/api/audit/taxonomy	audit:read	Categories, eventTypes, entityTypes, filterPresets (from `auditTaxonomy.js`)
POST	/api/audit/record	audit:write	Record audit event
GET	/api/audit/logs	audit:read	Get audit logs with filters
GET	/api/audit/summary/event-type	audit:read	Summary by event type
GET	/api/audit/summary/user	audit:read	Summary by user
GET	/api/audit/security	audit:read	Security audit summary
GET	/api/audit/data-access	audit:read	Data access audit summary
GET	/api/audit/financial	audit:read	Financial audit summary
GET	/api/audit/compliance	audit:read	Compliance audit summary
POST	/api/audit/entity-trail	audit:write	Create entity audit trail
GET	/api/audit/export	audit:read	Export logs (JSON/CSV)

Audit Schema

Field	Purpose
eventType	create, update, delete, view, login, logout, payment, refund
entityType	user, customer, product, order, payment, inventory
entityId	Target entity ID
action	Action performed
performedBy	Actor ID
performedByType	user, system, api, admin
oldValues, newValues	JSON — before/after
severity	critical, error, warning, info, debug
category	authentication, authorization, data_access, configuration, financial, system, general
ipAddress, userAgent, deviceId, sessionId	Request context

Integration Points

System	Connection
POS	pos.routes — finalize AuditService.recordAuditEventWithTenantContext
Register	pos-register.routes — open/close register
Gift Cards	giftCard.service — giftcard.issue, giftcard.reload, giftcard.redeem
HR	employee.service, department.service, benefits.service — hr_audit_log
Reporting	reporting.service — getFinancialAuditSummary, getAuditSummaryByEventType
Business Center	Reports Hub — transaction audit

HR Audit (Separate)

HR services use hr_audit_log in the tenant main DB for employee, department, and benefits changes. See 10 — HR & Payroll.

Key Paths

Path	Purpose
`backend/routes/audit.routes.js`	Audit API
`backend/services/audit.service.js`	AuditService
`backend/constants/auditTaxonomy.js`	Categories, event/entity types, Admin filter presets
`backend/middleware/auditLogger.js`	Auto-attach middleware