┌─────────────────────────────────────────────────────────────────────┐
│                        Demo Store (Next.js 16)                      │
│  Product Listings · Checkout · Order Tracking · Seller Dashboard    │
│  RainbowKit + wagmi + viem  ·  shadcn/ui + Tailwind                │
└────────────────────────────────┬────────────────────────────────────┘
                                 │ REST / WebSocket
┌────────────────────────────────▼────────────────────────────────────┐
│                       Backend API (Fastify + TypeScript)             │
│                                                                     │
│  Routes: orders · shipping · disputes · sellers · platform · agents │
│  Bridges: blockchain (ethers.js) · shippo · pinata                  │
│  Services: order · shipping · dispute · payout · webhook · agent    │
│  Queue: BullMQ + Redis  ·  WS: real-time state updates             │
└───────┬──────────────┬──────────────┬──────────────┬───────────────┘
        │              │              │              │
        ▼              ▼              ▼              ▼
┌──────────────┐ ┌───────────┐ ┌───────────┐ ┌──────────────────────┐
│ XRPL EVM     │ │ Shippo    │ │ Pinata    │ │ Pinata Agents        │
│ Sidechain    │ │ Shipping  │ │ IPFS      │ │ (OpenClaw)           │
│              │ │           │ │           │ │                      │
│ EscrowFSM    │ │ Rates     │ │ Invoices  │ │ BuyerAgent           │
│ DisputeRes.  │ │ Labels    │ │ Labels    │ │ SellerAgent          │
│ FLUSD Token  │ │ Tracking  │ │ Evidence  │ │ AdminAgent           │
│              │ │ Webhooks  │ │ Receipts  │ │                      │
│ Chain: 1449k │ │           │ │           │ │ 15 Skills (IPFS)     │
│ Gas: XRP     │ │ Sandbox   │ │ SDK       │ │ Pinata MCP Server    │
└──────────────┘ └───────────┘ └───────────┘ └──────────────────────┘

flowstate/
├── packages/contracts/     # Solidity smart contracts (Hardhat 3, XRPL EVM Sidechain)
│   ├── contracts/
│   │   ├── FLUSD.sol                    # Mock RLUSD stablecoin (ERC-20, 6 decimals)
│   │   ├── EscrowStateMachine.sol       # 7-state escrow FSM with streaming payouts
│   │   ├── DisputeResolver.sol          # Dispute lifecycle + auto-resolve
│   │   └── interfaces/                  # IEscrowStateMachine.sol, IDisputeResolver.sol
│   ├── test/                            # Hardhat + Mocha + Chai test suites
│   ├── ignition/                        # Hardhat Ignition deployment modules
│   └── hardhat.config.ts               # XRPL EVM Testnet network config
│
├── backend/                # Fastify REST API (TypeScript)
│   └── src/
│       ├── routes/          # orders, shipping, disputes, sellers, platform, agents, auth
│       ├── services/        # Business logic per domain
│       ├── bridges/         # blockchain.bridge, shippo.bridge, pinata.bridge
│       ├── queue/           # BullMQ async job processing
│       ├── ws/              # WebSocket real-time order updates
│       ├── cron/            # Grace period finalization scheduler
│       └── config/          # Environment + app configuration
│
├── pinata/                 # Pinata IPFS SDK wrapper (CommonJS)
│   └── src/
│       ├── client.js        # PinataSDK initialization (JWT + gateway)
│       ├── invoices.js      # Pin invoice PDFs + JSON to IPFS
│       ├── labels.js        # Pin Shippo shipping labels to IPFS
│       ├── evidence.js      # Pin dispute evidence files + bundles
│       └── receipts.js      # Pin state transition + payout proof receipts
│
├── pinata-mcp/             # Pinata MCP (Model Context Protocol) chat client
│   ├── .mcp.json            # MCP server config for pinata-mcp
│   └── chat.js              # AI chat loop: MCP tools + getFileInsights (PDF/JSON)
│
├── pinata-agents/          # Pinata OpenClaw Agent definitions
│   ├── agents/              # System prompts (buyer-agent.md, seller-agent.md, admin-agent.md)
│   ├── skills/              # 15 skill packages (SKILL.md + index.js per skill)
│   │   ├── buyer/           # order-status, track-shipment, file-dispute, get-receipt, list-my-orders
│   │   ├── seller/          # list-orders, get-metrics, confirm-label, respond-dispute, get-payouts
│   │   └── admin/           # get-analytics, list-sellers, flagged-sellers, webhook-logs, gas-report
│   ├── CID.txt              # IPFS CIDs for uploaded skill packages
│   └── ws-test.js           # WebSocket test client for agents
│
├── mcp-agents/             # MCP server exposing agents via LangChain + @modelcontextprotocol/sdk
│   └── src/
│       ├── agents/          # buyer-agent.ts, seller-agent.ts, admin-agent.ts, base-agent.ts
│       ├── tools/           # buyer-tools.ts, seller-tools.ts, admin-tools.ts
│       ├── session/         # Session manager for per-user context
│       └── index.ts         # MCP server entrypoint
│
├── demo-store/             # Next.js 16 e-commerce storefront
│   └── src/app/
│       ├── page.tsx          # Product listings
│       ├── product/          # Product detail pages
│       ├── cart/             # Shopping cart
│       ├── orders/           # Order tracking
│       ├── seller/           # Seller dashboard
│       ├── admin/            # Admin dashboard
│       ├── faucet/           # FLUSD testnet token faucet
│       └── api/              # API routes (orders, products, sellers, faucet, webhooks)
│
├── shippo/                 # Shippo shipping SDK wrapper (CommonJS)
│   └── src/                 # Rate shopping, label generation, tracking
│
└── docs/
    └── project-breakdown.md  # Full architecture decisions document

ESCROWED → LABEL_CREATED → SHIPPED → IN_TRANSIT → DELIVERED → FINALIZED
                                                       ↕
                                                   DISPUTED

Buyer uploads photos/PDFs
  → pinEvidenceFile() pins each file → returns CID per file
  → pinEvidenceBundle() pins a JSON manifest with all file CIDs
  → bundle CID passed to DisputeResolver.createDispute(escrowId, bundleCid)
  → CID stored on-chain permanently
  → Anyone can verify evidence via Pinata gateway: https://<gateway>/ipfs/<cid>

you: What files do I have pinned?
assistant: [calls searchFiles via MCP] You have 12 files pinned including
           invoices, shipping labels, and dispute evidence bundles...

you: What's inside that invoice?
assistant: [calls getFileInsights] This is a PDF invoice with 2 pages.
           It contains order #FS-00142 for buyer 0xf39F... totaling 150.00 FLUSD...

order-status/
├── SKILL.md       # Name, description, env var requirements (read by OpenClaw)
├── index.js       # HTTP calls to FlowState backend API
└── metadata.json  # Tool schema for LLM function calling

React Component (BuyerChat / SellerDashboard / AdminDashboard)
    ↓  POST /api/v1/agents/chat  { role, user_id, message }
FlowState Backend (agent.service.ts)
    ↓  POST to PINATA_{ROLE}_AGENT_URL
Pinata OpenClaw Container
    ↓  LLM (Nemotron) + skill scripts → FlowState API
    ↑  { response, suggested_actions }
Backend
    ↑  { success: true, data: { response, role, suggested_actions } }
React Component renders response