From 0a686fd3e50e07876d9838cb4c23706440273af3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=D0=90=D0=BD=D1=82=D0=BE=D0=BD=20=D0=A2=D1=80=D0=BE=D1=88?=
 =?UTF-8?q?=D0=B8=D0=BD?= <i@atroshin.ru>
Date: Wed, 28 Oct 2026 00:35:50 +0300
Subject: [PATCH] docs: add card-access-path architecture diagrams to the
 READMEs

Self-contained SVGs (EN + RU) showing Browser -> HTTP :8080 ->
pysim-simple-server -> PC/SC -> card reader -> UICC/SIM, referenced
from the top of each README.  They ride the package's whole-docs tree,
so the links resolve in the release zip too.
---
 README.md                |  2 ++
 README_RUS.md            |  2 ++
 docs/architecture_en.svg | 30 ++++++++++++++++++++++++++++++
 docs/architecture_ru.svg | 30 ++++++++++++++++++++++++++++++
 4 files changed, 64 insertions(+)
 create mode 100644 docs/architecture_en.svg
 create mode 100644 docs/architecture_ru.svg

diff --git a/README.md b/README.md
index 966a4b2..8bdd8ae 100644
--- a/README.md
+++ b/README.md
@@ -15,6 +15,8 @@ SIMple is a workbench for UICC/SIM card specialists: an offline HTML/JS frontend
 
 **Demo:** [simple.atroshin.ru](https://simple.atroshin.ru) — the frontend alone, for experimenting. Install the server (below) for card-reader functions.
 
+![Card access path: Browser (SIMple PWA) → HTTP :8080 → pysim-simple-server (wraps pySim) → PC/SC → card reader → UICC/SIM card](docs/architecture_en.svg)
+
 ## Prerequisites
 
 - **Python 3.9+** with `pip`, and **Git** — the app runs on 3.9+, but the **SCP81 TLS-PSK listener needs Python 3.13+** (`ssl`'s PSK callbacks).
diff --git a/README_RUS.md b/README_RUS.md
index 3222969..0a7d65c 100644
--- a/README_RUS.md
+++ b/README_RUS.md
@@ -15,6 +15,8 @@ SIMple — инструментарий для специалистов по UIC
 
 **Демо:** [simple.atroshin.ru](https://simple.atroshin.ru) — только фронтенд, для экспериментов. Для функций картридера установите сервер (ниже).
 
+![Путь доступа к карте: Браузер (PWA SIMple) → HTTP :8080 → pysim-simple-server (оборачивает pySim) → PC/SC → картридер → карта UICC/SIM](docs/architecture_ru.svg)
+
 ## Требования
 
 - **Python 3.9+** с `pip`, и **Git** — приложение работает на 3.9+, но **SCP81 TLS-PSK-слушателю нужен Python 3.13+** (PSK-callback'и `ssl`).
diff --git a/docs/architecture_en.svg b/docs/architecture_en.svg
new file mode 100644
index 0000000..6546a7a
--- /dev/null
+++ b/docs/architecture_en.svg
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="540" viewBox="0 0 960 540" role="img" aria-labelledby="diagram-title diagram-desc" font-family="'Segoe UI', 'Helvetica Neue', Arial, 'DejaVu Sans', sans-serif">
+  <title id="diagram-title">SIMple: card access path</title>
+  <desc id="diagram-desc">Browser (SIMple PWA) talks to pysim-simple-server over HTTP on :8080; the server wraps pySim and talks to the card reader over PC/SC, which talks to the UICC/SIM card.</desc>
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 Z" fill="#64748b"/>
+    </marker>
+  </defs>
+  <rect x="1" y="1" width="958" height="538" rx="18" fill="#ffffff" stroke="#e2e8f0" stroke-width="1.5"/>
+  <text x="480" y="30" text-anchor="middle" font-size="14" fill="#475569">card access path</text>
+
+  <rect x="250" y="48" width="460" height="76" rx="12" fill="#eff6ff" stroke="#93c5fd" stroke-width="1.5"/>
+  <text x="480" y="92" text-anchor="middle" font-size="20" font-weight="600" fill="#0f172a">Browser (SIMple PWA)</text>
+  <line x1="480" y1="124" x2="480" y2="172" stroke="#64748b" stroke-width="2" marker-end="url(#arrow)"/>
+  <text x="492" y="152" font-size="14" fill="#64748b" font-family="'Cascadia Mono', Consolas, 'DejaVu Sans Mono', monospace">HTTP :8080</text>
+
+  <rect x="250" y="176" width="460" height="80" rx="12" fill="#f5f3ff" stroke="#c4b5fd" stroke-width="1.5"/>
+  <text x="480" y="210" text-anchor="middle" font-size="19" font-weight="600" fill="#0f172a" font-family="'Cascadia Mono', Consolas, 'DejaVu Sans Mono', monospace">pysim-simple-server</text>
+  <text x="480" y="236" text-anchor="middle" font-size="14" fill="#475569">serves the PWA + JSON API · wraps pySim</text>
+  <line x1="480" y1="256" x2="480" y2="304" stroke="#64748b" stroke-width="2" marker-end="url(#arrow)"/>
+  <text x="492" y="284" font-size="14" fill="#64748b" font-family="'Cascadia Mono', Consolas, 'DejaVu Sans Mono', monospace">PC/SC</text>
+
+  <rect x="250" y="308" width="460" height="76" rx="12" fill="#ecfdf5" stroke="#6ee7b7" stroke-width="1.5"/>
+  <text x="480" y="352" text-anchor="middle" font-size="20" font-weight="600" fill="#0f172a">Card reader</text>
+  <line x1="480" y1="384" x2="480" y2="432" stroke="#64748b" stroke-width="2" marker-end="url(#arrow)"/>
+
+  <rect x="250" y="436" width="460" height="76" rx="12" fill="#fffbeb" stroke="#fcd34d" stroke-width="1.5"/>
+  <text x="480" y="480" text-anchor="middle" font-size="20" font-weight="600" fill="#0f172a">UICC/SIM card</text>
+</svg>
diff --git a/docs/architecture_ru.svg b/docs/architecture_ru.svg
new file mode 100644
index 0000000..f22de11
--- /dev/null
+++ b/docs/architecture_ru.svg
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="540" viewBox="0 0 960 540" role="img" aria-labelledby="diagram-title diagram-desc" font-family="'Segoe UI', 'Helvetica Neue', Arial, 'DejaVu Sans', sans-serif">
+  <title id="diagram-title">SIMple: путь доступа к карте</title>
+  <desc id="diagram-desc">Браузер (PWA SIMple) обращается к pysim-simple-server по HTTP на :8080; сервер оборачивает pySim и по PC/SC общается с картридером, а тот — с картой UICC/SIM.</desc>
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 Z" fill="#64748b"/>
+    </marker>
+  </defs>
+  <rect x="1" y="1" width="958" height="538" rx="18" fill="#ffffff" stroke="#e2e8f0" stroke-width="1.5"/>
+  <text x="480" y="30" text-anchor="middle" font-size="14" fill="#475569">путь доступа к карте</text>
+
+  <rect x="250" y="48" width="460" height="76" rx="12" fill="#eff6ff" stroke="#93c5fd" stroke-width="1.5"/>
+  <text x="480" y="92" text-anchor="middle" font-size="20" font-weight="600" fill="#0f172a">Браузер (PWA SIMple)</text>
+  <line x1="480" y1="124" x2="480" y2="172" stroke="#64748b" stroke-width="2" marker-end="url(#arrow)"/>
+  <text x="492" y="152" font-size="14" fill="#64748b" font-family="'Cascadia Mono', Consolas, 'DejaVu Sans Mono', monospace">HTTP :8080</text>
+
+  <rect x="250" y="176" width="460" height="80" rx="12" fill="#f5f3ff" stroke="#c4b5fd" stroke-width="1.5"/>
+  <text x="480" y="210" text-anchor="middle" font-size="19" font-weight="600" fill="#0f172a" font-family="'Cascadia Mono', Consolas, 'DejaVu Sans Mono', monospace">pysim-simple-server</text>
+  <text x="480" y="236" text-anchor="middle" font-size="14" fill="#475569">раздаёт PWA + JSON API · оборачивает pySim</text>
+  <line x1="480" y1="256" x2="480" y2="304" stroke="#64748b" stroke-width="2" marker-end="url(#arrow)"/>
+  <text x="492" y="284" font-size="14" fill="#64748b" font-family="'Cascadia Mono', Consolas, 'DejaVu Sans Mono', monospace">PC/SC</text>
+
+  <rect x="250" y="308" width="460" height="76" rx="12" fill="#ecfdf5" stroke="#6ee7b7" stroke-width="1.5"/>
+  <text x="480" y="352" text-anchor="middle" font-size="20" font-weight="600" fill="#0f172a">Картридер</text>
+  <line x1="480" y1="384" x2="480" y2="432" stroke="#64748b" stroke-width="2" marker-end="url(#arrow)"/>
+
+  <rect x="250" y="436" width="460" height="76" rx="12" fill="#fffbeb" stroke="#fcd34d" stroke-width="1.5"/>
+  <text x="480" y="480" text-anchor="middle" font-size="20" font-weight="600" fill="#0f172a">Карта UICC/SIM</text>
+</svg>