docs(keycloak-session-store): remake all 28 diagrams through the techviz pipeline

The originating repository's SVGs were drawn by hand and every one of them put a title, a subtitle and an explanation band inside the canvas. This repository forbids both, so they could not be carried over — the whole set was rebuilt through the skill's pipeline instead. Each diagram went through prepare, references, prompt, a VizSpec 1.1 citing document line ranges, lint, and render. All 28 pass lint and produce the same eight formats the existing keycloak project has. Sentences moved out of the canvas into <desc> and the paragraph beside each figure; the drawings carry names only. Two lint rules did real work rather than formatting work: edge-through-node caught arrows crossing an unrelated node and implying an adjacency that does not exist — four diagrams had to be restructured, not just relaid out evidence-outside-prepared-context caught a diagram citing another section; its anchor moved from B-0 to B-1 so all three sections it draws on are inside the prepared context lab-topology also had to change profile: its context offers a different candidate set, and query-fanout with shard roles is what the section actually shows — one entry point spreading to two Keycloak nodes. The document now carries all 28 inline, one per claim that needed one, and the section recording what was still missing is updated: the diagram gap is closed, Studio records remain. verify-pipeline.py passes. audit-records.py reports no issues. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-05 11:03:10 +09:00
parent b2963105a8
commit 75bed382c8
286 changed files with 65385 additions and 710 deletions
@@ -0,0 +1,22 @@
+# 관측을 어디에 둘 것인가
+
+## Alternative text
+
+외부 curl, Prometheus 지표, PostgreSQL 직접 조회 세 지점이 같은 시스템의 서로 다른 층을 보는 구성.
+
+## Long description
+
+처음에는 외부 curl 로만 쟀다. A-1 에서 7800 을 끊었는데 외부 응답이 전부 200 이었다. 장애가 없어서가 아니라 분단된 노드가 readiness 실패로 스스로 로드밸런서에서 빠졌기 때문이다. 그래서 관측 지점을 셋으로 늘렸다. up 지표도 신뢰할 수 없었다 — A-2 에서 503 이 나는 동안에도 1이었다. 프로세스가 살아 있고 metrics 가 응답하면 up 은 1이며 살아 있지만 쓸모없는 상태를 못 본다.
+
+## Elements and evidence
+
+- **Keycloak 클러스터** (service): 측정 대상. Evidence: L141–L146.
+- **외부 curl** (process): 사용자가 겪는 것. Evidence: L143–L147.
+- **Prometheus 지표** (process): 클러스터 내부 상태. Evidence: L143–L147.
+- **PostgreSQL 직접 조회** (process): 실제로 무엇이 저장됐는가. Evidence: L143–L147.
+
+## Relationships
+
+- **Keycloak 클러스터 → 외부 curl:** 외부 응답. Evidence: L143–L147.
+- **Keycloak 클러스터 → PostgreSQL 직접 조회:** 저장 결과. Evidence: L143–L147.
+- **Keycloak 클러스터 → Prometheus 지표:** 내부 지표. Evidence: L143–L147.
@@ -0,0 +1,18 @@
+# 관측을 어디에 둘 것인가
+# Question: 밖에서만 재면 무엇을 놓치는가
+direction: right
+n0: "Keycloak 클러스터" {
+  shape: rectangle
+}
+n1: "외부 curl" {
+  shape: rectangle
+}
+n2: "Prometheus 지표" {
+  shape: rectangle
+}
+n3: "PostgreSQL 직접 조회" {
+  shape: rectangle
+}
+n0 -> n1: "외부 응답"
+n0 -> n2: "내부 지표"
+n0 -> n3: "저장 결과"
@@ -0,0 +1,12 @@
+digraph techviz {
+  graph [rankdir=LR, splines=ortho, nodesep=0.55, ranksep=0.85];
+  node [fontname=Helvetica, fontsize=11, margin="0.18,0.12", style="rounded,filled", fillcolor=white, color="#2d4357", penwidth=1.5];
+  edge [fontname=Helvetica, fontsize=10, color="#364b5f", penwidth=1.4, arrowsize=0.75];
+  n0 [label="Keycloak 클러스터", shape=box, style="rounded,filled"];
+  n1 [label="외부 curl", shape=box, style="rounded,filled"];
+  n2 [label="Prometheus 지표", shape=box, style="rounded,filled"];
+  n3 [label="PostgreSQL 직접 조회", shape=box, style="rounded,filled"];
+  n0 -> n1 [label="외부 응답", style=solid];
+  n0 -> n2 [label="내부 지표", style=solid];
+  n0 -> n3 [label="저장 결과", style=solid];
+}
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<mxfile host="app.diagrams.net" modified="2026-07-23T00:00:00.000Z" agent="techviz-harness" version="24.7.17" type="device">
+  <diagram id="observation-points" name="관측을 어디에 둘 것인가">
+    <mxGraphModel dx="680" dy="462" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+      <root>
+        <mxCell id="0"/>
+        <mxCell id="1" parent="0"/>
+        <mxCell id="n_system" value="Keycloak 클러스터&lt;br/&gt;두 노드" tooltip="측정 대상. | Evidence: L141-L146" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;strokeColor=#2563eb;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="70.0" y="203.0" width="150.0" height="71.0" as="geometry"/>
+        </mxCell>
+        <mxCell id="n_curl" value="외부 curl&lt;br/&gt;분단돼도 200 이 나올 수 있다" tooltip="사용자가 겪는 것. | Evidence: L143-L147" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;" vertex="1" parent="1">
+          <mxGeometry x="422.0" y="60.0" width="160.0" height="71.0" as="geometry"/>
+        </mxCell>
+        <mxCell id="n_prom" value="Prometheus 지표&lt;br/&gt;vendor_cluster_size · agroal_*" tooltip="클러스터 내부 상태. | Evidence: L143-L147" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;strokeColor=#2563eb;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="380.0" y="203.0" width="244.0" height="71.0" as="geometry"/>
+        </mxCell>
+        <mxCell id="n_psql" value="PostgreSQL 직접 조회&lt;br/&gt;OFFLINE_USER_SESSION" tooltip="실제로 무엇이 저장됐는가. | Evidence: L143-L147" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;strokeColor=#2563eb;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="415.0" y="346.0" width="174.0" height="71.0" as="geometry"/>
+        </mxCell>
+        <mxCell id="e_s-c" value="외부 응답" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_system" target="n_curl">
+          <mxGeometry relative="1" as="geometry">
+            <mxPoint x="345.0" y="158.0" as="offset"/>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="e_s-d" value="저장 결과" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_system" target="n_psql">
+          <mxGeometry relative="1" as="geometry">
+            <mxPoint x="341.5" y="319.0" as="offset"/>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="e_s-p" value="내부 지표" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_system" target="n_prom">
+          <mxGeometry relative="1" as="geometry">
+            <mxPoint x="300.0" y="210.5" as="offset"/>
+          </mxGeometry>
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>
@@ -0,0 +1,586 @@
+{
+  "type": "excalidraw",
+  "version": 2,
+  "source": "techviz-harness",
+  "elements": [
+    {
+      "id": "edge-s-c",
+      "type": "arrow",
+      "x": 220.0,
+      "y": 95.5,
+      "width": 202.0,
+      "height": 125.0,
+      "angle": 0,
+      "strokeColor": "#1e1e1e",
+      "backgroundColor": "transparent",
+      "fillStyle": "solid",
+      "strokeWidth": 2,
+      "strokeStyle": "solid",
+      "roughness": 1,
+      "opacity": 100,
+      "groupIds": [],
+      "frameId": null,
+      "index": null,
+      "roundness": null,
+      "seed": 1273635378,
+      "version": 1,
+      "versionNonce": 1824881434,
+      "isDeleted": false,
+      "boundElements": [],
+      "updated": 0,
+      "link": null,
+      "locked": false,
+      "points": [
+        [
+          0.0,
+          125.0
+        ],
+        [
+          101.0,
+          125.0
+        ],
+        [
+          101.0,
+          0.0
+        ],
+        [
+          202.0,
+          0.0
+        ]
+      ],
+      "lastCommittedPoint": null,
+      "startBinding": {
+        "elementId": "node-system",
+        "focus": 0,
+        "gap": 4
+      },
+      "endBinding": {
+        "elementId": "node-curl",
+        "focus": 0,
+        "gap": 4
+      },
+      "startArrowhead": null,
+      "endArrowhead": "arrow",
+      "elbowed": true
+    },
+    {
+      "id": "edge-label-s-c",
+      "type": "text",
+      "x": 300.0,
+      "y": 146.0,
+      "width": 90,
+      "height": 24,
+      "angle": 0,
+      "strokeColor": "#1e1e1e",
+      "backgroundColor": "transparent",
+      "fillStyle": "solid",
+      "strokeWidth": 1,
+      "strokeStyle": "solid",
+      "roughness": 0,
+      "opacity": 100,
+      "groupIds": [],
+      "frameId": null,
+      "index": null,
+      "roundness": {
+        "type": 3
+      },
+      "seed": 1679307150,
+      "version": 1,
+      "versionNonce": 296929840,
+      "isDeleted": false,
+      "boundElements": [],
+      "updated": 0,
+      "link": null,
+      "locked": false,
+      "fontSize": 13,
+      "fontFamily": 5,
+      "text": "외부 응답",
+      "textAlign": "center",
+      "verticalAlign": "middle",
+      "containerId": null,
+      "originalText": "외부 응답",
+      "autoResize": true,
+      "lineHeight": 1.25
+    },
+    {
+      "id": "edge-s-d",
+      "type": "arrow",
+      "x": 220.0,
+      "y": 256.5,
+      "width": 195.0,
+      "height": 125.0,
+      "angle": 0,
+      "strokeColor": "#1e1e1e",
+      "backgroundColor": "transparent",
+      "fillStyle": "solid",
+      "strokeWidth": 2,
+      "strokeStyle": "solid",
+      "roughness": 1,
+      "opacity": 100,
+      "groupIds": [],
+      "frameId": null,
+      "index": null,
+      "roundness": null,
+      "seed": 338343128,
+      "version": 1,
+      "versionNonce": 52950825,
+      "isDeleted": false,
+      "boundElements": [],
+      "updated": 0,
+      "link": null,
+      "locked": false,
+      "points": [
+        [
+          0.0,
+          0.0
+        ],
+        [
+          97.5,
+          0.0
+        ],
+        [
+          97.5,
+          125.0
+        ],
+        [
+          195.0,
+          125.0
+        ]
+      ],
+      "lastCommittedPoint": null,
+      "startBinding": {
+        "elementId": "node-system",
+        "focus": 0,
+        "gap": 4
+      },
+      "endBinding": {
+        "elementId": "node-psql",
+        "focus": 0,
+        "gap": 4
+      },
+      "startArrowhead": null,
+      "endArrowhead": "arrow",
+      "elbowed": true
+    },
+    {
+      "id": "edge-label-s-d",
+      "type": "text",
+      "x": 296.5,
+      "y": 307.0,
+      "width": 90,
+      "height": 24,
+      "angle": 0,
+      "strokeColor": "#1e1e1e",
+      "backgroundColor": "transparent",
+      "fillStyle": "solid",
+      "strokeWidth": 1,
+      "strokeStyle": "solid",
+      "roughness": 0,
+      "opacity": 100,
+      "groupIds": [],
+      "frameId": null,
+      "index": null,
+      "roundness": {
+        "type": 3
+      },
+      "seed": 877912734,
+      "version": 1,
+      "versionNonce": 1236273253,
+      "isDeleted": false,
+      "boundElements": [],
+      "updated": 0,
+      "link": null,
+      "locked": false,
+      "fontSize": 13,
+      "fontFamily": 5,
+      "text": "저장 결과",
+      "textAlign": "center",
+      "verticalAlign": "middle",
+      "containerId": null,
+      "originalText": "저장 결과",
+      "autoResize": true,
+      "lineHeight": 1.25
+    },
+    {
+      "id": "edge-s-p",
+      "type": "arrow",
+      "x": 220.0,
+      "y": 238.5,
+      "width": 160.0,
+      "height": 0.0,
+      "angle": 0,
+      "strokeColor": "#1e1e1e",
+      "backgroundColor": "transparent",
+      "fillStyle": "solid",
+      "strokeWidth": 2,
+      "strokeStyle": "solid",
+      "roughness": 1,
+      "opacity": 100,
+      "groupIds": [],
+      "frameId": null,
+      "index": null,
+      "roundness": null,
+      "seed": 44315412,
+      "version": 1,
+      "versionNonce": 1347154454,
+      "isDeleted": false,
+      "boundElements": [],
+      "updated": 0,
+      "link": null,
+      "locked": false,
+      "points": [
+        [
+          0.0,
+          0.0
+        ],
+        [
+          80.0,
+          0.0
+        ],
+        [
+          80.0,
+          0.0
+        ],
+        [
+          160.0,
+          0.0
+        ]
+      ],
+      "lastCommittedPoint": null,
+      "startBinding": {
+        "elementId": "node-system",
+        "focus": 0,
+        "gap": 4
+      },
+      "endBinding": {
+        "elementId": "node-prom",
+        "focus": 0,
+        "gap": 4
+      },
+      "startArrowhead": null,
+      "endArrowhead": "arrow",
+      "elbowed": true
+    },
+    {
+      "id": "edge-label-s-p",
+      "type": "text",
+      "x": 255.0,
+      "y": 198.5,
+      "width": 90,
+      "height": 24,
+      "angle": 0,
+      "strokeColor": "#1e1e1e",
+      "backgroundColor": "transparent",
+      "fillStyle": "solid",
+      "strokeWidth": 1,
+      "strokeStyle": "solid",
+      "roughness": 0,
+      "opacity": 100,
+      "groupIds": [],
+      "frameId": null,
+      "index": null,
+      "roundness": {
+        "type": 3
+      },
+      "seed": 1302933428,
+      "version": 1,
+      "versionNonce": 1204656141,
+      "isDeleted": false,
+      "boundElements": [],
+      "updated": 0,
+      "link": null,
+      "locked": false,
+      "fontSize": 13,
+      "fontFamily": 5,
+      "text": "내부 지표",
+      "textAlign": "center",
+      "verticalAlign": "middle",
+      "containerId": null,
+      "originalText": "내부 지표",
+      "autoResize": true,
+      "lineHeight": 1.25
+    },
+    {
+      "id": "node-system",
+      "type": "rectangle",
+      "x": 70.0,
+      "y": 203.0,
+      "width": 150.0,
+      "height": 71.0,
+      "angle": 0,
+      "strokeColor": "#1e1e1e",
+      "backgroundColor": "#ffffff",
+      "fillStyle": "solid",
+      "strokeWidth": 2,
+      "strokeStyle": "solid",
+      "roughness": 1,
+      "opacity": 100,
+      "groupIds": [],
+      "frameId": null,
+      "index": null,
+      "roundness": {
+        "type": 3
+      },
+      "seed": 767381569,
+      "version": 1,
+      "versionNonce": 1771683397,
+      "isDeleted": false,
+      "boundElements": [],
+      "updated": 0,
+      "link": null,
+      "locked": false
+    },
+    {
+      "id": "node-label-system",
+      "type": "text",
+      "x": 80.0,
+      "y": 213.0,
+      "width": 130.0,
+      "height": 51.0,
+      "angle": 0,
+      "strokeColor": "#1e1e1e",
+      "backgroundColor": "transparent",
+      "fillStyle": "solid",
+      "strokeWidth": 1,
+      "strokeStyle": "solid",
+      "roughness": 0,
+      "opacity": 100,
+      "groupIds": [],
+      "frameId": null,
+      "index": null,
+      "roundness": {
+        "type": 3
+      },
+      "seed": 776996752,
+      "version": 1,
+      "versionNonce": 171260497,
+      "isDeleted": false,
+      "boundElements": [],
+      "updated": 0,
+      "link": null,
+      "locked": false,
+      "fontSize": 15,
+      "fontFamily": 5,
+      "text": "Keycloak 클러스터\n두 노드",
+      "textAlign": "center",
+      "verticalAlign": "middle",
+      "containerId": null,
+      "originalText": "Keycloak 클러스터\n두 노드",
+      "autoResize": true,
+      "lineHeight": 1.25
+    },
+    {
+      "id": "node-curl",
+      "type": "rectangle",
+      "x": 422.0,
+      "y": 60.0,
+      "width": 160.0,
+      "height": 71.0,
+      "angle": 0,
+      "strokeColor": "#1e1e1e",
+      "backgroundColor": "#ffffff",
+      "fillStyle": "solid",
+      "strokeWidth": 2,
+      "strokeStyle": "solid",
+      "roughness": 1,
+      "opacity": 100,
+      "groupIds": [],
+      "frameId": null,
+      "index": null,
+      "roundness": {
+        "type": 3
+      },
+      "seed": 1541136388,
+      "version": 1,
+      "versionNonce": 714012886,
+      "isDeleted": false,
+      "boundElements": [],
+      "updated": 0,
+      "link": null,
+      "locked": false
+    },
+    {
+      "id": "node-label-curl",
+      "type": "text",
+      "x": 432.0,
+      "y": 70.0,
+      "width": 140.0,
+      "height": 51.0,
+      "angle": 0,
+      "strokeColor": "#1e1e1e",
+      "backgroundColor": "transparent",
+      "fillStyle": "solid",
+      "strokeWidth": 1,
+      "strokeStyle": "solid",
+      "roughness": 0,
+      "opacity": 100,
+      "groupIds": [],
+      "frameId": null,
+      "index": null,
+      "roundness": {
+        "type": 3
+      },
+      "seed": 514285477,
+      "version": 1,
+      "versionNonce": 1325089115,
+      "isDeleted": false,
+      "boundElements": [],
+      "updated": 0,
+      "link": null,
+      "locked": false,
+      "fontSize": 15,
+      "fontFamily": 5,
+      "text": "외부 curl\n분단돼도 200 이 나올 수 있다",
+      "textAlign": "center",
+      "verticalAlign": "middle",
+      "containerId": null,
+      "originalText": "외부 curl\n분단돼도 200 이 나올 수 있다",
+      "autoResize": true,
+      "lineHeight": 1.25
+    },
+    {
+      "id": "node-prom",
+      "type": "rectangle",
+      "x": 380.0,
+      "y": 203.0,
+      "width": 244.0,
+      "height": 71.0,
+      "angle": 0,
+      "strokeColor": "#1e1e1e",
+      "backgroundColor": "#ffffff",
+      "fillStyle": "solid",
+      "strokeWidth": 2,
+      "strokeStyle": "solid",
+      "roughness": 1,
+      "opacity": 100,
+      "groupIds": [],
+      "frameId": null,
+      "index": null,
+      "roundness": {
+        "type": 3
+      },
+      "seed": 241346278,
+      "version": 1,
+      "versionNonce": 481193177,
+      "isDeleted": false,
+      "boundElements": [],
+      "updated": 0,
+      "link": null,
+      "locked": false
+    },
+    {
+      "id": "node-label-prom",
+      "type": "text",
+      "x": 390.0,
+      "y": 213.0,
+      "width": 224.0,
+      "height": 51.0,
+      "angle": 0,
+      "strokeColor": "#1e1e1e",
+      "backgroundColor": "transparent",
+      "fillStyle": "solid",
+      "strokeWidth": 1,
+      "strokeStyle": "solid",
+      "roughness": 0,
+      "opacity": 100,
+      "groupIds": [],
+      "frameId": null,
+      "index": null,
+      "roundness": {
+        "type": 3
+      },
+      "seed": 46384892,
+      "version": 1,
+      "versionNonce": 1664824395,
+      "isDeleted": false,
+      "boundElements": [],
+      "updated": 0,
+      "link": null,
+      "locked": false,
+      "fontSize": 15,
+      "fontFamily": 5,
+      "text": "Prometheus 지표\nvendor_cluster_size · agroal_*",
+      "textAlign": "center",
+      "verticalAlign": "middle",
+      "containerId": null,
+      "originalText": "Prometheus 지표\nvendor_cluster_size · agroal_*",
+      "autoResize": true,
+      "lineHeight": 1.25
+    },
+    {
+      "id": "node-psql",
+      "type": "rectangle",
+      "x": 415.0,
+      "y": 346.0,
+      "width": 174.0,
+      "height": 71.0,
+      "angle": 0,
+      "strokeColor": "#1e1e1e",
+      "backgroundColor": "#ffffff",
+      "fillStyle": "solid",
+      "strokeWidth": 2,
+      "strokeStyle": "solid",
+      "roughness": 1,
+      "opacity": 100,
+      "groupIds": [],
+      "frameId": null,
+      "index": null,
+      "roundness": {
+        "type": 3
+      },
+      "seed": 797854641,
+      "version": 1,
+      "versionNonce": 1517944532,
+      "isDeleted": false,
+      "boundElements": [],
+      "updated": 0,
+      "link": null,
+      "locked": false
+    },
+    {
+      "id": "node-label-psql",
+      "type": "text",
+      "x": 425.0,
+      "y": 356.0,
+      "width": 154.0,
+      "height": 51.0,
+      "angle": 0,
+      "strokeColor": "#1e1e1e",
+      "backgroundColor": "transparent",
+      "fillStyle": "solid",
+      "strokeWidth": 1,
+      "strokeStyle": "solid",
+      "roughness": 0,
+      "opacity": 100,
+      "groupIds": [],
+      "frameId": null,
+      "index": null,
+      "roundness": {
+        "type": 3
+      },
+      "seed": 803626794,
+      "version": 1,
+      "versionNonce": 729231160,
+      "isDeleted": false,
+      "boundElements": [],
+      "updated": 0,
+      "link": null,
+      "locked": false,
+      "fontSize": 15,
+      "fontFamily": 5,
+      "text": "PostgreSQL 직접 조회\nOFFLINE_USER_SESSION",
+      "textAlign": "center",
+      "verticalAlign": "middle",
+      "containerId": null,
+      "originalText": "PostgreSQL 직접 조회\nOFFLINE_USER_SESSION",
+      "autoResize": true,
+      "lineHeight": 1.25
+    }
+  ],
+  "appState": {
+    "gridSize": 10,
+    "viewBackgroundColor": "#ffffff",
+    "currentItemFontFamily": 5
+  },
+  "files": {}
+}
@@ -0,0 +1,32 @@
+{
+  "harness_version": "0.2.0",
+  "spec_id": "observation-points",
+  "spec_version": "1.1",
+  "spec_sha256": "b5dfbe6448d4d010d8860e8aad1b93e5f867a628edc03d06798b4a676f2a8156",
+  "source_context": {
+    "document": "docs/keycloak-session-store/final/document.md",
+    "document_sha256": "1d44cba1905544d92f1d26ae36a8deb64a3db3914d6b488fd30d6ae7f8cfbabe",
+    "anchor": {
+      "kind": "heading",
+      "value": "관측을 어디에 둘 것인가",
+      "line": 140
+    }
+  },
+  "outputs": [
+    "observation-points.svg",
+    "observation-points.mmd",
+    "observation-points.d2",
+    "observation-points.dot",
+    "observation-points.drawio",
+    "observation-points.excalidraw",
+    "observation-points.alt.md"
+  ],
+  "lint_issue_count": 0,
+  "assumption_count": 0,
+  "assumptions_allowed": false,
+  "composition_profile": "component-flow",
+  "reference_ids": [
+    "payment-event-flow"
+  ],
+  "diagram_only": true
+}
@@ -0,0 +1,10 @@
+%% 관측을 어디에 둘 것인가
+%% question: 밖에서만 재면 무엇을 놓치는가
+flowchart LR
+    n0["Keycloak 클러스터"]
+    n1["외부 curl"]
+    n2["Prometheus 지표"]
+    n3["PostgreSQL 직접 조회"]
+    n0 -->|"외부 응답"| n1
+    n0 -->|"내부 지표"| n2
+    n0 -->|"저장 결과"| n3
@@ -0,0 +1,86 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="680" height="462" viewBox="0 0 680 462" role="img" aria-labelledby="diagram-title diagram-description">
+<title id="diagram-title">관측을 어디에 둘 것인가</title>
+<desc id="diagram-description">처음에는 외부 curl 로만 쟀다. A-1 에서 7800 을 끊었는데 외부 응답이 전부 200 이었다. 장애가 없어서가 아니라 분단된 노드가 readiness 실패로 스스로 로드밸런서에서 빠졌기 때문이다. 그래서 관측 지점을 셋으로 늘렸다. up 지표도 신뢰할 수 없었다 — A-2 에서 503 이 나는 동안에도 1이었다. 프로세스가 살아 있고 metrics 가 응답하면 up 은 1이며 살아 있지만 쓸모없는 상태를 못 본다.</desc>
+<metadata>{&quot;techviz&quot;:{&quot;spec_version&quot;:&quot;1.1&quot;,&quot;id&quot;:&quot;observation-points&quot;,&quot;profile&quot;:&quot;component-flow&quot;},&quot;source_context&quot;:{&quot;document&quot;:&quot;docs/keycloak-session-store/final/document.md&quot;,&quot;document_sha256&quot;:&quot;1d44cba1905544d92f1d26ae36a8deb64a3db3914d6b488fd30d6ae7f8cfbabe&quot;,&quot;anchor&quot;:{&quot;kind&quot;:&quot;heading&quot;,&quot;value&quot;:&quot;관측을 어디에 둘 것인가&quot;,&quot;line&quot;:140}},&quot;evidence_policy&quot;:&quot;Each factual element cites source lines or is marked assumption.&quot;,&quot;diagram_only&quot;:true}</metadata>
+<defs>
+  <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+    <path d="M 0 0 L 10 5 L 0 10 z" />
+  </marker>
+  <style>
+    :root { color-scheme: light; }
+    text { font-family: Inter, Pretendard, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #111827; }
+    .canvas { fill: #ffffff; }
+    .group-box { fill: #ffffff; stroke: #9ca3af; stroke-width: 1.4; stroke-dasharray: 7 5; }
+    .group-label-bg { fill: #ffffff; }
+    .group-label { font-size: 13px; font-weight: 650; fill: #374151; }
+    .edge { fill: none; stroke: #374151; stroke-width: 1.8; stroke-linejoin: round; stroke-linecap: round; marker-end: url(#arrow); }
+    .edge.style-dashed, .edge.semantic-dashed, .edge.assumption { stroke-dasharray: 7 5; }
+    .edge.style-dotted { stroke-dasharray: 2 5; }
+    .edge.emphasis-primary { stroke: #2563eb; stroke-width: 2.2; }
+    .edge.emphasis-muted { stroke: #9ca3af; }
+    .edge.emphasis-warning, .edge.kind-failure, .edge.kind-error { stroke: #dc2626; stroke-width: 2.2; }
+    .edge-label-bg { fill: #ffffff; }
+    .edge-label { font-size: 12px; font-weight: 560; text-anchor: middle; }
+    .node-shape { fill: #ffffff; stroke: #4b5563; stroke-width: 1.7; }
+    .node-shape.emphasis-primary { stroke: #2563eb; stroke-width: 2.2; }
+    .node-shape.emphasis-muted { stroke: #9ca3af; fill: #f9fafb; }
+    .node-shape.emphasis-warning { stroke: #d97706; stroke-width: 2; fill: #fffdf5; }
+    .node-shape.kind-database, .node-shape.kind-datastore, .node-shape.kind-storage { fill: #f8fafc; }
+    .node-shape.kind-queue, .node-shape.kind-event, .node-shape.kind-topic { fill: #fafafa; }
+    .node-shape.assumption { stroke-dasharray: 4 4; }
+    .storage-bottom, .controller-divider { fill: none; stroke: #4b5563; stroke-width: 1.4; }
+    .controller-led { fill: #4b5563; }
+    .actor-symbol { fill: none; stroke: #4b5563; stroke-width: 1.8; stroke-linecap: round; }
+    .actor-symbol.emphasis-primary { stroke: #2563eb; stroke-width: 2.2; }
+    .node-label { font-size: 14px; font-weight: 650; text-anchor: middle; }
+    .node-role { font-size: 10px; letter-spacing: 0.04em; text-anchor: middle; fill: #6b7280; }
+    .node-detail-divider { stroke: #d1d5db; stroke-width: 1; }
+    .node-detail { font-size: 11px; fill: #374151; }
+    .assumption-badge { font-size: 9px; font-weight: 700; fill: #92400e; }
+    .failure-mark { stroke: #dc2626; stroke-width: 4; stroke-linecap: round; }
+    .lifeline { stroke: #9ca3af; stroke-width: 1.2; stroke-dasharray: 5 5; }
+    .timeline-axis { stroke: #374151; stroke-width: 1.8; marker-end: url(#arrow); }
+    .timeline-stem { stroke: #6b7280; stroke-width: 1.3; }
+    .timeline-marker { fill: #ffffff; stroke: #374151; stroke-width: 1.7; }
+    .timeline-marker.primary { fill: #2563eb; stroke: #2563eb; }
+    .timeline-marker.warning { fill: #dc2626; stroke: #dc2626; }
+    .timeline-label { font-size: 13px; font-weight: 650; text-anchor: middle; }
+    .timeline-detail { font-size: 11px; fill: #4b5563; text-anchor: middle; }
+  </style>
+</defs>
+<rect class="canvas" width="680" height="462" />
+<polyline class="edge kind-read style-solid emphasis-normal" points="220.0,220.5 321.0,220.5 321.0,95.5 422.0,95.5" data-evidence="143-147" />
+<rect class="edge-label-bg" x="319.2" y="144.0" width="51.5" height="22" rx="3" />
+<text class="edge-label" x="345.0" y="159.0">외부 응답</text>
+<polyline class="edge kind-read style-solid emphasis-normal" points="220.0,256.5 317.5,256.5 317.5,381.5 415.0,381.5" data-evidence="143-147" />
+<rect class="edge-label-bg" x="315.8" y="305.0" width="51.5" height="22" rx="3" />
+<text class="edge-label" x="341.5" y="320.0">저장 결과</text>
+<polyline class="edge kind-read style-solid emphasis-normal" points="220.0,238.5 300.0,238.5 300.0,238.5 380.0,238.5" data-evidence="143-147" />
+<rect class="edge-label-bg" x="274.2" y="196.5" width="51.5" height="22" rx="3" />
+<text class="edge-label" x="300.0" y="211.5">내부 지표</text>
+<g id="node-system">
+<rect class="node-shape kind-service emphasis-primary role-source" data-evidence="141-146" x="70.0" y="203.0" width="150.0" height="71.0" rx="7" />
+<text class="node-label" x="145.0" y="230.0">Keycloak 클러스터</text>
+<line class="node-detail-divider" x1="84.0" y1="251.0" x2="206.0" y2="251.0" />
+<text class="node-detail" x="86.0" y="268.0">두 노드</text>
+</g>
+<g id="node-curl">
+<rect class="node-shape kind-process emphasis-normal role-target" data-evidence="143-147" x="422.0" y="60.0" width="160.0" height="71.0" rx="7" />
+<text class="node-label" x="502.0" y="87.0">외부 curl</text>
+<line class="node-detail-divider" x1="436.0" y1="108.0" x2="568.0" y2="108.0" />
+<text class="node-detail" x="438.0" y="125.0">분단돼도 200 이 나올 수 있다</text>
+</g>
+<g id="node-prom">
+<rect class="node-shape kind-process emphasis-primary role-target" data-evidence="143-147" x="380.0" y="203.0" width="244.0" height="71.0" rx="7" />
+<text class="node-label" x="502.0" y="230.0">Prometheus 지표</text>
+<line class="node-detail-divider" x1="394.0" y1="251.0" x2="610.0" y2="251.0" />
+<text class="node-detail" x="396.0" y="268.0">vendor_cluster_size · agroal_*</text>
+</g>
+<g id="node-psql">
+<rect class="node-shape kind-process emphasis-primary role-target" data-evidence="143-147" x="415.0" y="346.0" width="174.0" height="71.0" rx="7" />
+<text class="node-label" x="502.0" y="373.0">PostgreSQL 직접 조회</text>
+<line class="node-detail-divider" x1="429.0" y1="394.0" x2="575.0" y2="394.0" />
+<text class="node-detail" x="431.0" y="411.0">OFFLINE_USER_SESSION</text>
+</g>
+</svg>