Integration Builder v2 — Design Spec

Overview

Complete rewrite of the Integration Builder, replacing the current monolithic 1,530-line component with a no-code drag & drop canvas builder powered by React Flow. The builder lets developers visually compose API integration flows by dragging blocks onto a canvas, connecting them, configuring parameters inline, and generating executable code + markdown reports.

Key shift: The current builder is a form wizard. The v2 is a visual flow editor — closer to n8n, Langflow, or Retool than to a step-by-step form.

Design Decisions (Validated)

Decision	Choice	Rationale
Architecture	Canvas Livre (React Flow)	Maximum freedom, no-code UX, supports branching and multi-operation flows
Fallback	Conversational Wizard	For mobile/accessibility; same engine, different UI — future scope, not v2 launch
Interaction model	Everything is a block	Login, KYC, Quote, Ticket — all draggable. Full freedom for the developer
Config	Inline on blocks	Click block → expands on canvas showing selects (currency, chain, method, amount)
Connections	Auto-binding + manual override	Connecting blocks auto-binds compatible outputs→inputs. Click connection to customize
Output	Generate Flow button → modal with markdown + code	Disabled until flow is valid. Generates report as overlay
Config system	Data-driven, modular files	One JSON per currency/chain/method. Adding a currency = adding a file, zero code
Color palette	Aurora Violet	#A78BFA accent, #7C3AED dark, #F472B6 secondary. Brand base (#060607, #3C3C54, #E0DCD8)
Theme	Dark + Light mode	Dark as default, toggle in top bar
Icons	Lucide React (stroke)	Minimal, 1.5px stroke, monochrome. No emojis
Right panel	None	Canvas takes full width. Output only via Generate Flow modal
Sidebar	Collapsible	Toggle to hide block palette, canvas goes full-screen
Export	Markdown + SVG/PNG	Download report as .md, export canvas diagram as SVG or PNG
Links	Visible, high contrast	Each block and report step links to Integration Guide. Color: #A78BFA (not dim)

Architecture

src/
├── pages/
│   └── integration-builder.tsx          # Page shell, layout, theme provider
├── components/
│   └── builder/
│       ├── Canvas.tsx                    # React Flow canvas wrapper
│       ├── Sidebar.tsx                   # Collapsible block palette
│       ├── TopBar.tsx                    # Logo, controls, Generate Flow button
│       ├── nodes/
│       │   ├── BaseNode.tsx             # Shared node chrome (header, handles, link)
│       │   ├── CollapsedNode.tsx        # Default view: icon, title, method, endpoint
│       │   └── ExpandedNode.tsx         # Config view: currency selects, inputs, chain picker
│       ├── edges/
│       │   └── AnimatedEdge.tsx         # Animated connection with particle effect
│       ├── config/
│       │   └── NodeConfigPanel.tsx      # Inline config form rendered inside ExpandedNode
│       ├── report/
│       │   ├── ReportModal.tsx          # Overlay modal after Generate Flow
│       │   ├── ReportPreview.tsx        # Rendered markdown preview
│       │   ├── CodeTab.tsx             # cURL / Node / Python / Go tabs
│       │   └── ExportActions.tsx        # Copy, Download .md, Export SVG/PNG
│       ├── validation/
│       │   └── FlowValidator.tsx        # Real-time validation warnings on canvas
│       └── shared/
│           ├── MethodBadge.tsx          # POST/GET/PUT/DELETE colored badge
│           ├── BindingBadge.tsx         # Shows auto-bound data between blocks
│           └── GuideLink.tsx           # High-contrast link to Integration Guide
├── engine/
│   ├── FlowEngine.ts                   # Core: resolves dependencies, validates flow, generates output
│   ├── CodeGenerator.ts                # Transforms flow graph into code snippets (cURL, Node, Python, Go)
│   ├── MarkdownGenerator.ts            # Transforms flow graph into markdown report
│   └── BindingResolver.ts             # Auto-detects compatible output→input pairs between blocks
├── registry/
│   ├── BlockRegistry.ts                # Loads and indexes all block definitions from config files
│   └── index.ts                        # Re-exports registry singleton
├── store/
│   └── useBuilderStore.ts              # Zustand store: nodes, edges, config state, theme, sidebar visibility
├── hooks/
│   ├── useAutoBinding.ts               # Auto-connects compatible ports when edges are created
│   ├── useFlowValidation.ts            # Real-time validation: missing dependencies, invalid combos
│   ├── useCanvasExport.ts              # Export canvas as SVG/PNG using html-to-image or react-flow utils
│   └── useTheme.ts                     # Dark/light mode toggle with CSS variable switching
└── configs/
    ├── currencies/
    │   ├── brl.json
    │   ├── usdc.json
    │   ├── usdt.json
    │   ├── eurc.json
    │   ├── cop.json
    │   └── ...
    ├── payment-methods/
    │   ├── pix.json
    │   ├── wire.json
    │   ├── ach.json
    │   └── ...
    ├── chains/
    │   ├── polygon.json
    │   ├── ethereum.json
    │   ├── base.json
    │   └── ...
    └── blocks/
        ├── login.json
        ├── kyc-level1.json
        ├── kyb.json
        ├── account-info.json
        ├── balances.json
        ├── beneficiary-wallet.json
        ├── beneficiary-bank.json
        ├── get-quote.json
        ├── create-ticket.json
        └── convert.json

Config File Format

Block Definition (`configs/blocks/get-quote.json`)

{
  "id": "get-quote",
  "name": "Get Quote",
  "category": "operations",
  "icon": "arrow-left-right",
  "description": "Get exchange rate and quote token",
  "method": "GET",
  "endpoint": "/v2/{scope}/quote/fixed-rate",
  "guideLink": "/docs/Operations/quote",
  "inputs": {
    "authToken": { "type": "token", "required": true, "from": "login.authToken" }
  },
  "outputs": {
    "quoteToken": { "type": "token", "description": "JWT quote token (expires in 5min)" },
    "rate": { "type": "number", "description": "Exchange rate applied" },
    "fees": { "type": "object", "description": "Fee breakdown" }
  },
  "configFields": [
    {
      "id": "inputCurrency",
      "label": "Input Currency",
      "type": "currency-select",
      "required": true,
      "filter": { "supportedAs": "input" }
    },
    {
      "id": "outputCurrency",
      "label": "Output Currency",
      "type": "currency-select",
      "required": true,
      "filter": { "supportedAs": "output", "compatibleWith": "inputCurrency" }
    },
    {
      "id": "inputAmount",
      "label": "Amount",
      "type": "number",
      "required": true,
      "placeholder": "1000.00"
    },
    {
      "id": "inputPaymentMethod",
      "label": "Pay In",
      "type": "payment-method-select",
      "required": true,
      "filter": { "currency": "inputCurrency" }
    },
    {
      "id": "chain",
      "label": "Chain",
      "type": "chain-select",
      "required": true,
      "filter": { "currency": "outputCurrency" }
    },
    {
      "id": "blockchainSendMethod",
      "label": "Send Method",
      "type": "select",
      "options": ["PERMIT", "TRANSFER"],
      "default": "PERMIT"
    }
  ]
}

Currency Definition (`configs/currencies/brl.json`)

{
  "id": "brl",
  "symbol": "BRL",
  "name": "Brazilian Real",
  "type": "fiat",
  "flag": "br",
  "supportedAs": ["input", "output"],
  "paymentMethods": ["pix"],
  "chains": [],
  "minAmount": 10,
  "decimalPlaces": 2
}

Adding a new currency

Create configs/currencies/mxn.json
Create configs/payment-methods/spei.json (if new method)
Done. The BlockRegistry auto-discovers and the builder renders it.

Component Behavior

Canvas

React Flow canvas with custom node types (CollapsedNode, ExpandedNode)
Grid background: subtle Aurora Violet tint, 24px grid
Zoom/Pan: standard React Flow controls, bottom-right
Minimap: bottom-left, shows node positions with gradient dots matching block colors
Toolbar: center-top, floating with glassmorphism. Buttons: Select, Pan, Auto Layout, Clear All
Radial glow: subtle gradient blobs behind node clusters for depth

Nodes

Collapsed state (default): icon (Lucide, 1.5px stroke) + title + method badge + endpoint. Compact, ~185px wide
Expanded state (on click/double-click): shows inline config form below the header. Currency pair selector with flag icons, amount input, dropdowns for method/chain/send. ~280px wide
Selected state: accent border + outer glow ring (2px rgba accent)
Validation warning: yellow badge appears above/below node when dependencies are missing
Guide link: visible on every node, #A78BFA color, "↗ Integration Guide" — links to the relevant doc page. Must be legible (no dim colors)

Connections (Edges)

Animated edges: dashed line with particle dots traveling along the path
Gradient colors: source node color → target node color gradient along the edge
Auto-binding: when user connects two nodes, the engine checks output→input compatibility and creates bindings automatically. Shows binding badge on target node (e.g., "step2.quoteToken → body.quoteToken")
Manual override: click on edge or binding badge to open a mini-panel to remap fields
Bezier curves: smooth cubic bezier, not straight lines

Collapsible: toggle button (chevron) at the top-right of sidebar to collapse. Canvas expands to fill
Collapsed state: thin strip with just category icons, hoverable to see labels
Search: filters blocks by name/description as user types
Categories: Setup, Operations. Visually separated with category headers
Drag interaction: grab cursor on hover, grabbing on drag. Block appears as ghost on canvas while dragging
Block preview: icon (with gradient background) + name + endpoint in mono font

Generate Flow Button

Disabled state: grayed out when flow has zero blocks or has validation errors. Tooltip explains why
Enabled state: Aurora Violet gradient, subtle glow shadow, hover lifts 1px
On click: validates flow → resolves all bindings → generates output → opens Report Modal

Overlay: dark backdrop, centered modal with max-width ~800px
Tabs: Preview (rendered), Markdown (raw), cURL, Node.js, Python, Go
Preview tab: each step as a card with step number (gradient badge), method badge, description, code block, binding indicators, Guide link
Code tabs: full executable snippet with syntax highlighting. Copy button per block
Actions: Copy full content, Download as .md, Export canvas as SVG/PNG, Close
Keyboard: Escape to close, Tab to navigate

Color Palette — Aurora Violet

Dark Mode (Default)

Role	Color	Usage
bg-deep	`#060607`	Page background, deep surfaces
bg-surface	`#0F0A1A`	Sidebar, modals, panels
bg-card	`#130E20`	Node backgrounds, input backgrounds
border	`#2A1D45`	Active borders, hover states
border-subtle	`#1A1230`	Default borders, dividers
accent	`#A78BFA`	Primary accent, links, highlights, Guide links
accent-dark	`#7C3AED`	Buttons, active states, selected borders
accent-bg	`#1E1035`	Accent surface tint (badges, code bg)
secondary	`#F472B6`	Secondary highlights, bindings, GET badges
success	`#4ADE80`	POST badges, success states
info	`#60A5FA`	GET badges, info callouts
warning	`#FBBF24`	Validation warnings
text-primary	`#E0DCD8`	Headings, node titles
text-secondary	`#BCB6B8`	Body text, descriptions
text-muted	`#827F9A`	Subtle labels, placeholders
text-dim	`#3C3C54`	Category headers, disabled text

Light Mode

Inverted palette maintaining the same accent colors:

Role	Color
bg-deep	`#F8F6F4`
bg-surface	`#FFFFFF`
bg-card	`#F0EDE8`
border	`#D2CCCA`
border-subtle	`#E0DCD8`
accent	`#7C3AED`
accent-dark	`#6D28D9`
text-primary	`#1A1230`
text-secondary	`#3C3C54`
text-muted	`#827F9A`

Icons — Lucide React Mapping

Block	Icon	Lucide Name
Login	Key outline	`log-in`
KYC Level 1	User with checkmark	`user-check`
KYB	Building	`building-2`
Account Info	Wallet	`wallet`
Balances	Coins	`coins`
Beneficiary (wallet)	Wallet arrow	`send`
Beneficiary (bank)	Landmark	`landmark`
Get Quote	Bidirectional arrows	`arrow-left-right`
Create Ticket	Receipt	`receipt`
Convert	Refresh arrows	`refresh-cw`

All icons: 1.5px stroke weight, 18px size inside 26x26 gradient-filled rounded square.

Animations & Micro-interactions

Connection Flow Particles

Small circles (r=2.5) travel along edge paths using SVG animateMotion
Color matches the gradient of the edge (source → target)
Duration: 2-3s per cycle, infinite repeat
Subtle glow pulse animation on the particle (opacity 0.3 → 1.0)

Node Interactions

Hover: border brightens from border-subtle → border, soft box-shadow appears (0.2s ease)
Select: accent border + 2px outer ring in accent-glow, stronger shadow
Expand/Collapse: smooth height transition (0.25s ease-out) with content fade-in
Drag from sidebar: ghost preview follows cursor with 0.8 opacity, drop zone highlights on canvas

Canvas Ambient

Subtle radial gradients in the background that shift position slightly on mouse move (parallax, very subtle — 2-3px max)
Grid lines pulse faintly on node drop (single pulse, 0.3s)

Generate Flow Button

Disabled: flat gray, no shadow
Enabled: gradient shimmer animation (subtle, 3s cycle), glow shadow
Hover: lift 1px (translateY), shadow expands
Click: pressed state (scale 0.98), then modal slides up

Entry: backdrop fades in (0.2s), modal slides up from bottom (0.3s ease-out)
Exit: reverse animation on Escape/Close
Tab switch: content cross-fade (0.15s)

Width transitions from 230px → 48px (0.25s ease)
Block labels fade out, only icons remain in collapsed state
Canvas expands to fill the space smoothly

Validation System

Real-time validation runs on every node/edge change:

Rule	Behavior
Missing dependency	Yellow warning badge: "Requires [Block] before this"
Invalid currency combo	Red warning: "BRL → BRL is not a valid combination"
Disconnected node	Subtle dimming + dashed border
Circular dependency	Red warning: "Circular dependency detected"
Incomplete config	Orange dot on node header: "Configure required fields"

Warnings are non-blocking — the developer can see them but isn't forced to fix before exploring. The Generate Flow button only enables when there are zero red/blocking errors.

Keyboard Shortcuts

Key	Action
`Delete` / `Backspace`	Remove selected node or edge
`Ctrl+Z`	Undo
`Ctrl+Shift+Z`	Redo
`Ctrl+A`	Select all nodes
`Space` (hold)	Pan mode
`Ctrl+G`	Generate Flow (when enabled)
`Escape`	Deselect / Close modal
`Ctrl+F`	Focus sidebar search
`1-9`	Quick-add block by position in sidebar

Additional Features (My Suggestions)

Flow Templates

Pre-built flow templates that load a common pattern onto the canvas with one click. Accessible from an empty state or a "Templates" button in the toolbar.

Onramp BRL→USDC (PIX): Login → KYC → Beneficiary → Quote → Ticket
Offramp USDC→BRL: Login → Beneficiary (bank) → Quote → Ticket
Cross-border COP→USDC: Login → KYC → Beneficiary → Quote → Ticket
Full KYB Setup: Login → KYB → Account Info → Balances

Templates are also defined as JSON configs — easy to add new ones.

Empty State

When canvas is empty, show a welcoming state instead of a blank grid:

"Drag blocks from the sidebar or pick a template to get started"
3-4 template cards (most common flows) as quick-start
Subtle animated gradient background

URL State Persistence

Encode the current flow as a compressed URL parameter. Developers can share their flow with teammates by sharing the URL. On page load, decode and restore the canvas state.

Snap-to-Grid

Nodes snap to the 24px grid when dropped or moved, keeping the canvas tidy. Can be toggled off in toolbar.

Auto Layout

"Auto Layout" button reorganizes all nodes into a clean top-to-bottom or left-to-right tree layout using dagre algorithm (React Flow has built-in support). Useful after building a complex flow.

Flow Validation Summary

A small floating indicator in the top-right of the canvas: "4 blocks · 3 connections · Ready to generate" or "4 blocks · 2 warnings". Clicking it scrolls/zooms to the first warning.

Dark/Light Mode Transition

Smooth CSS transition (0.3s) on theme toggle. No flash. CSS variables swap via a data-theme attribute on the root.

Tech Stack

Layer	Technology	Why
Canvas	React Flow (xyflow)	Industry standard for node editors. 30k+ stars, active maintenance
State	Zustand	Lightweight, no boilerplate, perfect for React Flow integration
Animations	Framer Motion + CSS	Framer for layout animations, CSS for micro-interactions
Icons	Lucide React	Already in project, minimal stroke icons
Styling	CSS Modules	Already used in project, scoped by default
Code highlight	Prism React Renderer	Already in project (Docusaurus dependency)
Canvas export	html-to-image	Lightweight, exports DOM to SVG/PNG
Auto layout	dagre	Standard graph layout algorithm, React Flow compatible
URL state	lz-string	Compresses flow state for URL sharing

Docusaurus Integration

The builder lives inside the Docusaurus site as a custom page (not a doc). Key integration points:

Theme: reads Docusaurus color mode and maps to builder dark/light theme
Navigation: accessible from main nav bar as "Builder" tab
Routing: /integration-builder path (same as current)
Guide links: relative links to /docs/... pages within the same site
Static: all logic is client-side, no server needed. Configs are imported at build time

Migration Path

The current integration-builder.tsx (1,530 lines) and flow-config.ts (752 lines) are replaced entirely. No incremental migration — this is a full rewrite. The current files serve as reference for:

All supported currency/chain/method combinations → migrated to config JSON files
Flow generation logic → migrated to FlowEngine.ts
Endpoint/body/header definitions → migrated to block JSON configs

Success Criteria

Developer can build a complete integration flow (login → KYC → quote → ticket) in under 60 seconds
Adding a new currency requires only creating a JSON file, zero TypeScript changes
All blocks link to relevant Integration Guide documentation
Canvas is responsive down to 1024px width (sidebar collapses automatically)
Dark and light modes work correctly with smooth transitions
Generated markdown/code is accurate and copy-pasteable
Canvas can be exported as SVG/PNG for documentation purposes
Flow state persists in URL for sharing

Overview​

Design Decisions (Validated)​

Architecture​

Config File Format​

Block Definition (configs/blocks/get-quote.json)​

Currency Definition (configs/currencies/brl.json)​

Adding a new currency​

Component Behavior​

Canvas​

Nodes​

Connections (Edges)​

Sidebar​

Generate Flow Button​

Report Modal​

Color Palette — Aurora Violet​

Dark Mode (Default)​

Light Mode​

Icons — Lucide React Mapping​

Animations & Micro-interactions​

Connection Flow Particles​

Node Interactions​

Canvas Ambient​

Generate Flow Button​

Report Modal​

Sidebar Collapse​

Validation System​

Keyboard Shortcuts​

Additional Features (My Suggestions)​

Flow Templates​

Empty State​

URL State Persistence​

Snap-to-Grid​

Auto Layout​

Flow Validation Summary​

Dark/Light Mode Transition​

Tech Stack​

Docusaurus Integration​

Migration Path​

Success Criteria​

Overview

Design Decisions (Validated)

Architecture

Config File Format

Block Definition (`configs/blocks/get-quote.json`)

Currency Definition (`configs/currencies/brl.json`)

Adding a new currency

Component Behavior

Canvas

Nodes

Connections (Edges)

Sidebar

Generate Flow Button

Report Modal

Color Palette — Aurora Violet

Dark Mode (Default)

Light Mode

Icons — Lucide React Mapping

Animations & Micro-interactions

Connection Flow Particles

Node Interactions

Canvas Ambient

Generate Flow Button

Report Modal

Sidebar Collapse

Validation System

Keyboard Shortcuts

Additional Features (My Suggestions)

Flow Templates

Empty State

URL State Persistence

Snap-to-Grid

Auto Layout

Flow Validation Summary

Dark/Light Mode Transition

Tech Stack

Docusaurus Integration

Migration Path

Success Criteria