{
  "docVersion": 1,
  "id": "template-sharded-sql-vitess-style",
  "name": "Sharded SQL — Vitess style",
  "purpose": "SQL sharding behind a router: topology service resolves key ranges, reads scatter-gather across shard primaries, cross-shard writes use 2PC, and shard c0- is splitting to relieve a hotspot.",
  "nodes": {
    "app": {
      "type": "k8s",
      "label": "Application",
      "x": 20,
      "y": 260,
      "runtime": "plain SQL — no shard awareness",
      "patterns": [
        "stateless"
      ]
    },
    "router": {
      "type": "proxy",
      "label": "Query router (vtgate)",
      "x": 330,
      "y": 260,
      "runtime": "plan · route · gather",
      "color": "blue",
      "patterns": [
        "stateless",
        "autoscale"
      ],
      "notes": "Parses SQL, resolves target shards from the cached topology map, executes single-shard fast-path or scatter-gathers, and coordinates 2PC when a write spans shards."
    },
    "topo": {
      "type": "servicediscovery",
      "label": "Topology service",
      "x": 330,
      "y": 20,
      "runtime": "shard map · consistent core",
      "color": "purple",
      "patterns": [
        "replicated"
      ]
    },
    "s1": {
      "type": "database",
      "label": "Shard [-80)",
      "x": 690,
      "y": 60,
      "runtime": "primary + replicas",
      "patterns": [
        "sharded",
        "replicated"
      ]
    },
    "s2": {
      "type": "database",
      "label": "Shard [80-c0)",
      "x": 690,
      "y": 260,
      "runtime": "primary + replicas",
      "patterns": [
        "sharded",
        "replicated"
      ]
    },
    "s3": {
      "type": "database",
      "label": "Shard [c0-)",
      "x": 690,
      "y": 460,
      "runtime": "HOT · splitting…",
      "color": "amber",
      "patterns": [
        "sharded"
      ],
      "notes": "A hot range being split: the new shard backfills from this one via filtered replication, then the topology map cuts over atomically."
    },
    "s3b": {
      "type": "database",
      "label": "Shard [c0-e0) — new",
      "x": 1000,
      "y": 460,
      "runtime": "backfilling",
      "style": "dashed",
      "color": "amber"
    }
  },
  "edges": {
    "e1": {
      "from": "app",
      "to": "router",
      "fromSide": "right",
      "toSide": "left",
      "label": "SELECT / INSERT",
      "animated": true,
      "patterns": [
        "timeout"
      ]
    },
    "e2": {
      "from": "router",
      "to": "topo",
      "fromSide": "top",
      "toSide": "bottom",
      "label": "resolve ranges",
      "style": "dashed",
      "patterns": [
        "cache-aside"
      ]
    },
    "e3": {
      "from": "router",
      "to": "s1",
      "fromSide": "right",
      "toSide": "left",
      "label": "scatter",
      "animated": true
    },
    "e4": {
      "from": "router",
      "to": "s2",
      "fromSide": "right",
      "toSide": "left",
      "label": "scatter → gather",
      "animated": true
    },
    "e5": {
      "from": "router",
      "to": "s3",
      "fromSide": "right",
      "toSide": "left",
      "label": "cross-shard write · 2PC",
      "patterns": [
        "timeout",
        "retry"
      ]
    },
    "e6": {
      "from": "s3",
      "to": "s3b",
      "fromSide": "right",
      "toSide": "left",
      "label": "range split · filtered backfill",
      "style": "dashed",
      "color": "amber"
    }
  },
  "boxes": {
    "b1": {
      "x": 650,
      "y": -20,
      "w": 660,
      "h": 640,
      "label": "shard fleet — ranges of the keyspace",
      "color": "blue",
      "opacity": 0.04
    }
  },
  "texts": {
    "t1": {
      "x": 20,
      "y": 440,
      "text": "design rule: model queries so 95%+ hit ONE\nshard (shard by tenant/user). scatter-gather\nand 2PC exist — as exceptions, priced in.",
      "color": "amber",
      "size": 12
    }
  },
  "meta": {
    "createdAt": "2026-07-13T09:00:00.000Z",
    "modifiedAt": "2026-07-13T09:00:00.000Z"
  }
}