Local Development

The repository is a pnpm workspace. Start with the package under change, then add only the service that exercises it. The web app needs generated transit assets before its first build or development start. The collector needs a local D1 migration before Wrangler serves it.

Install and inspect

The inspection command reads the current planner inputs and reports the compiled graph shape. It is useful before debugging a browser result because it separates bad source data from a client lifecycle problem.

Start the services

Use separate terminals:

The configured local ports are:

The collector dev script applies the local collector-db migrations before starting Wrangler. If it fails before the server starts, inspect the migration output instead of debugging the API client.

Generated assets

The web package runs build:planner-image before its build and preview commands. For a direct transit build, use the actual package scripts:

There is no root pnpm build:bundle command. If the map has an empty route layer, validate the generated data and inspect whether the source selected the canonical geometry or its ordered-stop fallback.

Documentation diagrams

Keep diagrams in Mermaid fenced blocks; the Markdown remains the authoring source of truth. The documentation app opens those blocks in Interactive mode, where React Flow provides selection, keyboard focus, dragging, pan, and zoom while ELK arranges the graph. Use the Mermaid segment when the original static rendering is more useful.

The interactive adapter covers the diagram families currently used by the repository: flowcharts, sequence diagrams, state diagrams, and ER diagrams. Run the docs tests after changing diagram syntax so every authored block is checked through both parsing and ELK layout.

Do and do not

Do run one focused package first. Do use the inspection and validation scripts before changing application code.

Do not assume that a cached service worker is using the files just generated. Reload with the local service worker state understood, or use a fresh browser context when testing cache behavior.