Module 12: Audit & Compliance

⛔ SUPERSEDED 2026-06-11 — Sprig-era feature spec (pre-pivot). The authoritative current design is the locked schema in docs/SCHEMA.md, the module's entry in docs/PROJECT_DECISIONS.md, and the responsibility/seam maps in docs/MODULE_INDEX.md + docs/CROSS_MODULE_CONTRACTS.md. This file is retained for historical feature context only; do NOT treat its scope/table/feature claims as current (it predates the nursery→generic pivot, the HR-out-of-scope cut, the identity/payments/integrations/files extractions, and the schema locks). Superseded note added 2026-06-11.

Status: ✅ Locked for v1.0 Schema: audit Feature count: 108 features in v1.0 Build estimate: Strategic spec only — implementation effort TBD Last updated: 2026-05-12

Overview

Audit & Compliance is the cross-cutting "everything is logged and we can prove it" module. It owns the immutable audit log, snapshot history, compliance reporting, data subject rights (GDPR/CCPA), encryption verification, data breach management, and compliance task tracking. The module captures events from every other module and provides query/export capabilities for compliance, regulatory, and forensic scenarios.

Audit & Compliance is primarily a consumer module — it subscribes to events from every other module and provides query, search, and export capabilities. It also emits its own events (incidents, breaches, integrity violations).

The module supports retail nursery compliance needs (state tax, federal labor law, pesticide records where applicable), modern data privacy frameworks (GDPR, CCPA), and standard B2B SaaS requirements (PCI compliance through Stripe tokenization, SOC 2 Type II readiness for Enterprise customers in year 2).

Target Customer Profile

• Mid-size growth-stage retail nursery, $500K–$5M revenue
• Mix of W-2 employees and 1099 contractors
• May handle credit card data via Stripe (PCI compliance through tokenization)
• Customers include some California residents (CCPA) and some European tourists (GDPR consideration)
• Annual financial audit by external accountant
• Possible insurance/regulatory inspections

Architecture Principles

Immutable audit log

Audit log entries are append-only, never deleted, and cryptographically hash-chained to detect tampering. Retention is configurable but minimum 7 years for financial records.

Tenant isolation

Each tenant's audit data is isolated via tenant_id (with RLS at database level). No cross-tenant audit queries are possible from the application layer.

Configurability

Every threshold, default, retention period, and granularity setting is configurable per tenant via the Owner Dashboard (Module 10).

Tier Behavior

Tier	Audit & Compliance capability
Starter	Basic audit log; 30-day retention; manual exports
Pro	Full audit log; 7-year retention; PCI status; CCPA/GDPR rights; compliance reports
Enterprise	All Pro + SOC 2 readiness reports + advanced encryption verification + custom retention + audit API access + dedicated compliance dashboard

Feature Hierarchy (108 features across 15 groups)

Group 1: Audit Log Foundation (10 features)

#	Feature	Notes
1.1	Immutable audit log table	Append-only enforced by Postgres trigger blocking UPDATE/DELETE; never deleted; tamper-evident. v1.0 external attestation: weekly signed export to R2 (tenant-specific key); v2.0 upgrade to R2 Object Lock for SOC 2. See ARCHITECTURE.md "Audit Architecture".
1.2	Audit log entry schema	actor (user_id), action, resource, timestamp, ip, device, before/after state
1.3	Audit log capture from all modules	Every module emits events that become audit entries
1.4	Audit log retention	7 years default (configurable)
1.5	Audit log search	Full-text + structured search across all entries
1.6	Audit log filtering	By actor, action type, resource, date range, IP
1.7	Audit log granularity setting	All actions / sensitive only / minimal — per tenant
1.8	Audit log integrity verification	Cryptographic hash chain to detect tampering. Per-row hash chain: SHA-256(previous_row_hash || row_payload). Daily verification job. See ARCHITECTURE.md "Audit Architecture".
1.9	PII masking in audit logs	Mask sensitive customer data in log entries to reduce compliance burden
1.10	Audit log integrity check schedule	Daily/weekly automated verification of hash chain integrity

Group 2: User Activity & Access Audit (10 features)

#	Feature	Notes
2.1	Login attempts log	Success/failure, IP, device
2.2	Session activity tracking	When user logged in, what they accessed
2.3	Permission change audit	Who changed whose permissions
2.4	Role assignment audit	Role changes tracked
2.5	Privileged action audit	Admin, manager, payroll actions logged
2.6	Failed authentication audit	Lockouts, suspicious patterns
2.7	Session impersonation audit	Vrida support accessing tenant (if happens)
2.8	API key usage audit	Per-key activity tracking (Enterprise)
2.9	Webhook delivery audit	Successful and failed webhook attempts
2.10	User self-deletion audit	When user requests own account deletion

Group 3: Financial Audit (8 features)

#	Feature	Notes
3.1	Sale audit trail	Complete sale history with all modifications
3.2	Refund audit trail	Why refunded, by whom, when
3.3	Void / cancellation audit	Sale voids, order cancellations
3.4	Cash drawer variance audit	Variances over time per cashier
3.5	Tender modification audit	Changes to payment method on transactions
3.6	Discount audit trail	All discounts applied, by whom, reason
3.7	Cash drop / payout audit	Movement of cash to/from drawer
3.8	Bank deposit reconciliation audit	Cash to deposit matched to deposits made

Group 4: Inventory Audit (8 features)

#	Feature	Notes
4.1	Inventory adjustment audit	Every qty change, reason, actor
4.2	Dead count / shrinkage audit	What was written off, why
4.3	Stock movement audit	All movements between zones, sites
4.4	Inventory snapshot history	Daily snapshots; 7-year retention
4.5	Inventory valuation audit	Cost basis changes over time
4.6	Variant master data audit	Changes to plant master records
4.7	Receiving audit	All goods received, by whom, when
4.8	Inventory transfer audit	Inter-site transfers with full trail

Group 5: Customer Data Audit (15 features)

#	Feature	Notes
5.1	Customer record changes audit	All edits, who, when, before/after
5.2	Customer access audit	Who viewed customer PII, when
5.3	GDPR data export requests	All exports tracked, completed when
5.4	GDPR data deletion requests	Deletion requests with timestamps
5.5	Customer consent changes audit	Marketing opt-in/out history
5.6	Customer charge account audit	Credit limit changes, holds
5.7	Tax exemption certificate audit	Cert additions, expirations, applications to sales
5.8	Customer merge audit	When duplicates were merged
5.9	Customer deletion audit	When customer record was deleted (soft or hard)
5.10	Customer data sharing audit	When customer data shared with third parties
5.11	Right to rectification	Customer requests correction; staff updates; audit captured
5.12	Right to restriction of processing	Customer requests data processing be paused, not deleted; workflow + audit
5.13	Right to object to processing	Customer objects to marketing, profiling, or specific data use; workflow + audit
5.14	Subject Access Request (SAR) workflow	Structured GDPR/CCPA request handling — receipt → review → response within deadline
5.15	Data subject consent versioning	Track which version of privacy policy / TOS customer consented to

Group 6: System Configuration Audit (8 features)

#	Feature	Notes
6.1	Tenant settings changes audit	Every setting change in Owner Dashboard
6.2	Tier / subscription changes audit	Upgrades, downgrades, cancellations
6.3	User & role changes audit	Permissions, role assignments
6.4	Tax configuration audit	Tax rate changes, jurisdictions
6.5	Pricing changes audit	Variant price changes
6.6	Promotion & discount audit	Campaign creation, modifications
6.7	Integration setup audit	QuickBooks, Stripe, etc. connections
6.8	API key generation audit	Keys created, revoked

Group 7: Compliance Reporting (10 features)

#	Feature	Notes
7.1	PCI compliance status	Card data handling proof; tokenization status
7.2	PCI audit trail	All credit card-touching actions
7.3	GDPR compliance report	Customer rights actions, retention status
7.4	CCPA compliance report	California-specific privacy rights
7.5	SOC 2 readiness report	Control activity for SOC 2 audit (year-2)
7.6	State tax compliance reports	Per-jurisdiction tax records
7.7	Federal tax compliance reports	IRS-required records
7.8	Employment tax records	Per-employee tax-related documentation
7.9	Labor law compliance	Hours, breaks, overtime per employee
7.10	Industry-specific compliance	Pesticide records, USDA, plant import (where applicable)

Group 8: Audit Log Search & Investigation (8 features)

#	Feature	Notes
8.1	Time-based audit search	"What happened between dates X and Y"
8.2	Actor-based audit search	"What did User X do"
8.3	Resource-based audit search	"All changes to Customer Y"
8.4	Action-type audit search	"All refunds in past 30 days"
8.5	Pattern-based audit search	AI-assisted: "Show me unusual activity"
8.6	Audit drill-down	Click event → see related events
8.7	Audit visualization	Timeline view of activity
8.8	Audit context expansion	Show before/after state for changes

Group 9: Snapshot & Time-Travel (5 features)

#	Feature	Notes
9.1	Inventory snapshot UI	Visual time-travel through inventory state
9.2	Financial snapshot UI	Time-travel through financial state
9.3	Customer state snapshot UI	Historical customer record states
9.4	Snapshot comparison	Compare two points in time
9.5	Snapshot export	Download a snapshot for accountant/auditor

Group 10: Audit Export & Reporting (6 features)

#	Feature	Notes
10.1	Audit log export (CSV)	All filtered audit entries
10.2	Audit log export (PDF)	Formatted compliance report
10.3	Audit log API access	Programmatic query (Enterprise)
10.4	Audit log scheduled exports	Auto-export weekly/monthly to external storage
10.5	Compliance package export	"All records for IRS audit period" — bundled export
10.6	Audit log search-and-export	Search results exported

Group 11: Incident Response & Forensics (5 features)

#	Feature	Notes
11.1	Suspicious activity detection	AI flags patterns
11.2	Security incident reporting	Tenant reports breach/issue
11.3	Incident audit trail	All actions during incident captured
11.4	Forensic data preservation	Locking audit logs during incident
11.5	External investigator access	Read-only audit access for forensics

Group 12: Compliance Documentation (7 features)

#	Feature	Notes
12.1	Compliance certifications display	PCI, SOC 2, GDPR, etc. visible to tenants
12.2	Compliance documentation library	Vrida's compliance docs available to tenants
12.3	Tenant compliance documentation	Tenant's own compliance docs (insurance, licenses, etc.) — covered in Module 10
12.4	Compliance status dashboard	Visual status of tenant compliance posture
12.5	Compliance breach alerts	Auto-alert on potential compliance violations
12.6	Subprocessor list	List of Vrida's data processors (Stripe, AWS, Twilio, etc.) — required by GDPR
12.7	Data Processing Agreement (DPA) management	Tenant-Vrida DPA tracking, version history, signatures

Group 13: Data Breach Management (2 features)

#	Feature	Notes
13.1	Data breach notification workflow	Structured process: detection → assessment → notification (regulators, affected users) within legal deadlines
13.2	Data breach risk classification	Critical / High / Medium / Low — drives notification urgency and depth

Group 14: Encryption & Data Security Audit (4 features)

#	Feature	Notes
14.1	Encryption at rest verification	Audit that database data is encrypted; ongoing verification
14.2	Encryption in transit verification	TLS audit for all data transmission
14.3	Key management audit	Encryption keys: rotation, access, audit trail
14.4	Sensitive data detection	Auto-flag PII, financial data in unexpected places; warning before unintended exposure

Group 15: Compliance Task & Calendar (2 features)

#	Feature	Notes
15.1	Compliance task management	"Tax filing due", "SAR response", "Cert renewal" — structured task list
15.2	Compliance task deadlines	Alerting with escalation if approaching/past deadline

Configurable Defaults (Owner Dashboard)

Configurable	Default
Audit log retention	7 years (retained in archived form even after tenant cancellation; see PROJECT_DECISIONS Tenant Lifecycle)
Audit log granularity	All actions logged
Audit log access	Owner + Manager only
Audit log export schedule	OFF (manual)
Snapshot frequency	Daily
Snapshot retention	7 years (matches audit)
Incident response workflow enabled	ON
Compliance dashboard enabled	ON
Auto-archive old audit data	OFF (keep all 7 years)
Tamper-evident hash chain	ON (always)
GDPR compliance enabled	ON (per region)
CCPA compliance enabled	ON (California)
PCI compliance enabled	ON (always for card-handling)
SOC 2 readiness reports	ON if Enterprise tier
Industry-specific compliance reports	OFF (configurable per tenant region)
PII masking in audit logs	ON for non-sensitive review; OFF for forensics
Audit log integrity check frequency	Daily
Subject Access Request workflow enabled	ON (GDPR/CCPA required)
Data breach notification deadline	72 hours (GDPR standard)
Compliance task notifications	ON (Pro+); SMS+email
Encryption verification check frequency	Weekly
Sensitive data detection sensitivity	Medium (configurable: low/medium/high)

AI Features in Audit & Compliance

Feature #	AI capability
8.5	AI pattern-based audit search ("show me unusual activity")
11.1	AI suspicious activity detection
7.10	AI industry-specific compliance suggestions
8.7	AI audit context expansion
14.4	AI sensitive data detection (auto-flag PII)
13.2	AI breach risk classification
15.1	AI compliance task prioritization

All AI features use AWS Bedrock with Claude Haiku 4.5.

Events Emitted

• audit.log_entry_created
• audit.log_entry_searched
• audit.log_exported
• audit.log_retention_expired
• audit.snapshot_taken
• audit.snapshot_accessed
• audit.incident_reported
• audit.incident_resolved
• audit.compliance_report_generated
• audit.tamper_attempt_detected
• audit.api_audit_export
• audit.integrity_check_completed
• audit.integrity_violation_detected
• audit.gdpr_rectification_requested
• audit.gdpr_restriction_requested
• audit.gdpr_objection_received
• audit.sar_received
• audit.sar_completed
• audit.consent_version_recorded
• audit.encryption_verification_completed
• audit.encryption_violation_detected
• audit.sensitive_data_detected
• audit.data_breach_reported
• audit.data_breach_notified_regulator
• audit.data_breach_notified_users
• audit.compliance_task_created
• audit.compliance_task_due
• audit.compliance_task_overdue
• audit.compliance_task_completed

Event isolation: Per CROSS_MODULE_CONTRACTS.md Rule 7, audit.* events are internal to the Audit module. No operational module subscribes to audit.* events. This prevents event cycles.

Events Consumed

Audit consumes events from EVERY other module — that's its purpose:

• All *.created, *.updated, *.deleted events
• Login events from Admin
• Sale/refund events from POS
• Customer changes from CRM
• Stock movements from Inventory
• Etc.

API Contract (AuditService — public methods)

High-level surface (detailed signatures during implementation):

• Audit log: searchAuditLog, exportAuditLog, getAuditEntry, getAuditContext, verifyIntegrity, maskPII
• User & access: getUserActivity, getLoginHistory, getPermissionChanges
• Financial: getSaleAudit, getRefundAudit, getCashAudit
• Inventory: getInventoryAudit, getStockMovement, getDeadCountAudit
• Customer rights: handleRectificationRequest, handleRestrictionRequest, handleObjectionRequest, handleSAR, recordConsentVersion
• Compliance: generateComplianceReport, getComplianceStatus, manageDPA, getSubprocessorList
• Snapshots: getSnapshot, compareSnapshots, exportSnapshot
• Incident: reportIncident, classifyBreach, notifyRegulators, notifyUsers
• Encryption: verifyEncryptionAtRest, verifyEncryptionInTransit, getKeyAudit, detectSensitiveData
• Compliance task: createComplianceTask, getDueTasks, escalateTask, prioritizeTask

Out of Scope

Capability	Why excluded
External audit firm integration	Out of scope; export-based collaboration
Continuous compliance monitoring (automated SOC 2)	Future v2.0+
SOC 2 Type II audit automation	Manual via auditor; we provide records
Penetration testing automation	Out of scope (security audit)
Continuous penetration scanning	Out of scope
Regulatory rule changes auto-update	Out of scope; manual updates
External attestation services	Out of scope
Real-time compliance violation auto-prevention	Future v2.0
Cookie consent management	Out of scope (web only)
Privacy impact assessment	Out of scope (internal Vrida process)
Cross-border data transfer compliance	Out of scope (US-only initially)
Data residency / jurisdiction enforcement	Out of scope (US-only initially)
Vendor security assessments	Out of scope (internal Vrida process)
Bug bounty integration	Out of scope
Vulnerability disclosure program	Out of scope