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](https://nodejs.org))
- **Docker Desktop** ([Download](https://www.docker.com/products/docker-desktop))
- **Git** ([Download](https://git-scm.com))
- **VS Code** (recommended) ([Download](https://code.visualstudio.com))

---

## Option 1: Docker Compose (Recommended)

The fastest way to get the full stack running:

### 1. Clone the Repository

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

### 2. Start All Services

```bash
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

```bash
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:

```bash
createdb ca_grow_ops_dev
```

### 2. Set Up Backend

```bash
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:

```bash
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

```bash
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

```bash
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

```bash
# 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)

```bash
# 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)

```bash
# 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`:

```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**:

```bash
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](constitution.md) — Project principles
   - [Architecture](docs/architecture.md) — System design
   - [Compliance Notes](docs/compliance-notes-ca.md) — California regulations

2. **Review the specs**:
   - [Tasks and Scheduling](specs/tasks-and-scheduling.md)
   - [Batches and Rooms](specs/batches-and-rooms.md)
   - [Labor and Hours](specs/labor-and-hours.md)

3. **Check the plan**:
   - [Phase 1 Plan](plans/phase-1-foundation.md)
   - [Week 1 Tasks](plans/tasks-week-1-infrastructure.md)

4. **Start coding**:
   - Pick a task from [Week 1 Tasks](plans/tasks-week-1-infrastructure.md)
   - 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](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](README.md) — Project overview
- [Backend README](backend/README.md) — Backend details
- [Frontend README](frontend/README.md) — Frontend details
- [STATUS](STATUS.md) — Current project status

### External Resources

- [Fastify Docs](https://www.fastify.io/docs/latest/)
- [Prisma Docs](https://www.prisma.io/docs)
- [React Docs](https://react.dev)
- [Tailwind Docs](https://tailwindcss.com/docs)
- [shadcn/ui Docs](https://ui.shadcn.com)

---

## License

**Proprietary** — All rights reserved.

---

**Happy Coding!** 🚀