# 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:**
```bash
cd backend
bun install
cp .env.example .env  # Configure DB connection
bunx prisma migrate dev
bun run dev
```

**Frontend:**
```bash
cd frontend
bun install
cp .env.example .env  # Configure API URL
bun run dev
```

**Full Stack (Docker):**
```bash
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