da7729d6e4
- 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
232 lines
7.1 KiB
Markdown
232 lines
7.1 KiB
Markdown
# CA Grow Ops Manager — Constitution
|
||
|
||
This document encodes the **non-negotiable principles** that govern the design, architecture, and development of the CA Grow Ops Manager platform.
|
||
|
||
---
|
||
|
||
## 1. Mission & Purpose
|
||
|
||
**CA Grow Ops Manager** exists to **reduce cognitive load** for teams managing licensed California cannabis cultivation facilities by:
|
||
|
||
- Centralizing grow operations (tasks, batches, rooms)
|
||
- Tracking labor and associating costs to batches/rooms
|
||
- Supporting compliance-adjacent recordkeeping (while METRC remains the system of record)
|
||
- Providing scheduling and team communication tools
|
||
- Integrating with environmental monitoring systems
|
||
|
||
The platform must be **opinionated, simple to use on the floor, and safe for regulated environments**.
|
||
|
||
---
|
||
|
||
## 2. Technology Stack
|
||
|
||
### Backend
|
||
|
||
- **Language**: TypeScript
|
||
- **Runtime**: Node.js
|
||
- **Framework**: Express or Fastify
|
||
- **Database**: PostgreSQL
|
||
- **ORM**: Prisma (or similar typed ORM)
|
||
- **Testing**: Unit tests for business logic; integration tests for critical workflows (auth, tasks, time tracking, exports)
|
||
|
||
### Frontend
|
||
|
||
- **Language**: TypeScript
|
||
- **Framework**: React
|
||
- **Build Tool**: Vite or Next.js
|
||
- **Component Library**: Accessible primitives (e.g., Radix UI or shadcn-style components)
|
||
- **Styling**: Modern CSS-in-JS or utility-first CSS (Tailwind acceptable)
|
||
|
||
### Mobile
|
||
|
||
- **Primary**: Web-first, fully usable on tablets
|
||
- **Stretch Goal**: React Native or React Native Web / Capacitor-style PWA
|
||
- **Requirement**: All critical workflows must be completable on mobile/tablet devices
|
||
|
||
---
|
||
|
||
## 3. Architecture Principles
|
||
|
||
### Modularity & Domain Boundaries
|
||
|
||
- **Feature-first structure** with clear domain boundaries:
|
||
- `CultivationOps` (tasks, batches, rooms)
|
||
- `Compliance` (recordkeeping, audit packets)
|
||
- `Labor` (timeclock, hours, cost tracking)
|
||
- `Inventory` (materials, nutrients, supplies)
|
||
- `Integrations` (METRC, environmental monitoring, hardware)
|
||
- `Communications` (task comments, notifications, announcements)
|
||
|
||
### API-First Design
|
||
|
||
- All features exposed via **typed HTTP/JSON APIs**
|
||
- No hidden business logic in the UI
|
||
- Clear separation between presentation and domain logic
|
||
|
||
### Security & Compliance
|
||
|
||
- **Strict authentication** (JWT or session-based)
|
||
- **Role-Based Access Control (RBAC)** with least privilege
|
||
- **Audit logs** on all critical changes (batch updates, compliance records, labor edits)
|
||
- **Data encryption** at rest and in transit
|
||
- **Input validation** and sanitization on all endpoints
|
||
|
||
### Testing & Quality
|
||
|
||
- **Unit tests** for all business logic
|
||
- **Integration tests** for critical workflows:
|
||
- Authentication and authorization
|
||
- Task creation and completion
|
||
- Time tracking (clock in/out)
|
||
- Compliance record exports
|
||
- Batch lifecycle transitions
|
||
- **Type safety** enforced via TypeScript across frontend and backend
|
||
|
||
---
|
||
|
||
## 4. User Experience Principles
|
||
|
||
### Optimized for the Floor
|
||
|
||
- **Low-friction daily use** in noisy, physical environments
|
||
- **Big tap targets** (minimum 44×44px)
|
||
- **Dark mode** as default (with light mode option)
|
||
- **Offline-friendly patterns** where feasible (service workers, local caching)
|
||
|
||
### Workflow Efficiency
|
||
|
||
- **Every critical workflow completable in ≤ 3 screens**:
|
||
- Clock in
|
||
- Complete a task
|
||
- Log a weight
|
||
- Acknowledge an alert
|
||
- **"Today / This Week" views** tuned for on-shift workers
|
||
- **Minimal cognitive load**: clear visual hierarchy, consistent patterns, predictable navigation
|
||
|
||
### Accessibility
|
||
|
||
- **WCAG 2.1 AA compliance** minimum
|
||
- **Keyboard navigation** for all interactive elements
|
||
- **Screen reader support** for critical workflows
|
||
- **High contrast** and readable typography
|
||
|
||
---
|
||
|
||
## 5. Governance & Development Workflow
|
||
|
||
### Spec Kit Loop
|
||
|
||
Every new feature follows this workflow:
|
||
|
||
1. **Spec**: Write a feature spec in `specs/` with user stories, requirements, out-of-scope, and acceptance criteria
|
||
2. **Plan**: Create an implementation plan breaking down the spec into tasks
|
||
3. **Tasks**: Define concrete, actionable tasks with clear acceptance criteria
|
||
4. **Implement**: Build, test, and deploy the feature
|
||
|
||
### Constitution Changes
|
||
|
||
- Changes that violate this constitution **must not be merged**
|
||
- If a change requires violating the constitution, **update the constitution explicitly** with rationale and team consensus
|
||
|
||
### Code Review Standards
|
||
|
||
- All code must pass type checking
|
||
- All tests must pass
|
||
- Security-sensitive changes require additional review
|
||
- Breaking changes require migration plans
|
||
|
||
---
|
||
|
||
## 6. Data & Privacy
|
||
|
||
### Data Ownership
|
||
|
||
- **Facility data belongs to the facility owner**
|
||
- Users can export all their data at any time
|
||
- Data retention policies must comply with California cannabis regulations
|
||
|
||
### Privacy
|
||
|
||
- **Minimal data collection**: only what's necessary for functionality
|
||
- **No third-party tracking** without explicit consent
|
||
- **Clear privacy policy** and terms of service
|
||
|
||
---
|
||
|
||
## 7. Compliance Philosophy
|
||
|
||
### METRC as System of Record
|
||
|
||
- **METRC is the authoritative system** for California cannabis track-and-trace
|
||
- CA Grow Ops Manager **supports compliance-adjacent workflows** but does not replace METRC
|
||
- **Read-only METRC integration** in v1; write integration requires explicit user confirmation and robust error handling
|
||
|
||
### Audit Readiness
|
||
|
||
- Platform must support **audit packet generation** (ZIP with CSV/JSON indexes and attached documents)
|
||
- Compliance views organized by **month/quarter** with DCC-aligned checklists
|
||
- **Immutable audit logs** for critical operations
|
||
|
||
---
|
||
|
||
## 8. Extensibility & Integrations
|
||
|
||
### Integration Strategy
|
||
|
||
- **Adapter pattern** for external systems (METRC, environmental monitoring, hardware)
|
||
- **Explicit configuration** for API keys, rate limits, and permissions
|
||
- **Graceful degradation** when integrations are unavailable
|
||
- **User confirmation** required before any write operations to external systems
|
||
|
||
### Hardware Integrations
|
||
|
||
- **Read-only dashboards** for environmental data (temperature, humidity, VPD)
|
||
- **Manual fallback** for all automated data inputs
|
||
- **Clear error handling** and retry logic
|
||
|
||
---
|
||
|
||
## 9. Performance & Scalability
|
||
|
||
### Performance Targets
|
||
|
||
- **Page load**: < 2 seconds on 3G
|
||
- **Time to interactive**: < 3 seconds on 3G
|
||
- **API response time**: < 200ms for p95
|
||
|
||
### Scalability
|
||
|
||
- Architecture must support **multiple facilities** (multi-tenant)
|
||
- Database design must support **horizontal scaling**
|
||
- **Caching strategy** for frequently accessed data
|
||
|
||
---
|
||
|
||
## 10. Documentation
|
||
|
||
### Required Documentation
|
||
|
||
- **Architecture diagrams** (system, data flow, trust boundaries)
|
||
- **API documentation** (OpenAPI/Swagger)
|
||
- **Deployment guides** (local, staging, production)
|
||
- **User guides** for each major feature
|
||
- **Compliance notes** specific to California cannabis regulations
|
||
|
||
### Code Documentation
|
||
|
||
- **TSDoc comments** for all public APIs
|
||
- **README files** in each major directory
|
||
- **Inline comments** for complex business logic
|
||
|
||
---
|
||
|
||
## Amendments
|
||
|
||
This constitution is a **living document**. Amendments require:
|
||
|
||
1. Explicit proposal with rationale
|
||
2. Team discussion and consensus
|
||
3. Update to this document with changelog entry
|
||
|
||
**Last Updated**: 2025-12-08
|
||
**Version**: 1.0.0
|