# AIoT gRPC 고성능 통신 모듈 — 프로젝트 빠른 파악

> 이 프로젝트에 새로 투입된 당신을 위한 프롬프트입니다.
> AI 에이전트(Claude Code, Codex 등)에게 이 내용을 전달하면 프로젝트를 빠르게 이해하고 작업할 수 있습니다.

---

## 프로젝트 한 줄 요약

**AI Agent와 IoT 디바이스 간 통신을 위해, TCP 기반 gRPC(HTTP/2)의 전송 계층을 QUIC(HTTP/3)으로 교체한 고성능 통신 모듈을 Go로 구현하고, 이를 활용한 엣지 게이트웨이 아키텍처를 설계·구현·성능 검증하는 연구 프로젝트.**

---

## 핵심 정보

| 항목 | 내용 |
|------|------|
| **언어** | Go 1.22+ |
| **통신 프로토콜** | gRPC over HTTP/3 (QUIC) + Protocol Buffers v3 |
| **QUIC 라이브러리** | `github.com/quic-go/quic-go` |
| **비교 대상** | gRPC/HTTP3 vs gRPC/HTTP2 vs REST/HTTP2 vs REST/HTTP1.1 |
| **연구 범위** | 통신 모듈 구현 + 엣지 게이트웨이 + 6-way 정량 성능 비교 |
| **평가 시나리오** | ① IoT 데이터 전송 (수 KB~수 MB, 스트리밍) ② AI Agent RPC (수 KB, Unary, burst) |
| **네트워크 조건** | Ideal/LAN/WAN-Low/WAN-High/Lossy (tc로 시뮬레이션) |

---

## 문서 구성 (읽는 순서)

1. **`CLAUDE.md`** — 연구 방향, 동기, 목표, 평가 지표, 코드 정책. **모든 작업 시작 시 필독**.
2. **`IMPLEMENTATION.md`** — 디렉터리 구조, 네이밍, 워크플로우, Makefile, 코드 패턴. **코드 작성/수정 시 필독**.
3. **`BACKGROUND.md`** — 연구 배경 (AI Agent 트래픽 폭증, TCP 한계, QUIC 등장). **연구 동기 이해 시 참조**.
4. **`참고/SGS/README.md`** — 선행 연구 (스마트팜 해충 탐지, gRPC vs REST 비교). **차별성 파악 시 참조**.

특별 디렉터리:
- **`docs/decisions/`** — 설계 결정 기록 (ADR). 중요한 설계 변경 전후 확인.
- **`docs/open-questions.md`** — 미해결 탐색 주제. 새 실험 기획 시 참조.
- **`src/`** — **다른 에이전트가 UI 프로그램 구현 중이므로 건드리지 말 것.**

---

## 연구 동기 (왜 이 프로젝트인가)

1. **AI Agent 격리 → 통신 폭증**: 보안을 위해 각 Agent를 컨테이너에 격리하면 IPC가 전부 네트워크 통신으로 전환되어 통신 건수가 폭증함
2. **서브에이전트 아키텍처 → 통신 빈도 증가**: 컨텍스트 한계 극복을 위해 서브에이전트 + RAG 패턴이 표준화되면서 Agent 간/Agent-서비스 간 통신이 더 빈번해짐
3. **24/7 가동 → 동시 트래픽 누적**: 사람이 쉴 때도 Agent는 일하므로 동시간 네트워크 사용량이 급증

→ TCP 기반 HTTP/2(gRPC)의 HoL Blocking, 연결 수립 비용, 연결 고정 문제가 병목이 됨
→ QUIC(HTTP/3)이 0-RTT, 스트림 독립성, 연결 마이그레이션으로 이 문제들을 해결 가능
→ **그러나 AIoT 환경에서의 gRPC over QUIC 실증 연구는 아직 부재함** — 이 gap을 메우는 것이 본 연구

---

## 제안 2가지

### 제안 ①: gRPC over QUIC 통신 모듈
- QUIC의 0-RTT, HoL Blocking 해소, 연결 마이그레이션을 AIoT 환경에서 정량 검증
- 6가지 시스템 간 latency(P50/P95/P99), throughput(RPS), connection overhead 비교
- **성공 기준**: 각 측정값 최소 30회 반복, 95% 신뢰 구간 제시

### 제안 ②: gRPC 엣지 게이트웨이 아키텍처
- 프로토콜 변환 (MQTT/CoAP → Protobuf) + 정적 룰 기반 서비스 라우팅
- gRPC-QUIC 모듈을 사용해 백엔드와 통신
- LLM 기반 동적 라우팅은 범위 밖 (정적 룰 한정)

---

## 기술적 주의사항

### 가장 큰 리스크
**quic-go의 `quic.Stream`과 `net.Conn` 인터페이스 호환성.**
- quic-go Stream은 `net.Conn`의 deadline 설정, LocalAddr/RemoteAddr, Close(반쪽 종료) 방식이 다름
- 이 문제가 해결되지 않으면 QUIC 구현이 불가능함 → HTTP/2(gRPC-H2)만으로 게이트웨이 먼저 검증하고 QUIC은 별도 실험으로 분리

### 계층 분리 필수
```
Transport (QUIC/TCP) → Protocol (gRPC/HTTP) → Serialization (Protobuf/JSON) → Business Logic
```
전송 계층은 인터페이스로 추상화하여 QUIC↔TCP 교체 가능하게 할 것.

### 금지 사항
- `gen/` 디렉터리 직접 수정 금지. `.proto` 수정 후 `make proto`로 재생성.
- `panic` 사용 금지 (초기화 코드 제외)
- 전역 변수 설정 금지. `config` 구조체 사용.
- 미사용 의존성 추가 금지. `go mod tidy` 후 커밋.
- **`src/` 디렉터리 수정 금지** (다른 에이전트가 UI 구현 중)

---

## 자주 하는 작업

### 새 RPC 추가
1. `proto/aiot/{module}/{service}.proto`에 정의
2. `make proto` → `gen/` 생성
3. `internal/server/`에 핸들러 구현
4. 인터셉터(`internal/middleware/metrics.go`)로 latency 측정 자동화
5. 단위 테스트 → 벤치마크 시나리오 추가

### 서버 실행
```bash
go run ./cmd/server --transport=quic --port=50051   # gRPC over QUIC
go run ./cmd/server --transport=h2   --port=50052   # gRPC over HTTP/2
go run ./cmd/rest-server                             # REST 비교군
```

### 네트워크 조건
```bash
sudo ./scripts/tc-setup.sh --delay 50ms --loss 1% --interface eth0
sudo ./scripts/tc-reset.sh --interface eth0
```

---

## 선행 연구(SGS) 대비 차별성

| 항목 | 선행 연구 | 본 연구 |
|------|----------|--------|
| 전송 계층 | HTTP/2 (TCP) | **HTTP/3 (QUIC) 추가** |
| 시나리오 | 스마트팜 단일 | **IoT + AI Agent RPC 이중** |
| 게이트웨이 | 개념 제시 | **구현·정량 검증** |
| 평가 지표 | 응답 시간, 전송량 | **+ 0-RTT, HoL 내성, 연결 마이그레이션** |
| 비교 시스템 | 3개 | **6개** |

---

## 파일 상태

| 파일 | 목적 | 작성 완료 |
|------|------|----------|
| `CLAUDE.md` | 연구 방향·정책 | ✅ |
| `BACKGROUND.md` | 연구 배경 (발표 가능) | ✅ (1차 개선 완료) |
| `IMPLEMENTATION.md` | 구현 세부 사항 | ✅ |
| `FEEDBACK.md` | 문서 비평 | ✅ |
| `TASK_LIST.md` | 작업 리스트 | ✅ |
| `참고/SGS/README.md` | 선행 연구 | ✅ |

## 추후 보강 예정 (부록 A 참조)
- 정량적 데이터 근거 (통신 빈도 추정치, 기존 연구 인용)
- AI Agent 트래픽 특성 구체화 (RPC 수, latency 요구사항)
- AI Agent + IoT 두 시나리오 연결 논리 강화