From 3d35b196920b4acf3ec514415b0221fcfdf0039d Mon Sep 17 00:00:00 2001
From: dj-oyu <68707227+dj-oyu@users.noreply.github.com>
Date: Sun, 22 Feb 2026 21:13:03 +0900
Subject: [PATCH] Add network architecture diagram to dev-preview skill

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 workspace/skills/dev-preview/SKILL.md | 32 +++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/workspace/skills/dev-preview/SKILL.md b/workspace/skills/dev-preview/SKILL.md
index 70de850be..db64e0d3b 100644
--- a/workspace/skills/dev-preview/SKILL.md
+++ b/workspace/skills/dev-preview/SKILL.md
@@ -8,6 +8,38 @@ metadata: {"nanobot":{"emoji":"🌐"}}
 
 Launch a local dev server as a background process, wait for it to become ready, and connect it to the Mini App dev preview proxy.
 
+## Network Architecture
+
+```
+User's phone (Telegram)
+  │
+  │  HTTPS (internet)
+  ▼
+Telegram Bot API server
+  │
+  │  Mini App WebView (iframe)
+  │  URL: https://BOT_DOMAIN/miniapp
+  ▼
+picoclaw server (VPS / local machine)
+  │
+  │  /miniapp/dev/*  →  reverse proxy (httputil.ReverseProxy)
+  │  strips /miniapp/dev prefix, forwards all HTTP methods
+  ▼
+localhost:PORT (dev server)
+  e.g. Vite on :5173, FastAPI on :8000, Go on :8080
+```
+
+**Request path**: User opens Dev tab in Mini App → iframe loads `/miniapp/dev/` → picoclaw reverse proxy → `localhost:PORT`
+
+**What works**: All HTTP methods (GET/POST/PUT/DELETE/PATCH), JSON APIs, form submissions, static files, SSE
+**What doesn't work**: WebSocket (reverse proxy limitation), non-HTTP protocols
+
+**Key points**:
+- The dev server only needs to bind to **localhost** — it is never exposed directly to the internet
+- picoclaw's reverse proxy handles the internet-facing HTTPS
+- The Mini App frontend sees API paths as `/miniapp/dev/api/...` — the `/miniapp/dev` prefix is stripped before forwarding
+- For CRUD apps, set the API base URL to `/miniapp/dev` in the frontend code
+
 ## Quickstart
 
 ```