ca-grow-ops-manager/.claude/claude.md

Project Overview

Name: Veridian Cultivation Platform Type: Full-stack SaaS application (backend + frontend) Primary Languages: TypeScript (Node.js 20, React 18) Status: v0.1.0, Internal Testing

High-Level Description

Veridian is a cultivation management platform for licensed cannabis facilities that centralizes:

• Grow Operations: Tasks, batches, rooms, and cultivation workflows
• Labor Tracking: Timeclock, hours, and cost-per-batch analysis
• Compliance: Document storage, audit packets, and METRC alignment
• Inventory: Materials, nutrients, and supplies with lot tracking
• Integrations: Environmental monitoring and hardware dashboards
• Communications: Task comments, announcements, and notifications

External Systems:

• PostgreSQL 15.x (primary database via Prisma ORM)
• METRC API (read-only in v1, California track-and-trace)
• SensorPush environmental sensors (via Veridian Edge agent)
• VPS deployment: nexus-vector

Multi-Repo Architecture

This repo works in conjunction with veridian-edge as a single codebase:

• veridian (this repo): Main platform backend + frontend
• veridian-edge: SensorPush edge agent that polls SensorPush Cloud API and syncs environmental readings to Veridian backend

When making changes, consider the API contract between these two repos:

• Edge agent → Veridian backend API endpoints
• Data models must match between edge agent and backend
• Authentication/authorization patterns

Layout

veridian/
├── backend/          # Express/Fastify backend API
│   ├── src/          # Source code
│   ├── prisma/       # Database schema and migrations
│   └── package.json  # Node.js dependencies
├── frontend/         # React + Vite frontend
│   ├── src/          # Source code
│   └── package.json  # Dependencies
├── docs/             # Architecture and compliance docs
├── specs/            # Feature specifications (Spec Kit workflow)
├── design-os/        # Design system components
└── docker-compose.yml # Local development stack

Conventions

Language/Style

• TypeScript strict mode enabled
• ESLint + Prettier for formatting
• Prisma 5.x for database access
• Conventional commits for git messages

Package Manager

• Use bun instead of npm by default
• Commands: bun install, bun run, bun test, bun add

Error Handling

• Throw semantic errors with clear messages
• Use Result types for operations that can fail
• Never expose sensitive data in error messages

Logging

• Use structured logging (JSON in production)
• No console.log in production code
• Log levels: error, warn, info, debug

Config

• Read from environment variables
• Never hard-code secrets or API keys
• Use .env.example as template

Patterns & Playbooks

How to Add New API Endpoints

1. Update Prisma schema if needed (prisma/schema.prisma)
2. Run migration: bunx prisma migrate dev --name description
3. Create route handler in backend/src/routes/
4. Add request validation (zod or similar)
5. Implement business logic in service layer
6. Add tests in backend/src/__tests__/
7. Update API documentation

How to Add New Frontend Components

1. Create component in frontend/src/components/
2. Follow existing design system patterns (see design-os/)
3. Use TypeScript with proper prop types
4. Add responsive styles (Tailwind CSS)
5. Create tests if component has logic
6. Export from component index file

How to Write Database Migrations

1. Modify backend/prisma/schema.prisma
2. Run bunx prisma migrate dev --name description
3. Generate client: bunx prisma generate
4. For production: bunx prisma migrate deploy

How to Run Locally

Backend:

cd backend
bun install
cp .env.example .env  # Configure DB connection
bunx prisma migrate dev
bun run dev

Frontend:

cd frontend
bun install
cp .env.example .env  # Configure API URL
bun run dev

Full Stack (Docker):

docker compose up -d

Important Environment Variables

• DATABASE_URL: PostgreSQL connection string
• JWT_SECRET: Secret for JWT token signing
• METRC_API_KEY: METRC integration (read-only)
• SENSORPUSH_WEBHOOK_SECRET: Webhook verification for edge agent

PR & Learning Workflow

• When a PR introduces a new pattern or fixes a subtle issue:
  1. Summarize the lesson in 1-2 bullets
  2. Append under "Patterns & Playbooks" above
  3. Consider updating relevant documentation in docs/

Testing Strategy

• Unit tests: Jest for pure functions and business logic
• Integration tests: API endpoint tests with test database
• E2E tests: Browser tests for critical flows (login, batch creation)
• VPS verification: After deployment, verify on nexus-vector

Compliance Notes

• METRC is system of record for California track-and-trace
• All compliance-relevant changes must be documented
• Audit logs must capture: who, what, when, for critical operations
• See docs/compliance-notes-ca.md for detailed guidance