# 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