Local dev loop

Once make init-dev has succeeded once, day-to-day development is a small set of commands and a tight feedback loop.

Make targets (skeleton root) #

Target	Effect
`make init-dev`	One-shot bootstrap: render `.env`, pull, up, RabbitMQ plugin, schemas, register the worker, install topology, issue an API token. Idempotent — safe to re-run.
`make docker-up-force`	Re-pull and recreate the stack without re-running schema/topology setup.
`make docker-stop`	`docker compose down` — stop containers, keep data volumes.
`make docker-down-clean`	`docker compose down -v` — stop containers and delete data volumes. Destructive.

For the operations the legacy skeleton wrapped behind helper targets (make up, make logs, make sh, ...), use Docker Compose directly:

docker compose ps                     # status
docker compose logs -f backend frontend worker   # tail logs
docker compose exec worker sh         # shell into the worker container
docker compose up -d --force-recreate worker     # recreate just the worker

Make targets (worker) #

Run from worker/. They proxy commands into the running worker container:

Target	Effect
`make install`	`pnpm install` inside the worker container.
`make update`	`pnpm update` inside the worker container.
`make start`	Start (or restart) the SDK process inside the worker container.
`make lint`	ESLint with `--fix`.
`make unit`	Jest unit tests.
`make fasttest`	`lint` + `unit`.
`make test`	Bring up the container, run `install` + `fasttest`, then `docker compose down -v`.

Hot reload for the worker #

The worker container runs nodemon src/index.ts. Editing files in worker/src/ triggers an automatic restart. The platform reconnects to the worker within a few seconds and resumes routing.

A typical iteration #

Edit a connector in worker/src/Hubspot/Connector/HubspotListContacts.ts.
Save. The worker reloads.
In the Admin UI, open the topology / process detail page for the topology you're working on.
Trigger the topology (press Run on the topology, post to a webhook, hit the sync API).
Watch the process detail update — successful and failed nodes are marked, basic per-node metrics are visible, and any breakpoint output you placed shows the captured payload.
If a message landed in the Trash, open it, edit the payload, and re-run from the failed step.

Debugging tips #

Inspect the message at a specific point #

Drop a Breakpoint built-in node where you want to look. When you trigger the topology from the Admin UI, the process pauses there and shows the in-flight payload before it leaves the node; resume from the same place once you've looked.

Breakpoints are a testing aid. They only pause when the process is started from the Admin UI. When the same topology is invoked via API, Cron, or a webhook, breakpoints are pass-through and the process runs end to end without stopping.

Step into the worker #

For Node.js, the container exposes the inspector port. Add to package.json:

"start:debug": "nodemon --inspect=0.0.0.0:9229 src/index.ts"

and connect Chrome DevTools / VS Code to localhost:9229. Breakpoints survive across nodemon reloads.

For PHP, install Xdebug in the container image and forward port 9003.

Replay a failed message #

Open the Trash inbox in the Admin UI, pick the failed message, click Replay. The platform re-injects the original payload into the failed step. Combined with hot reload, this is the fastest way to fix a bug: edit code, save, click Replay.

Watch worker logs #

Either docker compose logs -f worker or stream them straight in the Admin UI's Logs view. The platform tags each log entry with the process id, so you can filter to one execution.