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:

START_SERVER.bat

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

http://localhost:3030

Health check:

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

Optional Secret For Box Automate

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

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

Box Automate should then send the same value in:

X-Box-Automate-Secret

or as:

?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:

{
  "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:

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