ca-grow-ops-manager/docs/API-WALKTHROUGH.md

Daily Walkthrough API Documentation

Base URL: /api/walkthroughs
Authentication: Required (JWT Bearer token)

---

Endpoints

1. Start New Walkthrough

POST /api/walkthroughs

Request Body:

{
  "date": "2025-12-09T08:00:00Z" // optional, defaults to now
}

Response (201):

{
  "id": "uuid",
  "date": "2025-12-09T08:00:00Z",
  "completedBy": "user-uuid",
  "startTime": "2025-12-09T08:00:00Z",
  "endTime": null,
  "status": "IN_PROGRESS",
  "user": {
    "id": "user-uuid",
    "name": "Facility Owner",
    "email": "admin@runfoo.run",
    "role": "OWNER"
  },
  "reservoirChecks": [],
  "irrigationChecks": [],
  "plantHealthChecks": [],
  "createdAt": "2025-12-09T08:00:00Z",
  "updatedAt": "2025-12-09T08:00:00Z"
}

---

2. List Walkthroughs

GET /api/walkthroughs

Query Parameters:

• status - Filter by status (IN_PROGRESS, COMPLETED, INCOMPLETE)
• userId - Filter by user ID
• startDate - Filter by start date (ISO 8601)
• endDate - Filter by end date (ISO 8601)

Example:

GET /api/walkthroughs?status=COMPLETED&startDate=2025-12-01&endDate=2025-12-09

Response (200):

[
  {
    "id": "uuid",
    "date": "2025-12-09T08:00:00Z",
    "completedBy": "user-uuid",
    "startTime": "2025-12-09T08:00:00Z",
    "endTime": "2025-12-09T08:25:00Z",
    "status": "COMPLETED",
    "user": { ... },
    "reservoirChecks": [ ... ],
    "irrigationChecks": [ ... ],
    "plantHealthChecks": [ ... ]
  }
]

---

3. Get Walkthrough Detail

GET /api/walkthroughs/:id

Response (200):

{
  "id": "uuid",
  "date": "2025-12-09T08:00:00Z",
  "completedBy": "user-uuid",
  "startTime": "2025-12-09T08:00:00Z",
  "endTime": null,
  "status": "IN_PROGRESS",
  "user": { ... },
  "reservoirChecks": [ ... ],
  "irrigationChecks": [ ... ],
  "plantHealthChecks": [ ... ]
}

Error (404):

{
  "message": "Walkthrough not found"
}

---

4. Complete Walkthrough

POST /api/walkthroughs/:id/complete

Response (200):

{
  "id": "uuid",
  "status": "COMPLETED",
  "endTime": "2025-12-09T08:25:00Z",
  ...
}

---

5. Add Reservoir Check

POST /api/walkthroughs/:id/reservoir-checks

Request Body:

{
  "tankName": "Veg Tank 1",
  "tankType": "VEG",
  "levelPercent": 85,
  "status": "OK",
  "photoUrl": "https://...",
  "notes": "All good"
}

Field Validation:

• tankName: string (required)
• tankType: "VEG" | "FLOWER" (required)
• levelPercent: number 0-100 (required)
• status: "OK" | "LOW" | "CRITICAL" (required)
• photoUrl: string (optional)
• notes: string (optional)

Response (201):

{
  "id": "uuid",
  "walkthroughId": "walkthrough-uuid",
  "tankName": "Veg Tank 1",
  "tankType": "VEG",
  "levelPercent": 85,
  "status": "OK",
  "photoUrl": "https://...",
  "notes": "All good",
  "createdAt": "2025-12-09T08:05:00Z"
}

---

6. Add Irrigation Check

POST /api/walkthroughs/:id/irrigation-checks

Request Body:

{
  "zoneName": "Veg Upstairs",
  "drippersTotal": 48,
  "drippersWorking": 47,
  "drippersFailed": ["A-12"],
  "waterFlow": true,
  "nutrientsMixed": true,
  "scheduleActive": true,
  "photoUrl": "https://...",
  "issues": "Dripper A-12 clogged"
}

Field Validation:

• zoneName: string (required) - e.g., "Veg Upstairs", "Flower Downstairs"
• drippersTotal: number (required)
• drippersWorking: number (required)
• drippersFailed: string[] (optional) - array of dripper IDs
• waterFlow: boolean (required)
• nutrientsMixed: boolean (required)
• scheduleActive: boolean (required)
• photoUrl: string (optional)
• issues: string (optional)

Response (201):

{
  "id": "uuid",
  "walkthroughId": "walkthrough-uuid",
  "zoneName": "Veg Upstairs",
  "drippersTotal": 48,
  "drippersWorking": 47,
  "drippersFailed": "[\"A-12\"]",
  "waterFlow": true,
  "nutrientsMixed": true,
  "scheduleActive": true,
  "photoUrl": "https://...",
  "issues": "Dripper A-12 clogged",
  "createdAt": "2025-12-09T08:10:00Z"
}

---

7. Add Plant Health Check

POST /api/walkthroughs/:id/plant-health-checks

Request Body:

{
  "zoneName": "Flower Upstairs",
  "healthStatus": "GOOD",
  "pestsObserved": false,
  "pestType": null,
  "waterAccess": "OK",
  "foodAccess": "OK",
  "flaggedForAttention": false,
  "issuePhotoUrl": null,
  "referencePhotoUrl": "https://...",
  "notes": "All plants healthy"
}

Field Validation:

• zoneName: string (required)
• healthStatus: "GOOD" | "FAIR" | "NEEDS_ATTENTION" (required)
• pestsObserved: boolean (required)
• pestType: string (optional) - required if pestsObserved is true
• waterAccess: "OK" | "ISSUES" (required)
• foodAccess: "OK" | "ISSUES" (required)
• flaggedForAttention: boolean (optional, defaults to false)
• issuePhotoUrl: string (optional)
• referencePhotoUrl: string (optional)
• notes: string (optional)

Response (201):

{
  "id": "uuid",
  "walkthroughId": "walkthrough-uuid",
  "zoneName": "Flower Upstairs",
  "healthStatus": "GOOD",
  "pestsObserved": false,
  "pestType": null,
  "waterAccess": "OK",
  "foodAccess": "OK",
  "flaggedForAttention": false,
  "issuePhotoUrl": null,
  "referencePhotoUrl": "https://...",
  "notes": "All plants healthy",
  "createdAt": "2025-12-09T08:15:00Z"
}

---

Error Responses

401 Unauthorized

{
  "message": "Unauthorized"
}

404 Not Found

{
  "message": "Walkthrough not found"
}

500 Internal Server Error

{
  "message": "Failed to create walkthrough"
}

---

Example Workflow

Complete Morning Walkthrough

# 1. Start walkthrough
curl -X POST https://777wolfpack.runfoo.run/api/walkthroughs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

# Response: { "id": "walk-123", ... }

# 2. Add reservoir checks (4 tanks)
curl -X POST https://777wolfpack.runfoo.run/api/walkthroughs/walk-123/reservoir-checks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tankName": "Veg Tank 1",
    "tankType": "VEG",
    "levelPercent": 85,
    "status": "OK"
  }'

# 3. Add irrigation checks (4 zones)
curl -X POST https://777wolfpack.runfoo.run/api/walkthroughs/walk-123/irrigation-checks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "zoneName": "Veg Upstairs",
    "drippersTotal": 48,
    "drippersWorking": 48,
    "drippersFailed": [],
    "waterFlow": true,
    "nutrientsMixed": true,
    "scheduleActive": true
  }'

# 4. Add plant health checks (4 zones)
curl -X POST https://777wolfpack.runfoo.run/api/walkthroughs/walk-123/plant-health-checks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "zoneName": "Veg Upstairs",
    "healthStatus": "GOOD",
    "pestsObserved": false,
    "waterAccess": "OK",
    "foodAccess": "OK"
  }'

# 5. Complete walkthrough
curl -X POST https://777wolfpack.runfoo.run/api/walkthroughs/walk-123/complete \
  -H "Authorization: Bearer $TOKEN"

---

Notes

• All endpoints require authentication
• User is automatically attributed from JWT token
• Photos are stored as URLs (upload endpoint TBD)
• Failed drippers are stored as JSON string
• Cascade delete: deleting walkthrough deletes all checks
• Timestamps are UTC ISO 8601 format