# Veridian

> A cultivation management platform for licensed facilities.

**Version**: 0.1.0  
**Status**: Internal Testing (Veridian)  
**Last Updated**: 2025-12-27

---

## Overview

**Veridian** reduces cognitive load for cultivation teams by centralizing:

- **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

The platform is **opinionated, simple to use on the floor, and safe for regulated environments**.

---

## Quick Links

- **Constitution**: [constitution.md](constitution.md) — Non-negotiable principles
- **Project Spec**: [spec.yml](spec.yml) — High-level overview
- **Architecture**: [docs/architecture.md](docs/architecture.md) — System design
- **Compliance Notes**: [docs/compliance-notes-ca.md](docs/compliance-notes-ca.md) — California DCC guidance

---

## Tech Stack

### Backend

- **Language**: TypeScript
- **Runtime**: Node.js 20.x
- **Framework**: Express or Fastify
- **Database**: PostgreSQL 15.x
- **ORM**: Prisma 5.x

### Frontend

- **Language**: TypeScript
- **Framework**: React 18.x
- **Build Tool**: Vite or Next.js
- **Components**: Radix UI or shadcn-style
- **Styling**: Tailwind CSS

### Mobile

- **Approach**: Web-first (tablet-optimized)
- **Stretch Goal**: React Native or Capacitor PWA

---

## Project Structure

```
ca-grow-ops-manager/
├── .specify/
│   └── memory/
│       └── constitution.md       # Full constitution (Spec Kit memory)
├── specs/                        # Feature specifications
│   ├── tasks-and-scheduling.md
│   ├── batches-and-rooms.md
│   ├── labor-and-hours.md
│   ├── compliance-and-docs.md
│   ├── inventory-and-materials.md
│   ├── integrations-and-hardware.md
│   └── communications-and-notifications.md
├── backend/                      # Backend application
│   └── README.md
├── frontend/                     # Frontend application
│   └── README.md
├── docs/                         # Documentation
│   ├── architecture.md
│   └── compliance-notes-ca.md
├── constitution.md               # Constitution summary
├── spec.yml                      # Project specification
└── README.md                     # This file
```

---

## Feature Specs

All feature specs are located in `specs/` and follow the Spec Kit template:

1. **[Tasks and Scheduling](specs/tasks-and-scheduling.md)**: Room-based task templates, calendar views, and "Today" view for on-shift workers
2. **[Batches and Rooms](specs/batches-and-rooms.md)**: Batch lifecycle management, METRC mapping, weight logging, and yield tracking
3. **[Labor and Hours](specs/labor-and-hours.md)**: Timeclock, wage rates, labor cost per batch, and payroll exports
4. **[Compliance and Documentation](specs/compliance-and-docs.md)**: Document storage, audit packets, and DCC-aligned checklists
5. **[Inventory and Materials](specs/inventory-and-materials.md)**: Materials tracking, lot/serial, restock alerts, and recall support
6. **[Integrations and Hardware](specs/integrations-and-hardware.md)**: Environmental dashboards, METRC connector (Phase 2), and hardware adapters
7. **[Communications and Notifications](specs/communications-and-notifications.md)**: Task comments, @mentions, daily digests, and announcements

---

## Spec Kit Workflow

This project follows the **GitHub Spec Kit** workflow:

1. **Spec** → Write feature specs in `specs/`
2. **Plan** → Create implementation plans
3. **Tasks** → Define concrete, actionable tasks
4. **Implement** → Build, test, and deploy

### Spec Kit Commands (Placeholder)

```bash
# Generate implementation plan from spec
/speckit.plan specs/tasks-and-scheduling.md

# Generate tasks from plan
/speckit.tasks plans/tasks-and-scheduling-plan.md

# Implement tasks
/speckit.implement tasks/tasks-and-scheduling-tasks.md
```

---

## Core Principles

### 1. Opinionated & Simple

- Every critical workflow completable in **≤ 3 screens**
- No feature bloat; focus on daily operations

### 2. Floor-Optimized

- **Big tap targets** (minimum 44×44px)
- **Dark mode** as default
- **Offline-friendly** patterns where feasible

### 3. API-First

- All features exposed via **typed HTTP/JSON APIs**
- No hidden business logic in the UI

### 4. Security & Compliance

- **Strict auth** (JWT-based)
- **RBAC** with least privilege
- **Audit logs** on all critical changes
- **METRC as system of record** (read-only in v1)

### 5. Spec Kit Governance

- Every feature starts as a spec
- Changes must not violate the constitution
- If they need to, update the constitution explicitly

---

## Actors & Roles

- **Owner**: Full access to all features
- **Compliance Manager**: Full compliance, read-only operations
- **Head Grower**: Full cultivation ops, read-only compliance
- **Staff / Trimmers**: Limited access to tasks and timeclock
- **Accountant**: Read-only reports

---

## Domains

1. **CultivationOps**: Tasks, batches, rooms, cultivation workflows
2. **Compliance**: Document storage, audit packets, METRC mapping
3. **Labor**: Timeclock, hours, labor cost analysis
4. **Inventory**: Materials, lot/serial, restock alerts
5. **Integrations**: METRC, environmental monitoring, hardware
6. **Communications**: Task comments, announcements, notifications

---

## Development Phases

### Phase 1 — Foundation (v0.1.0)

- Authentication and RBAC
- Task templates and scheduling
- Basic batch and room management
- Timeclock and labor tracking
- Compliance document storage

### Phase 2 — Operations (v0.2.0)

- Advanced batch lifecycle
- Weight logging and yield analytics
- Inventory management
- Environmental dashboards
- Notification system

### Phase 3 — Integrations (v0.3.0)

- METRC connector (read/write)
- Hardware integrations
- Advanced reporting
- Mobile app (if not PWA)
- Multi-facility support

---

## Out of Scope (v1)

- Direct METRC write integration (read-only mapping only)
- Payroll processing (exports only)
- Financial accounting beyond labor cost tracking
- Customer-facing features (B2C)
- Automated environmental control (read-only dashboards only)

---

## Getting Started

### Prerequisites

- Node.js 20.x LTS
- PostgreSQL 15.x
- npm or yarn

### Backend Setup

```bash
cd backend
npm install
cp .env.example .env
# Edit .env with your database credentials
npx prisma migrate dev
npm run dev
```

See [backend/README.md](backend/README.md) for details.

### Frontend Setup

```bash
cd frontend
npm install
cp .env.example .env
# Edit .env with your API URL
npm run dev
```

See [frontend/README.md](frontend/README.md) for details.

---

## Compliance Philosophy

**METRC is the system of record** for California cannabis track-and-trace. CA Grow Ops Manager supports compliance-adjacent workflows but does not replace METRC.

- **v1**: Read-only METRC tag mapping
- **Phase 2**: METRC connector with explicit user confirmation for writes

See [docs/compliance-notes-ca.md](docs/compliance-notes-ca.md) for details.

---

## Contributing

This project follows the **Spec Kit workflow**:

1. **Spec**: Propose a feature by writing a spec in `specs/`
2. **Review**: Discuss the spec with the team
3. **Plan**: Create an implementation plan
4. **Tasks**: Break down the plan into tasks
5. **Implement**: Build, test, and deploy

All changes must align with the [constitution](constitution.md).

---

## License

**Proprietary** — All rights reserved.

---

## Resources

### Official Documentation

- [California DCC](https://cannabis.ca.gov)
- [METRC California](https://www.metrc.com/california)
- [DCC Regulations](https://cannabis.ca.gov/cannabis-laws/dcc-regulations/)

### Tech Stack

- [Prisma](https://www.prisma.io/docs)
- [React](https://react.dev)
- [PostgreSQL](https://www.postgresql.org/docs)
- [TypeScript](https://www.typescriptlang.org/docs)

---

## Contact

For questions or support, contact the project maintainer.

---

**Last Updated**: 2025-12-08  
**Version**: 0.1.0  
**Status**: Initialized and ready for Spec Kit workflow

# Trigger CI/CD
