ca-grow-ops-manager/specs/compliance-and-docs.md

Feature Spec: Compliance and Documentation

Domain: Compliance
Status: Draft
Version: 0.1.0
Last Updated: 2025-12-08

---

Overview

The Compliance and Documentation module helps California cannabis cultivation facilities maintain audit-ready records for DCC (Department of Cannabis Control) compliance. It tracks key compliance-adjacent records (taxes, utilities, invoices, payroll references), provides compliance views by month/quarter, and generates "audit packet" exports. METRC remains the system of record for track-and-trace; this module supports adjacent recordkeeping.

---

User Stories

As a Compliance Manager

• I want to upload and categorize compliance documents (PDFs, images) so they're organized and searchable
• I want to see a monthly/quarterly compliance checklist so I know what's missing
• I want to generate an audit packet (ZIP with all docs and indexes) so I'm ready for inspections
• I want to track METRC tag mappings for batches so I can cross-reference with the state system

As an Owner

• I want to see compliance status at a glance so I know we're audit-ready
• I want to delegate compliance tasks to the Compliance Manager
• I want to ensure all financial records (taxes, invoices, payroll) are properly documented

As an Accountant

• I want to upload invoices and bills with structured metadata so they're easy to find
• I want to export compliance records for tax preparation

---

Requirements

Functional Requirements

Document Management

• Document types:
  • Monthly taxes (excise, sales, cultivation)
  • Utility bills (SMUD, PG&E, water, gas)
  • Rent/lease agreements
  • CO₂ and greenhouse supply invoices
  • Nutrient and material invoices
  • Bills of sale
  • Payroll summaries (references only, not full payroll data)
  • Hours tracking exports (from Labor module)
  • Licenses and permits
  • Inspection reports
  • SOPs (Standard Operating Procedures)
• Document upload:
  • Drag-and-drop or file picker
  • PDF, image (JPG, PNG), and CSV supported
  • Automatic OCR for searchability (future enhancement)
• Structured metadata:
  • Document type
  • Date (invoice date, bill date, etc.)
  • Vendor/supplier
  • Amount (if applicable)
  • Period covered (month/quarter)
  • Tags (custom labels)
  • Notes

Compliance Views

• Monthly view:
  • Checklist of required documents for the month
  • Status: complete, missing, pending
  • Quick upload for missing items
• Quarterly view:
  • Aggregated checklist for the quarter
  • DCC-aligned categories
• Annual view:
  • Year-end compliance summary
  • License renewal reminders

Audit Packet Generation

• Export format: ZIP file containing:
  • All documents for the selected period
  • CSV index with metadata (filename, type, date, vendor, amount)
  • JSON index for programmatic access
  • README with export details
• Filters:
  • By date range
  • By document type
  • By vendor
• Encryption (optional): Password-protected ZIP

METRC Tag Mapping

• Batch-to-METRC mapping:
  • Store METRC tag IDs for each batch
  • Display mapping in batch detail view
  • Export mapping as CSV
• Read-only in v1: No direct METRC sync

Non-Functional Requirements

• Security: Documents encrypted at rest
• Access control: Only Compliance Manager and Owner can view/edit
• Audit trail: All document uploads and deletions logged
• Performance: Document list loads in < 1 second
• Storage: Configurable retention policy (e.g., 7 years for tax records)

---

Out of Scope (v1)

• Direct METRC integration (read/write)
• Automated compliance alerts based on METRC data
• OCR and automatic metadata extraction
• E-signature for documents
• Integration with accounting systems (QuickBooks, Xero)

---

Acceptance Criteria

Document Management

• Compliance Manager can upload documents with metadata
• Documents are categorized by type
• Documents can be searched by metadata (type, date, vendor)
• Documents can be previewed in-app (PDF, images)
• Documents can be downloaded individually

Compliance Views

• Monthly view displays checklist of required documents
• Missing documents are highlighted
• Quick upload button for missing documents
• Quarterly and annual views aggregate monthly data

Audit Packet

• Audit packet can be generated for a date range
• ZIP contains all documents and indexes (CSV, JSON)
• Export includes README with metadata
• Password protection is optional

METRC Mapping

• METRC tags can be associated with batches
• Mapping is displayed in batch detail view
• Mapping can be exported as CSV

Audit Trail

• All document uploads are logged with user and timestamp
• All document deletions are logged (soft delete)
• Audit log is exportable

---

Technical Notes

Data Model (Prisma Schema)

model ComplianceDocument {
  id          String   @id @default(cuid())
  type        DocumentType
  filename    String
  url         String   // S3 or local storage
  date        DateTime // invoice date, bill date, etc.
  vendor      String?
  amount      Float?
  period      String?  // "2025-01" for January 2025
  tags        String[] // custom labels
  notes       String?
  uploadedBy  String
  user        User     @relation(fields: [uploadedBy], references: [id])
  deletedAt   DateTime? // soft delete
  deletedBy   String?
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
}

enum DocumentType {
  TAX_MONTHLY
  UTILITY_BILL
  RENT_LEASE
  CO2_INVOICE
  NUTRIENT_INVOICE
  BILL_OF_SALE
  PAYROLL_SUMMARY
  HOURS_EXPORT
  LICENSE_PERMIT
  INSPECTION_REPORT
  SOP
  OTHER
}

model AuditLog {
  id          String   @id @default(cuid())
  action      String   // "upload", "delete", "edit"
  entityType  String   // "ComplianceDocument", "Batch", etc.
  entityId    String
  userId      String
  user        User     @relation(fields: [userId], references: [id])
  metadata    Json?    // additional context
  createdAt   DateTime @default(now())
}

API Endpoints

• GET /api/compliance/documents - List documents with filters
• GET /api/compliance/documents/:id - Get document detail
• POST /api/compliance/documents - Upload document
• PATCH /api/compliance/documents/:id - Update document metadata
• DELETE /api/compliance/documents/:id - Soft delete document
• GET /api/compliance/documents/:id/download - Download document
• GET /api/compliance/checklist/:period - Get compliance checklist for period
• POST /api/compliance/audit-packet - Generate audit packet
• GET /api/compliance/metrc-mapping - Get METRC tag mappings
• GET /api/compliance/audit-log - Get audit log

UI Components

• DocumentUploader - Drag-and-drop upload with metadata form
• DocumentList - Filterable list of documents
• DocumentPreview - In-app PDF/image viewer
• ComplianceChecklist - Monthly/quarterly checklist view
• AuditPacketGenerator - Export interface with filters
• MetrcMappingTable - Batch-to-METRC tag mapping
• AuditLogViewer - Audit trail display

---

Dependencies

• Batches and Rooms module (for METRC mapping)
• Labor module (for payroll/hours exports)
• Authentication (for RBAC and audit trail)

---

Risks & Mitigations

Risk	Impact	Mitigation
Document storage costs	Medium	Configurable retention policy; compression
Missing documents at audit time	High	Proactive checklists; monthly reminders
METRC mapping errors	High	Clear UI; validation; read-only in v1
Data breach (sensitive financial docs)	High	Encryption at rest; strict access control; audit trail

---

Compliance Notes (California DCC)

Key Recordkeeping Requirements

Per California DCC regulations, licensed cannabis businesses must maintain:

• Financial records: Invoices, receipts, bank statements, tax filings (7 years)
• Inventory records: METRC is the system of record; internal records must align
• Labor records: Hours, wages, payroll (4 years minimum)
• Licenses and permits: Current and historical
• Inspection reports: All DCC and local inspections
• SOPs: Current versions and change history

Audit Preparation

• Quarterly self-audits recommended
• Audit packet should include:
  • All financial records for the period
  • METRC reconciliation reports
  • Labor and payroll summaries
  • Licenses and permits
  • Inspection reports
  • SOPs

Resources

• California DCC Regulations
• METRC California Guide
• DCC Compliance Checklist

---

Future Enhancements (Post-v1)

• OCR and automatic metadata extraction
• METRC integration (read/write with user confirmation)
• Automated compliance alerts (e.g., "Missing utility bill for March")
• E-signature for SOPs and inspection reports
• Integration with accounting systems (QuickBooks, Xero)
• Automated tax filing reminders