docs(assets-controller): add architecture diagrams under docs-temp

.oxfmtrc.json

@@ -16,5 +16,9 @@
   },
   "tabWidth": 2,
   "trailingComma": "all",
-  "ignorePatterns": [".yarnrc.yml", "merged-packages/**"]
+  "ignorePatterns": [
+    ".yarnrc.yml",
+    "merged-packages/**",
+    "packages/*/docs-temp/*.html"
+  ]
 }

packages/assets-controller/docs-temp/01-component-map.architecture.json

@@ -0,0 +1,383 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "@metamask/assets-controller \u2014 Component Map",
+    "quality_profile": "showcase",
+    "viewBox": [1330, 716],
+    "views": [
+      {
+        "id": "entry",
+        "label": "How callers reach the controller",
+        "focus": ["consumers", "messenger", "controller", "state", "events"],
+        "note": "Reads and refreshes arrive as registered messenger actions; commits publish events back."
+      },
+      {
+        "id": "balance-priority",
+        "label": "Balance sources by priority",
+        "focus": ["pipeline", "activity", "accounts_api", "snap_ds", "rpc_ds"],
+        "note": "Four sources claim chains in a fixed order, so later ones absorb what is left."
+      },
+      {
+        "id": "enrichment",
+        "label": "Enrichment and egress",
+        "focus": ["token_ds", "price_ds", "token_price_api", "evm_rpc"],
+        "note": "Metadata and price run together as one parallel stage after balances land."
+      }
+    ]
+  },
+  "components": [
+    {
+      "id": "consumers",
+      "type": "frontend",
+      "label": "Client + Controllers",
+      "sublabel": "extension \u00b7 mobile",
+      "pos": [405, 40],
+      "size": [190, 60]
+    },
+    {
+      "id": "messenger",
+      "type": "messagebus",
+      "label": "Messenger",
+      "sublabel": "actions \u00b7 events",
+      "pos": [661, 40],
+      "size": [180, 60]
+    },
+    {
+      "id": "events",
+      "type": "messagebus",
+      "label": "Published Events",
+      "sublabel": "stateChange \u00b7 balanceChanged",
+      "pos": [961, 40],
+      "size": [220, 60]
+    },
+    {
+      "id": "controller",
+      "type": "backend",
+      "label": "AssetsController",
+      "sublabel": "BaseController",
+      "tag": "core",
+      "pos": [661, 168],
+      "size": [180, 64]
+    },
+    {
+      "id": "state",
+      "type": "database",
+      "label": "State Commit",
+      "sublabel": "assetsInfo \u00b7 assetsBalance",
+      "pos": [961, 168],
+      "size": [220, 64]
+    },
+    {
+      "id": "pipeline",
+      "type": "backend",
+      "label": "Middleware Pipeline",
+      "sublabel": "composed with reduceRight \u00b7 a throwing stage is caught and skipped",
+      "pos": [232, 300],
+      "size": [1038, 72]
+    },
+    {
+      "id": "activity",
+      "type": "messagebus",
+      "label": "AccountActivity",
+      "sublabel": "push only \u00b7 never fetched",
+      "tag": "priority 1",
+      "pos": [60, 470],
+      "size": [150, 68]
+    },
+    {
+      "id": "accounts_api",
+      "type": "backend",
+      "label": "AccountsApi",
+      "sublabel": "poll 30s \u00b7 timeout 15s",
+      "tag": "priority 2",
+      "pos": [232, 470],
+      "size": [150, 68]
+    },
+    {
+      "id": "snap_ds",
+      "type": "backend",
+      "label": "Snap",
+      "sublabel": "keyring events",
+      "tag": "priority 3",
+      "pos": [404, 470],
+      "size": [150, 68]
+    },
+    {
+      "id": "rpc_ds",
+      "type": "backend",
+      "label": "Rpc",
+      "sublabel": "eip155 only \u00b7 poll 30s",
+      "tag": "priority 4",
+      "pos": [576, 470],
+      "size": [150, 68]
+    },
+    {
+      "id": "staked_ds",
+      "type": "backend",
+      "label": "StakedBalance",
+      "sublabel": "mainnet + Hoodi",
+      "tag": "no claims",
+      "pos": [762, 470],
+      "size": [150, 68]
+    },
+    {
+      "id": "token_ds",
+      "type": "backend",
+      "label": "Token",
+      "sublabel": "batch 50 \u00b7 timeout 15s",
+      "pos": [948, 470],
+      "size": [150, 68]
+    },
+    {
+      "id": "price_ds",
+      "type": "backend",
+      "label": "Price",
+      "sublabel": "poll 60s \u00b7 deduped",
+      "pos": [1120, 470],
+      "size": [150, 68]
+    },
+    {
+      "id": "activity_ws",
+      "type": "cloud",
+      "label": "Activity Service",
+      "sublabel": "WebSocket",
+      "pos": [60, 632],
+      "size": [150, 60]
+    },
+    {
+      "id": "accounts_api_svc",
+      "type": "cloud",
+      "label": "Accounts API",
+      "sublabel": "v5 / v6 balances",
+      "pos": [232, 632],
+      "size": [150, 60]
+    },
+    {
+      "id": "snaps",
+      "type": "external",
+      "label": "Keyring Snaps",
+      "sublabel": "Solana \u00b7 Bitcoin",
+      "pos": [404, 632],
+      "size": [150, 60]
+    },
+    {
+      "id": "evm_rpc",
+      "type": "external",
+      "label": "EVM JSON-RPC",
+      "sublabel": "Multicall3 \u00b7 staking vault",
+      "pos": [576, 632],
+      "size": [336, 60]
+    },
+    {
+      "id": "token_price_api",
+      "type": "cloud",
+      "label": "Tokens + Price API",
+      "sublabel": "metadata \u00b7 spot prices",
+      "pos": [948, 632],
+      "size": [322, 60]
+    }
+  ],
+  "boundaries": [
+    {
+      "kind": "region",
+      "label": "controller core",
+      "wraps": ["controller", "state", "pipeline"],
+      "pad": 20
+    },
+    {
+      "kind": "security-group",
+      "label": "balance sources \u00b7 first-pick chain assignment",
+      "wraps": ["activity", "accounts_api", "snap_ds", "rpc_ds"],
+      "pad": 14
+    },
+    {
+      "kind": "security-group",
+      "label": "enrichment \u00b7 one parallel stage",
+      "wraps": ["token_ds", "price_ds"],
+      "pad": 14
+    }
+  ],
+  "connections": [
+    {
+      "from": "consumers",
+      "to": "messenger",
+      "label": "getAssets",
+      "variant": "emphasis",
+      "fromSide": "right",
+      "toSide": "left"
+    },
+    {
+      "from": "messenger",
+      "to": "controller",
+      "label": "action handlers",
+      "variant": "emphasis",
+      "fromSide": "bottom",
+      "toSide": "top",
+      "labelDy": 58
+    },
+    {
+      "from": "controller",
+      "to": "state",
+      "label": "merge + normalize",
+      "fromSide": "right",
+      "toSide": "left"
+    },
+    {
+      "from": "state",
+      "to": "events",
+      "label": "on commit",
+      "variant": "dashed",
+      "fromSide": "top",
+      "toSide": "bottom"
+    },
+    {
+      "from": "controller",
+      "to": "pipeline",
+      "label": "#executeMiddlewares",
+      "variant": "emphasis",
+      "fromSide": "bottom",
+      "toSide": "top",
+      "labelDy": 45
+    },
+    {
+      "from": "activity",
+      "to": "controller",
+      "label": "onAssetsUpdate push",
+      "variant": "dashed",
+      "fromSide": "top",
+      "toSide": "left"
+    },
+    {
+      "from": "pipeline",
+      "to": "accounts_api",
+      "label": "balance \u00b7 pLimit 3",
+      "fromSide": "bottom",
+      "toSide": "top",
+      "labelSegment": 2
+    },
+    {
+      "from": "pipeline",
+      "to": "snap_ds",
+      "label": "background lane",
+      "fromSide": "bottom",
+      "toSide": "top",
+      "labelSegment": 2
+    },
+    {
+      "from": "pipeline",
+      "to": "rpc_ds",
+      "label": "fallback lane",
+      "fromSide": "bottom",
+      "toSide": "top",
+      "labelSegment": 2
+    },
+    {
+      "from": "pipeline",
+      "to": "staked_ds",
+      "label": "extra source",
+      "fromSide": "bottom",
+      "toSide": "top",
+      "labelSegment": 2
+    },
+    {
+      "from": "pipeline",
+      "to": "token_ds",
+      "label": "metadata",
+      "fromSide": "bottom",
+      "toSide": "top",
+      "labelSegment": 2
+    },
+    {
+      "from": "pipeline",
+      "to": "price_ds",
+      "label": "price",
+      "fromSide": "bottom",
+      "toSide": "top",
+      "labelSegment": 2
+    },
+    {
+      "from": "activity",
+      "to": "activity_ws",
+      "label": "subscribe",
+      "variant": "dashed",
+      "fromSide": "bottom",
+      "toSide": "top",
+      "labelDy": 58
+    },
+    {
+      "from": "accounts_api",
+      "to": "accounts_api_svc",
+      "label": "balances",
+      "fromSide": "bottom",
+      "toSide": "top",
+      "labelDy": 58
+    },
+    {
+      "from": "snap_ds",
+      "to": "snaps",
+      "label": "keyring RPC",
+      "fromSide": "bottom",
+      "toSide": "top",
+      "labelDy": 58
+    },
+    {
+      "from": "rpc_ds",
+      "to": "evm_rpc",
+      "label": "eth_call",
+      "fromSide": "bottom",
+      "toSide": "top",
+      "labelSegment": 0
+    },
+    {
+      "from": "staked_ds",
+      "to": "evm_rpc",
+      "label": "getShares",
+      "fromSide": "bottom",
+      "toSide": "top",
+      "labelSegment": 0
+    },
+    {
+      "from": "token_ds",
+      "to": "token_price_api",
+      "label": "v3 assets",
+      "fromSide": "bottom",
+      "toSide": "top",
+      "labelSegment": 0
+    },
+    {
+      "from": "price_ds",
+      "to": "token_price_api",
+      "label": "spot prices",
+      "fromSide": "bottom",
+      "toSide": "top",
+      "labelSegment": 0
+    }
+  ],
+  "cards": [
+    {
+      "dot": "cyan",
+      "title": "Chain assignment",
+      "items": [
+        "Priority sources are walked in order; each claims the active chains it can serve",
+        "A chain is claimed once, so lower-priority sources only see the leftovers"
+      ]
+    },
+    {
+      "dot": "emerald",
+      "title": "Two ways data arrives",
+      "items": [
+        "Pull: getAssets drives the pipeline, then commits and publishes",
+        "Push: a subscribed source calls onAssetsUpdate for a shorter pipeline"
+      ]
+    },
+    {
+      "dot": "violet",
+      "title": "Basic functionality off",
+      "items": [
+        "Only Rpc and StakedBalance stay reachable for balances",
+        "Metadata and price types are stripped, so those stages skip themselves"
+      ]
+    }
+  ]
+}