ca-grow-ops-manager/QUICKSTART.md

Quick Start Guide

CA Grow Ops Manager — Get up and running in 15 minutes

---

Prerequisites

Before you begin, ensure you have:

• Node.js 20.x LTS (Download)
• Docker Desktop (Download)
• Git (Download)
• VS Code (recommended) (Download)

---

Option 1: Docker Compose (Recommended)

The fastest way to get the full stack running:

1. Clone the Repository

git clone <repository-url>
cd ca-grow-ops-manager

2. Start All Services

docker-compose up

This will start:

• Backend on http://localhost:3000
• Frontend on http://localhost:5173
• PostgreSQL on localhost:5432
• Redis on localhost:6379

3. Open in Browser

Navigate to http://localhost:5173 to see the frontend.

4. Stop Services

docker-compose down

---

Option 2: Local Development (Without Docker)

For a more traditional development setup:

1. Set Up PostgreSQL

Install PostgreSQL 15 locally or use a cloud instance.

Create a database:

createdb ca_grow_ops_dev

2. Set Up Backend

cd backend
npm install
cp .env.example .env
# Edit .env with your database credentials
npx prisma migrate dev
npm run dev

Backend will run on http://localhost:3000.

3. Set Up Frontend

In a new terminal:

cd frontend
npm install
cp .env.example .env
# Edit .env with your API URL (http://localhost:3000/api)
npm run dev

Frontend will run on http://localhost:5173.

---

Project Structure

ca-grow-ops-manager/
├── backend/              # Fastify + Prisma backend
│   ├── src/
│   │   ├── modules/      # Feature modules
│   │   ├── shared/       # Shared utilities
│   │   └── server.ts     # Entry point
│   ├── prisma/
│   │   └── schema.prisma # Database schema
│   └── package.json
├── frontend/             # Vite + React frontend
│   ├── src/
│   │   ├── pages/        # Page components
│   │   ├── components/   # Reusable components
│   │   └── main.tsx      # Entry point
│   └── package.json
├── specs/                # Feature specifications
├── plans/                # Implementation plans
├── docs/                 # Documentation
└── docker-compose.yml    # Docker Compose config

---

Common Commands

Backend

cd backend

# Development
npm run dev              # Start dev server with hot reload
npm run build            # Build for production
npm start                # Start production server

# Database
npx prisma migrate dev   # Create and apply migration
npx prisma studio        # Open Prisma Studio (DB GUI)
npx prisma generate      # Generate Prisma Client

# Testing
npm test                 # Run tests
npm run test:watch       # Run tests in watch mode
npm run test:coverage    # Generate coverage report

# Code Quality
npm run lint             # Run ESLint
npm run format           # Format with Prettier

Frontend

cd frontend

# Development
npm run dev              # Start dev server with hot reload
npm run build            # Build for production
npm run preview          # Preview production build

# Testing
npm test                 # Run tests
npm run test:ui          # Run tests with UI
npm run test:coverage    # Generate coverage report

# Code Quality
npm run lint             # Run ESLint
npm run format           # Format with Prettier

Docker

# Start all services
docker-compose up

# Start in background
docker-compose up -d

# Stop all services
docker-compose down

# Rebuild containers
docker-compose up --build

# View logs
docker-compose logs -f

# View logs for specific service
docker-compose logs -f backend

---

Environment Variables

Backend (.env)

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/ca_grow_ops_dev

# Redis
REDIS_URL=redis://localhost:6379

# JWT
JWT_SECRET=your-secret-key-change-in-production
JWT_ACCESS_EXPIRY=15m
JWT_REFRESH_EXPIRY=7d

# Server
PORT=3000
NODE_ENV=development

# Email (optional for v1)
EMAIL_SERVICE=sendgrid
EMAIL_API_KEY=your-api-key
EMAIL_FROM=noreply@example.com

Frontend (.env)

# API
VITE_API_URL=http://localhost:3000/api

# Features
VITE_AUTH_ENABLED=true
VITE_METRC_ENABLED=false

---

VS Code Setup

Recommended Extensions

Install these extensions for the best development experience:

• ESLint (dbaeumer.vscode-eslint)
• Prettier (esbenp.prettier-vscode)
• Prisma (Prisma.prisma)
• Tailwind CSS IntelliSense (bradlc.vscode-tailwindcss)
• TypeScript (built-in)

Workspace Settings

Create .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "[prisma]": {
    "editor.defaultFormatter": "Prisma.prisma"
  }
}

---

Troubleshooting

Backend won't start

Error: Cannot connect to database

Solution:

1. Ensure PostgreSQL is running
2. Check DATABASE_URL in .env
3. Run npx prisma migrate dev to apply migrations

---

Frontend won't start

Error: Cannot connect to API

Solution:

1. Ensure backend is running on http://localhost:3000
2. Check VITE_API_URL in .env
3. Check CORS settings in backend

---

Docker issues

Error: Port already in use

Solution:

1. Stop conflicting services: docker-compose down
2. Check for other processes using ports 3000, 5173, 5432, 6379
3. Kill processes: lsof -ti:3000 | xargs kill -9

---

Prisma issues

Error: Prisma Client not generated

Solution:

cd backend
npx prisma generate

Error: Migration failed

Solution:

1. Check database connection
2. Reset database: npx prisma migrate reset (⚠️ deletes all data)
3. Reapply migrations: npx prisma migrate dev

---

Next Steps

For New Developers

1. Read the docs:

   • Constitution — Project principles
   • Architecture — System design
   • Compliance Notes — California regulations

2. Review the specs:

   • Tasks and Scheduling
   • Batches and Rooms
   • Labor and Hours

3. Check the plan:

   • Phase 1 Plan
   • Week 1 Tasks

4. Start coding:

   • Pick a task from Week 1 Tasks
   • Create a feature branch: git checkout -b feature/task-001
   • Implement the task
   • Write tests
   • Submit a PR

For Project Managers

1. Review project status: STATUS.md
2. Set up project tracking (GitHub Projects, Linear, etc.)
3. Assign tasks to team members
4. Schedule kickoff meeting

---

Getting Help

Documentation

• README — Project overview
• Backend README — Backend details
• Frontend README — Frontend details
• STATUS — Current project status

External Resources

• Fastify Docs
• Prisma Docs
• React Docs
• Tailwind Docs
• shadcn/ui Docs

---

License

Proprietary — All rights reserved.

---

Happy Coding! 🚀