donghyeon.kang/document-haness
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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

Browse Source 
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>
This commit is contained in:
DongHyeonka
2026-09-05 11:03:10 +09:00
co-authored by Claude Opus 5
parent b2963105a8
commit 75bed382c8
286 changed files with 65385 additions and 710 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/keycloak-session-store/final/assets/a3-commit-to-disk-gap/a3-commit-to-disk-gap.alt.md
+22
View File
@@ -0,0 +1,22 @@
# 200 과 디스크 사이의 빈 구간
## Alternative text
클라이언트가 200 을 받은 뒤에도 WAL 이 아직 디스크에 닿지 않은 구간이 남아 있는 구성.
## Long description
Keycloak 은 트랜잭션마다 SET LOCAL synchronous_commit TO OFF 를 건다. PostgreSQL 은 COMMIT 을 WAL 디스크 기록을 기다리지 않고 즉시 반환하고, 클라이언트는 200 과 토큰을 받는다. 실측된 wal_writer_delay 는 200ms 이며 그 사이에 프로세스가 죽으면 그만큼이 사라진다. 153건 중 4건이 그렇게 유실됐다. 버그가 아니라 의도된 설계이고 그 대가를 숫자로 확인한 것이다.
## Elements and evidence
- **클라이언트** (actor): 200 과 토큰을 받는다. Evidence: L207–L213.
- **Keycloak** (service): 트랜잭션마다 synchronous_commit 을 끈다. Evidence: L211–L215.
- **PostgreSQL** (datastore): COMMIT 을 즉시 반환한다. WAL 은 아직 메모리에 있다. Evidence: L211–L215.
- **디스크의 WAL** (datastore): 여기 닿아야 살아남는다. Evidence: L207–L215.
## Relationships
- **클라이언트 → Keycloak:** 로그인 요청. Evidence: L207–L211.
- **Keycloak → PostgreSQL:** 세션 INSERT · COMMIT. Evidence: L211–L215.
- **PostgreSQL → 디스크의 WAL:** 지연된 WAL 기록. Evidence: L211–L215.
docs/keycloak-session-store/final/assets/a3-commit-to-disk-gap/a3-commit-to-disk-gap.d2
+18
View File
@@ -0,0 +1,18 @@
# 200 과 디스크 사이의 빈 구간
# Question: 로그인이 성공했는데 세션이 없을 수 있는 이유는 무엇인가
direction: down
n0: "클라이언트" {
shape: person
}
n1: "Keycloak" {
shape: rectangle
}
n2: "PostgreSQL" {
shape: cylinder
}
n3: "디스크의 WAL" {
shape: cylinder
}
n0 -> n1: "로그인 요청"
n1 -> n2: "세션 INSERT · COMMIT"
n2 -> n3: "지연된 WAL 기록"
docs/keycloak-session-store/final/assets/a3-commit-to-disk-gap/a3-commit-to-disk-gap.dot
+12
View File
@@ -0,0 +1,12 @@
digraph techviz {
graph [rankdir=TB, 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="클라이언트", shape=box, style="rounded,dashed,filled"];
n1 [label="Keycloak", shape=box, style="rounded,filled"];
n2 [label="PostgreSQL", shape=cylinder, style="rounded,filled"];
n3 [label="디스크의 WAL", shape=cylinder, style="rounded,filled"];
n0 -> n1 [label="로그인 요청", style=solid];
n1 -> n2 [label="세션 INSERT · COMMIT", style=solid];
n2 -> n3 [label="지연된 WAL 기록", style=solid];
}
docs/keycloak-session-store/final/assets/a3-commit-to-disk-gap/a3-commit-to-disk-gap.drawio
+38
View File
@@ -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="a3-commit-to-disk-gap" name="200 과 디스크 사이의 빈 구간">
<mxGraphModel dx="680" dy="742" 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_client" value="클라이언트&lt;br/&gt;로그인 153건 성공" tooltip="200 과 토큰을 받는다. | Evidence: L207-L213" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;dashed=1;fillColor=#f5f7fa;strokeColor=#2563eb;strokeWidth=2;" vertex="1" parent="1">
<mxGeometry x="134.5" y="60.0" width="150.0" height="84.0" as="geometry"/>
</mxCell>
<mxCell id="n_keycloak" value="Keycloak&lt;br/&gt;SET LOCAL synchronous_commit TO OFF" tooltip="트랜잭션마다 synchronous_commit 을 끈다. | Evidence: L211-L215" 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="70.0" y="240.0" width="279.0" height="71.0" as="geometry"/>
</mxCell>
<mxCell id="n_pg" value="PostgreSQL&lt;br/&gt;wal_writer_delay 200ms" tooltip="COMMIT 을 즉시 반환한다. WAL 은 아직 메모리에 있다. | Evidence: L211-L215" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;shape=cylinder3;boundedLbl=1;backgroundOutline=1;fillColor=#eef6fb;strokeColor=#d97706;fillColor=#fffdf5;" vertex="1" parent="1">
<mxGeometry x="115.5" y="407.0" width="188.0" height="97.0" as="geometry"/>
</mxCell>
<mxCell id="n_disk" value="디스크의 WAL&lt;br/&gt;DB 에 실제로 존재 149건" tooltip="여기 닿아야 살아남는다. | Evidence: L207-L215" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;shape=cylinder3;boundedLbl=1;backgroundOutline=1;fillColor=#eef6fb;strokeColor=#2563eb;strokeWidth=2;" vertex="1" parent="1">
<mxGeometry x="134.5" y="600.0" width="150.0" height="97.0" as="geometry"/>
</mxCell>
<mxCell id="e_c-k" value="로그인 요청" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_client" target="n_keycloak">
<mxGeometry relative="1" as="geometry">
<mxPoint x="233.5" y="192.0" as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="e_k-pg" value="세션 INSERT · COMMIT" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_keycloak" target="n_pg">
<mxGeometry relative="1" as="geometry">
<mxPoint x="233.5" y="359.0" as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="e_pg-disk" value="지연된 WAL 기록" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_pg" target="n_disk">
<mxGeometry relative="1" as="geometry">
<mxPoint x="233.5" y="552.0" as="offset"/>
</mxGeometry>
</mxCell>
</root>
</mxGraphModel>
</diagram>
</mxfile>
docs/keycloak-session-store/final/assets/a3-commit-to-disk-gap/a3-commit-to-disk-gap.excalidraw
+586
View File
@@ -0,0 +1,586 @@
{
"type": "excalidraw",
"version": 2,
"source": "techviz-harness",
"elements": [
{
"id": "edge-c-k",
"type": "arrow",
"x": 209.5,
"y": 144.0,
"width": 0.0,
"height": 96.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": 637304825,
"version": 1,
"versionNonce": 1285963241,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"points": [
[
0.0,
0.0
],
[
0.0,
48.0
],
[
0.0,
48.0
],
[
0.0,
96.0
]
],
"lastCommittedPoint": null,
"startBinding": {
"elementId": "node-client",
"focus": 0,
"gap": 4
},
"endBinding": {
"elementId": "node-keycloak",
"focus": 0,
"gap": 4
},
"startArrowhead": null,
"endArrowhead": "arrow",
"elbowed": true
},
{
"id": "edge-label-c-k",
"type": "text",
"x": 188.5,
"y": 180.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": 1672464756,
"version": 1,
"versionNonce": 775794122,
"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-k-pg",
"type": "arrow",
"x": 209.5,
"y": 311.0,
"width": 0.0,
"height": 96.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": 1058895576,
"version": 1,
"versionNonce": 290419384,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"points": [
[
0.0,
0.0
],
[
0.0,
48.0
],
[
0.0,
48.0
],
[
0.0,
96.0
]
],
"lastCommittedPoint": null,
"startBinding": {
"elementId": "node-keycloak",
"focus": 0,
"gap": 4
},
"endBinding": {
"elementId": "node-pg",
"focus": 0,
"gap": 4
},
"startArrowhead": null,
"endArrowhead": "arrow",
"elbowed": true
},
{
"id": "edge-label-k-pg",
"type": "text",
"x": 161.5,
"y": 347.0,
"width": 144,
"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": 1504141155,
"version": 1,
"versionNonce": 265883063,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 13,
"fontFamily": 5,
"text": "세션 INSERT · COMMIT",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "세션 INSERT · COMMIT",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "edge-pg-disk",
"type": "arrow",
"x": 209.5,
"y": 504.0,
"width": 0.0,
"height": 96.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": 375875096,
"version": 1,
"versionNonce": 124607208,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"points": [
[
0.0,
0.0
],
[
0.0,
48.0
],
[
0.0,
48.0
],
[
0.0,
96.0
]
],
"lastCommittedPoint": null,
"startBinding": {
"elementId": "node-pg",
"focus": 0,
"gap": 4
},
"endBinding": {
"elementId": "node-disk",
"focus": 0,
"gap": 4
},
"startArrowhead": null,
"endArrowhead": "arrow",
"elbowed": true
},
{
"id": "edge-label-pg-disk",
"type": "text",
"x": 188.5,
"y": 540.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": 326014364,
"version": 1,
"versionNonce": 1099775321,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 13,
"fontFamily": 5,
"text": "지연된 WAL 기록",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "지연된 WAL 기록",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "node-client",
"type": "rectangle",
"x": 134.5,
"y": 60.0,
"width": 150.0,
"height": 84.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "#ffffff",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "dashed",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 1893748721,
"version": 1,
"versionNonce": 1322839316,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false
},
{
"id": "node-label-client",
"type": "text",
"x": 144.5,
"y": 70.0,
"width": 130.0,
"height": 64.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": 817706832,
"version": 1,
"versionNonce": 1332899567,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 15,
"fontFamily": 5,
"text": "클라이언트\n로그인 153건 성공",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "클라이언트\n로그인 153건 성공",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "node-keycloak",
"type": "rectangle",
"x": 70.0,
"y": 240.0,
"width": 279.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": 819278378,
"version": 1,
"versionNonce": 1725278844,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false
},
{
"id": "node-label-keycloak",
"type": "text",
"x": 80.0,
"y": 250.0,
"width": 259.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": 1265230567,
"version": 1,
"versionNonce": 1115669911,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 15,
"fontFamily": 5,
"text": "Keycloak\nSET LOCAL synchronous_commit TO OFF",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "Keycloak\nSET LOCAL synchronous_commit TO OFF",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "node-pg",
"type": "rectangle",
"x": 115.5,
"y": 407.0,
"width": 188.0,
"height": 97.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "#e7f5ff",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 495847287,
"version": 1,
"versionNonce": 1955484919,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false
},
{
"id": "node-label-pg",
"type": "text",
"x": 125.5,
"y": 417.0,
"width": 168.0,
"height": 77.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": 1900836085,
"version": 1,
"versionNonce": 160871788,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 15,
"fontFamily": 5,
"text": "PostgreSQL\nwal_writer_delay 200ms",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "PostgreSQL\nwal_writer_delay 200ms",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "node-disk",
"type": "rectangle",
"x": 134.5,
"y": 600.0,
"width": 150.0,
"height": 97.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "#e7f5ff",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 492098394,
"version": 1,
"versionNonce": 862350580,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false
},
{
"id": "node-label-disk",
"type": "text",
"x": 144.5,
"y": 610.0,
"width": 130.0,
"height": 77.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": 1696521973,
"version": 1,
"versionNonce": 731803796,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 15,
"fontFamily": 5,
"text": "디스크의 WAL\nDB 에 실제로 존재 149건",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "디스크의 WAL\nDB 에 실제로 존재 149건",
"autoResize": true,
"lineHeight": 1.25
}
],
"appState": {
"gridSize": 10,
"viewBackgroundColor": "#ffffff",
"currentItemFontFamily": 5
},
"files": {}
}
docs/keycloak-session-store/final/assets/a3-commit-to-disk-gap/a3-commit-to-disk-gap.manifest.json
+32
View File
@@ -0,0 +1,32 @@
{
"harness_version": "0.2.0",
"spec_id": "a3-commit-to-disk-gap",
"spec_version": "1.1",
"spec_sha256": "29e279f39e07ba519e4e0685e5719d5d63b3ecf8b61a18816cbd5a1529baf854",
"source_context": {
"document": "docs/keycloak-session-store/final/document.md",
"document_sha256": "1d44cba1905544d92f1d26ae36a8deb64a3db3914d6b488fd30d6ae7f8cfbabe",
"anchor": {
"kind": "heading",
"value": "A-2 · A-3 — DB 가 멈출 때와 죽을 때",
"line": 201
}
},
"outputs": [
"a3-commit-to-disk-gap.svg",
"a3-commit-to-disk-gap.mmd",
"a3-commit-to-disk-gap.d2",
"a3-commit-to-disk-gap.dot",
"a3-commit-to-disk-gap.drawio",
"a3-commit-to-disk-gap.excalidraw",
"a3-commit-to-disk-gap.alt.md"
],
"lint_issue_count": 0,
"assumption_count": 0,
"assumptions_allowed": false,
"composition_profile": "component-flow",
"reference_ids": [
"payment-event-flow"
],
"diagram_only": true
}
docs/keycloak-session-store/final/assets/a3-commit-to-disk-gap/a3-commit-to-disk-gap.mmd
+12
View File
@@ -0,0 +1,12 @@
%% 200 과 디스크 사이의 빈 구간
%% question: 로그인이 성공했는데 세션이 없을 수 있는 이유는 무엇인가
flowchart TB
n0(["클라이언트"])
n1["Keycloak"]
n2[("PostgreSQL")]
n3[("디스크의 WAL")]
n0 -->|"로그인 요청"| n1
n1 -->|"세션 INSERT · COMMIT"| n2
n2 -->|"지연된 WAL 기록"| n3
classDef external stroke-dasharray: 6 4
class n0 external
docs/keycloak-session-store/final/assets/a3-commit-to-disk-gap/a3-commit-to-disk-gap.svg
+84
View File
@@ -0,0 +1,84 @@
<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" width="680" height="742" viewBox="0 0 680 742" role="img" aria-labelledby="diagram-title diagram-description">
<title id="diagram-title">200 과 디스크 사이의 빈 구간</title>
<desc id="diagram-description">Keycloak 은 트랜잭션마다 SET LOCAL synchronous_commit TO OFF 를 건다. PostgreSQL 은 COMMIT 을 WAL 디스크 기록을 기다리지 않고 즉시 반환하고, 클라이언트는 200 과 토큰을 받는다. 실측된 wal_writer_delay 는 200ms 이며 그 사이에 프로세스가 죽으면 그만큼이 사라진다. 153건 중 4건이 그렇게 유실됐다. 버그가 아니라 의도된 설계이고 그 대가를 숫자로 확인한 것이다.</desc>
<metadata>{&quot;techviz&quot;:{&quot;spec_version&quot;:&quot;1.1&quot;,&quot;id&quot;:&quot;a3-commit-to-disk-gap&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;A-2 · A-3 — DB 가 멈출 때와 죽을 때&quot;,&quot;line&quot;:201}},&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="742" />
<polyline class="edge kind-request style-solid emphasis-normal" points="209.5,144.0 209.5,192.0 209.5,192.0 209.5,240.0" data-evidence="207-211" />
<rect class="edge-label-bg" x="204.4" y="178.0" width="58.2" height="22" rx="3" />
<text class="edge-label" x="233.5" y="193.0">로그인 요청</text>
<polyline class="edge kind-write style-solid emphasis-normal" points="209.5,311.0 209.5,359.0 209.5,359.0 209.5,407.0" data-evidence="211-215" />
<rect class="edge-label-bg" x="164.2" y="345.0" width="138.6" height="22" rx="3" />
<text class="edge-label" x="233.5" y="360.0">세션 INSERT · COMMIT</text>
<polyline class="edge kind-write style-solid emphasis-normal" points="209.5,504.0 209.5,552.0 209.5,552.0 209.5,600.0" data-evidence="211-215" />
<rect class="edge-label-bg" x="191.0" y="538.0" width="85.0" height="22" rx="3" />
<text class="edge-label" x="233.5" y="553.0">지연된 WAL 기록</text>
<g id="node-client">
<g class="actor-symbol emphasis-primary" data-evidence="207-213"><circle cx="209.5" cy="80.0" r="11.0" /><line x1="209.5" y1="96.0" x2="209.5" y2="105.0" /><line x1="191.5" y1="106.0" x2="227.5" y2="106.0" /><line x1="209.5" y1="105.0" x2="194.5" y2="122.0" /><line x1="209.5" y1="105.0" x2="224.5" y2="122.0" /></g>
<text class="node-label" x="209.5" y="137.0">클라이언트</text>
</g>
<g id="node-keycloak">
<rect class="node-shape kind-service emphasis-normal role-control" data-evidence="211-215" x="70.0" y="240.0" width="279.0" height="71.0" rx="7" />
<text class="node-label" x="209.5" y="267.0">Keycloak</text>
<line class="node-detail-divider" x1="84.0" y1="288.0" x2="335.0" y2="288.0" />
<text class="node-detail" x="86.0" y="305.0">SET LOCAL synchronous_commit TO OFF</text>
</g>
<g id="node-pg">
<rect class="node-shape kind-datastore emphasis-warning role-control" data-evidence="211-215" x="115.5" y="420.0" width="188.0" height="71.0" /><ellipse class="node-shape kind-datastore emphasis-warning role-control" cx="209.5" cy="420.0" rx="94.0" ry="13.0" /><path class="storage-bottom" d="M 115.5 491.0 A 94.0 13.0 0 0 0 303.5 491.0" />
<text class="node-label" x="209.5" y="447.0">PostgreSQL</text>
<line class="node-detail-divider" x1="129.5" y1="468.0" x2="289.5" y2="468.0" />
<text class="node-detail" x="131.5" y="485.0">wal_writer_delay 200ms</text>
</g>
<g id="node-disk">
<rect class="node-shape kind-datastore emphasis-primary role-target" data-evidence="207-215" x="134.5" y="613.0" width="150.0" height="71.0" /><ellipse class="node-shape kind-datastore emphasis-primary role-target" cx="209.5" cy="613.0" rx="75.0" ry="13.0" /><path class="storage-bottom" d="M 134.5 684.0 A 75.0 13.0 0 0 0 284.5 684.0" />
<text class="node-label" x="209.5" y="640.0">디스크의 WAL</text>
<line class="node-detail-divider" x1="148.5" y1="661.0" x2="270.5" y2="661.0" />
<text class="node-detail" x="150.5" y="678.0">DB 에 실제로 존재 149건</text>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 7.3 KiB