malty/ca-grow-ops-manager
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ca-grow-ops-manager/.specify/memory/constitution.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

7.1 KiB
Raw Permalink Blame History

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