Appearance
Repository tour
Where to look for what, and — just as usefully — what to ignore.
Structural detail is in repositories; this page is the orientation pass.
Start here for a given task
| Task | First file to open |
|---|---|
| A swap prices wrongly | swap-sdk/src/aggregators/<Provider>.aggregator.ts |
| No routes appear at all | swap-sdk/src/index.ts (registration), then bz-backend/services/swap.service.js (excludes) |
| A settlement revert | bz-backend/contract-deployment/contracts/BlazpayRelayer.sol |
| A CSIP position is not executing | bz-backend/services/dcaCron.js |
| An Autopilot agent is not trading | bz-backend/services/autopilotCron.js, then check the router allow-list |
| The chat misunderstood a message | bz-agent/src/utils/constant.ts — the intent description is the classifier |
| The chat understood but did nothing | bz-backend/v1/services/agent.service.js — is there a case? |
| A chat card renders wrong | defi-dex/src/component/defi/swapAI/BotMessage.tsx |
| A token is missing from the picker | Token.order — see token curation |
| A chain is missing | swap-sdk/src/utils/constants.ts, then the Network collection |
| A landing page is wrong | defi-dex/src/data/chainSeo.mjs — the only file to edit |
| Bundle size regressed | defi-dex/vite.config.ts manualChunks, then src/index.tsx |
| Something about fees | contracts/BlazpayRelayer.sol (0.1%), autopilot/ (20 bps), dca/ (auto-claim) |
bz-backend — navigating a 65-route monolith
The thing to know is that the useful code is concentrated in a handful of places.
The files you will actually open
routes/defi.routes.js ← the trading route table, ~270 lines
controllers/defi/swap.js ← SSE quote controller
controllers/defi/transaction.controller.js ← EIP-712 signing + history
services/swap.service.js ← quote fan-out, excludes, price enrichment
services/executionEngine.js ← shared route selection for both crons
services/dcaCron.js ← CSIP executor
services/autopilot{Cron,Engine,Prices,Sync}.js
utils/policy.js ← Autopilot policy toolkit
utils/constants.js ← addresses, signature types, Orderly config
middleware/walletAuth.js ← signature auth
v1/services/agent.service.js ← the intent dispatch switch
v1/models/blazMessage.js ← BLAZ_ACTIONS + the data schema
index.js ← CORS allowlist, cron registrationWhat to ignore
| Path | Why |
|---|---|
archive/ | Not mounted |
new-backend/ | Not mounted |
microservices-backend/ | Not mounted — but see the proxy flags below |
gateway/ | Not mounted |
contracts/deprecated/ | Eight superseded contracts |
*.js at the repo root (~30 files) | One-off incident scripts. Several delete data |
build.sh, build.uat.sh, migrate.yaml | Stale build tooling |
nft-customize.tsx | A stray React file in a Node repo |
"Not mounted" does not mean "not deployed"
The backend deploy is rsync mode and copies the entire working tree. All of the above ships to production; it simply is not routed. And the *_FORCE_PROXY / *_PROXY_GROUPS env flags can route rewards and threads traffic away from the in-process handlers, so check those before concluding where a request is served.
The two route surfaces
| Mount | Shape |
|---|---|
/api — routes/ | 65 flat route files, controllers in controllers/, services in services/ |
/api/v1 — v1/ | Clean routes/controllers/services/models split. BlazAI, dApp builder, audit, safety, wallet cards, training, feedback, notifications |
New AI-adjacent work goes in v1. Neither is deprecated.
defi-dex — three trees, one repo
The entry dispatcher is the key to understanding everything else:
src/index.tsx (3 KB — the only code every visitor downloads)
├─ VITE_SITE=ai → AiApp.tsx (chat shell)
├─ MARKETING_ROUTE → MarketingApp.tsx (~234 KB, no wallet stack)
└─ else → FullApp.tsx (~7 MB trading terminal)The files you will actually open
src/config/site.ts ← SITE_ID, IS_AI_SITE, CHAT_ROOT, chatPath
src/routes/{index,aiRoutes,path}.tsx ← three route tables
src/utils/trade.ts ← the swap-sdk wrapper (largest file in the repo)
src/utils/autopilotPolicy.ts ← byte-for-byte mirror of the backend
src/utils/chainPreselect.ts ← ?chain= deep links
src/data/chainSeo.mjs ← ALL landing-page content
src/component/defi/swapAI/BotMessage.tsx ← the action renderer
src/pages/defi/home/products.ts ← the product model
vite.config.ts ← manualChunks (two load-bearing pins)What to ignore
| Path | Why |
|---|---|
src/state/swap/ | Legacy Redux for the old on-chain DEX path. Do not extend |
src/App.tsx, App.test.tsx, App.css | Superseded by the three shells and AppProviders |
src/setupTests.ts, reportWebVitals.ts | Create React App leftovers |
Three lists to keep in sync
Adding a marketing route means editing all three:
MARKETING_ROUTEregex insrc/index.tsx- The route table in
src/MarketingApp.tsx src/routes/index.tsxfor in-app navigation
Miss the regex and the page loads the 7 MB bundle. Miss MarketingApp and it 404s inside the light tree.
bz-agent — small and readable
Roughly 50 files. Read it top to bottom in an hour.
src/utils/constant.ts ← AVAILABLE_INTENTS. The descriptions ARE the classifier
src/template/*.ts ← one prompt per intent (23 files)
src/agent/graph.ts ← the state machine, with the routing switch
src/agent/node.ts ← one node per intent, Zod-validated
src/utils/models.ts ← the three LLM tiersImproving classification means editing a description
There is no fine-tuned model and no embedding classifier. getInstSystemTemplate injects every intent's name → description into the entry prompt. That is why several descriptions carry explicit examples and "do NOT use this for…" clauses.
swap-sdk — one pattern, 26 times
src/index.ts ← TradeManager: WHAT IS LIVE
src/aggregator.factory.ts ← parallel fan-out, errors swallowed
src/relayer.ts ← MetaTransaction assembly
src/utils/constants.ts ← chains, addresses, status URLs
src/aggregators/base.aggregator.ts ← shared helpers
src/aggregators/<Provider>.aggregator.ts × 26Read one aggregator (LiFi is a good direct-call example, 1inch a good proxied one) and you have read them all.
Planning documents at the defi-set root
Not code, but load-bearing. Read the relevant one before touching its subsystem.
| File | Read before working on |
|---|---|
AUTOPILOT_AND_COPYTRADE_PLAN.md | Autopilot or copy trading (57 KB, organised in blocks) |
AI_SPLIT_PLAN.md | Anything touching domains or 301s |
AI_SITE_SETUP.md | The AI shell, or executing the cutover |
DAPP_BUILDER_ARCHITECTURE.md | The dApp builder |
BLAZPAY_FEATURE_INVENTORY_FOR_MARKETING.md | Any external claim — but read its own accuracy notes |
Inside bz-backend, the ecosystem layer documents itself in ad-hoc markdown: ROCKET_REWARDS_README.md, CLIPPERS_API_SPEC.md, MARKETPLACE_INTEGRATION.md, poker.md, SOCKET_DEBUG_GUIDE.md, MODULE_BUSINESS_AUDIT_2026-06.md. Those files are the authority for endpoint detail there.
bz-backend/postman/ holds request collections, which are often faster than reading a controller.
Naming warts
These are inconsistencies in the code, not in these docs. Knowing them saves time.
| You will see | It means |
|---|---|
MetaTransaction.recipient | The aggregator's spender, not the end user |
isNativeAddresss | Triple s. Do not rename without every call site |
higestPosition | Misspelled in DCA contract storage — cannot be renamed |
sendTransacionRawTron | Misspelled in trade.ts |
balz.route.js | Typo for "blaz" |
/api/supportForDasboard | Typo in a live route path |
account-exits | Should be "exists" |
| CSIP vs DCA | Same product. UI says CSIP, code says DCA |
DCA interval | The total window, not the gap |
DCA frequency | The order count, not a rate |
defi-1 | defi-dex's package.json name |
networkModal.js, TokenModal.js | "Modal" means "model" |
The three hand-maintained mirrors
Change these together or things break silently:
| A | B | Consequence of drift |
|---|---|---|
bz-backend/utils/policy.js | defi-dex/src/utils/autopilotPolicy.ts | The FE computes a hash the BE rejects — every Autopilot creation fails |
v1/models/blazMessage.js BLAZ_ACTIONS + data | defi-dex/src/types/ai-chat.type.ts | Mongoose drops the field; the card renders empty with no error |
utils/abi/{dcaAbi,autopilotAbi}.json | defi-dex/src/constants/abis/{dca,autopilot}.json | New functions invisible; changed signatures revert opaquely |