Guides

Task-shaped walkthroughs. Each one assumes you have read the relevant architecture page and want to know the specific steps.

Local developmentRun the whole stack on your machine — and avoid the production-database trap.Repository tourWhere everything is, and what to ignore.Add a providerIntegrate a new swap or bridge aggregator across swap-sdk and the backend.Add an AI intentNine files across three repos, in order.Add a chainDatabase seed, contract deploy, SDK release, two consumer bumps.Debug a tradeA user says their swap did not arrive. Work through this in order.

Getting started

Guide	For
Local development	Running the whole stack on your machine — and the production-database trap
Repository tour	Where things are, and what to ignore

Extending the platform

Guide	Touches
Add a liquidity provider	swap-sdk + bz-backend (+ defi-dex if special-cased)
Add an AI intent	9 files across 3 repos
Add a chain	Database seed, contract deploy, SDK release
Add an SEO landing page	defi-dex data modules + three route lists
Add an Autopilot trigger	Policy schema, engine, FE mirror

Working practices

Guide	For
Testing	What tests exist, what does not, and what to run before shipping
Debugging a stuck trade	A user says their swap did not arrive
Curating token lists	"USDT is missing on chain X"

Ground rules

A few things apply to every task in this section.

Local development points at production

bz-backend's local .env uses the production Atlas connection string, and Network Access allows rotating developer IPs. Set CRON=false before you start, and read local development before running any of the loose maintenance scripts at the repo root.

vite build is the gate, not tsc

npx tsc --noEmit in defi-dex reports roughly 3,300 pre-existing errors from node_modules. Do not chase them as part of an unrelated change.

Bumping swap-sdk needs the lockfile too

npm install github:blazpay/swap-sdk#vX.Y.Z --package-lock-only, then commit both package.json and package-lock.json. Skipping the lock silently installs the old version.

No Co-Authored-By trailer on commits

Do not append a Co-Authored-By: or AI-generated trailer.

Which branch

Repo	Branch	Notes
bz-backend	bishtNew	Deployed with ./scripts/deploy.gcp.sh
bz-agent	main	Built on the VM
defi-dex	optimized	Netlify auto-builds. main is ~80 commits behind and stale
swap-sdk	tags vX.Y.Z	Consumed as a git dependency