BACKEND_SETUP.md

# Backend Setup

## What This Backend Does

- Serves the app and API from one Node server
- Stores shared cases and workflow state in `data/cases.json`
- Accepts frontend case syncs and workflow actions
- Stores artifacts in Box while the backend/database stays the source of truth
- Optionally accepts legacy Box Automate updates at `POST /api/box/automate-update`

## Start It

Run:

```bat
START_SERVER.bat
```

Preferred mode is Node.js. The server runs at:

```txt
http://localhost:3030
```

Health check:

```txt
GET http://localhost:3030/api/health
```

## Optional Secret For Box Automate

Set this before starting the server if you want Box callback protection:

```powershell
$env:BOX_AUTOMATE_SECRET="replace-with-a-secret"
node server.js
```

Box Automate should then send the same value in:

```txt
X-Box-Automate-Secret
```

or as:

```txt
?secret=replace-with-a-secret
```

## Main API Endpoints

- `GET /api/health`
- `GET /api/cases`
- `GET /api/cases/:caseId`
- `POST /api/cases/upsert`
- `POST /api/cases/bulk-upsert`
- `POST /api/cases/:caseId/patch`
- `POST /api/workflow/supervisor-decision`
- `POST /api/workflow/dispatch-plan`
- `POST /api/workflow/crew-closeout`
- `POST /api/workflow/resolve-case`
- `POST /api/box/automate-update`

## Box Automate Payload Shape

Send JSON like this from Box:

```json
{
  "caseId": "PHL-20260530-ABCDE1",
  "workflowStage": "crew_dispatch",
  "workflowStatus": "Assigned",
  "workflowPriority": "high",
  "workflowNextAction": "Dispatch crew",
  "folderId": "1234567890",
  "boxPath": "Potholes/Ward-29/Case-PHL-20260530-ABCDE1",
  "assignedTo": "dispatch@city.gov",
  "resolutionNotes": ""
}
```

## What You Still Need From Box

- A Box folder ID for the app root
- Supervisor email
- Dispatch or crew email/group
- A public URL for this backend when you want Box to call it from the cloud

For local testing with Box cloud callbacks, use a tunnel such as `ngrok` or `cloudflared`, then point Box Automate `HTTPS Request` to:

```txt
https://your-public-url/api/box/automate-update
```