Add "Architecture"

2026-03-16 02:15:33 +00:00
parent b4712f8406
commit c3007f28fb

51
Architecture.md Normal file

@@ -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를 건드리지 말 것 (무한 루프 또는 회귀 발생).