# Architecture

> AI 에이전트는 구현 전 이 문서를 반드시 확인합니다.

## 프로젝트 개요

Antigravity AI 코딩 에이전트의 Discord 연동 시스템.
- AG Extension ↔ WebSocket Hub ↔ Discord Bot (실시간)
- AG Extension ↔ 파일 bridge ↔ Collector ↔ Gateway ↔ Discord Bot (레거시)

## 디렉토리 구조

```
gravity_control/
├── auth.py              # JWT 토큰 관리
├── hub.py               # WebSocket Hub (메시지 라우팅, 인스턴스 관리)
├── bot.py               # Discord 봇 (승인 UI, 채널 관리, Hub 핸들러)
├── gateway.py           # HTTP REST + /ws endpoint
├── bridge.py            # 파일 기반 IPC (레거시)
├── collector.py         # 원격 파일→HTTP 릴레이 (Phase 2 삭제 예정)
├── watcher.py           # Brain 디렉토리 변경 감시
├── config.py            # 환경변수 설정
├── main.py              # 진입점 (Bot + Hub + Watcher 시작)
├── parser.py            # Markdown→Discord 파서
├── extension/src/
│   ├── extension.ts     # 메인 Extension (3,300줄, 점진적 모듈화 진행)
│   ├── ws-client.ts     # WSBridgeClient (Hub 연결, 재연결, 메시지 큐)
│   └── sdk/             # Antigravity SDK (로컬 임베드)
└── .agents/references/  # AI 에이전트 레퍼런스 문서
```

## 핵심 모듈

| 모듈 | 역할 | 의존성 |
|------|------|--------|
| hub.py | WS 연결 관리, 메시지 라우팅, 인스턴스 번호 | auth.py |
| auth.py | JWT 토큰 생성/검증, registration code | - |
| bot.py | Discord UI, 승인 처리, 채팅 릴레이 | hub.py, bridge.py, parser.py |
| gateway.py | HTTP REST API + /ws endpoint | hub.py |
| ws-client.ts | Extension→Hub WS 클라이언트 | - |
| extension.ts | AG SDK 연동, step 감시, DOM observer | ws-client.ts, sdk/ |

## 데이터 흐름

```
    [Extension]
        │
   ┌────┴────┐
   │ WS Hub  │ ← 실시간 (preferred)
   │ (ws-client.ts → hub.py)
   └────┬────┘
        │                    ┌─────────────┐
        ├───────────────────→│  Discord Bot │→ Discord
        │                    └─────────────┘
   ┌────┴────┐
   │파일 bridge│ ← 레거시 fallback
   │(Collector → Gateway)
   └─────────┘
```