From c3007f28fb52f5dd8d1813d1d9193a7b74d9a860 Mon Sep 17 00:00:00 2001
From: Variet Main Worker <variet_worker@variet.net>
Date: Mon, 16 Mar 2026 02:15:33 +0000
Subject: [PATCH] Add "Architecture"

---
 Architecture.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 Architecture.md

diff --git a/Architecture.md b/Architecture.md
new file mode 100644
index 0000000..b7455e5
--- /dev/null
+++ b/Architecture.md
@@ -0,0 +1,51 @@
+# Gravity Control — Architecture
+
+## 시스템 구조
+
+```
+AG IDE (Antigravity)
+  ├── Extension (extension.ts)  ← Bridge 핵심 (v0.3.12)
+  │     ├── setupMonitor()     ← 5초 폴링
+  │     ├── step_probe         ← WAITING step 감지
+  │     ├── DOM Observer       ← 렌더러 버튼 감지
+  │     ├── processResponseFile() ← Discord 응답 처리
+  │     └── tryApprovalStrategies() ← RPC 실행
+  ├── bridge/ (파일 시스템 IPC)
+  │     ├── pending/*.json
+  │     ├── response/*.json
+  │     ├── snapshot/*.json
+  │     └── register/*.json
+  └── Bot (bot.py) ← Discord 통신
+        ├── pending_approval_scanner
+        ├── auto_approve_scanner
+        └── snapshot_scanner
+
+Collector (collector.py) ← Local ↔ Gateway 중계
+Gateway (gateway.py) ← VPS HTTP API (Docker + Caddy)
+```
+
+## 핵심 문서
+
+| 문서 | 내용 |
+|------|------|
+| `docs/approval-flow.md` | 승인 시스템 전체 Flow, 상태 변수, 전이 다이어그램 |
+| `.agents/references/known-issues.md` | 모든 이슈/교훈 SSOT (50+ 항목) |
+| `docs/usage-guide.md` | 사용 가이드 |
+| `docs/tech-stack.md` | 기술 스택 정보 |
+
+## 승인 Flow 개요
+
+자세한 내용 → `docs/approval-flow.md`
+
+**2가지 pending 생성 경로:**
+1. Step Probe → `writePendingApproval()` (메모리 dedup 포함)
+2. DOM Observer → HTTP POST `/pending` (파일 기반 dedup만)
+
+**핵심 상태 변수 (5개, 모듈 레벨):**
+- `lastPendingStepIndex` — step 재감지 방지
+- `stallProbed` — 같은 stall에서 재probe 방지
+- `sawRunningAfterPending` — auto_resolve gate
+- `sessionStalled` — stall 상태 플래그
+- `recentPendingSteps` — 메모리 dedup Map (60초 TTL)
+
+**위험 지점:** processResponseFile의 상태 리셋 — `sawRunningAfterPending = true`만 설정. 절대 lastPendingStepIndex나 stallProbed를 건드리지 말 것 (무한 루프 또는 회귀 발생).