malty/ca-grow-ops-manager
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ca-grow-ops-manager/README.md
fullsizemalt da7729d6e4
Some checks failed
Deploy to Production / deploy (push) Failing after 0s
Details
Test / backend-test (push) Failing after 0s
Details
Test / frontend-test (push) Failing after 0s
Details
Initial commit: Spec Kit foundation complete 
- Constitution and project spec (spec.yml)
- 7 comprehensive feature specs (tasks, batches, labor, compliance, inventory, integrations, comms)
- Phase 1 implementation plan (6-week roadmap)
- Week 1 task breakdown (15 concrete tasks)
- Architecture and compliance documentation
- Backend and frontend setup guides
- Deployment guide for nexus-vector
- CI/CD workflows (Forgejo Actions)
- Quick start guide for developers

Project is ready for implementation with:
- Automated testing on every push
- Automatic deployment to nexus-vector on push to main
- Database migrations handled automatically
- Health checks and monitoring

Stack: TypeScript, Fastify, React, Vite, PostgreSQL, Prisma, Docker
2025-12-08 23:54:12 -08:00

310 lines
8.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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
Reference in a new issue View git blame Copy permalink