311 lines
8.3 KiB
Markdown
311 lines
8.3 KiB
Markdown
# CA Grow Ops Manager
|
||
|
||
> A production-grade web + mobile application for managing licensed California cannabis cultivation facilities.
|
||
|
||
**Version**: 0.1.0
|
||
**Status**: Initialized (Spec Kit ready)
|
||
**Last Updated**: 2025-12-08
|
||
|
||
---
|
||
|
||
## Overview
|
||
|
||
**CA Grow Ops Manager** 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
|