gRPC 기반 AIoT 멀티 에이전트(Multi-Agent) 인터페이스 개발을 위한 사전 학습
- 사물인터넷(IoT) 환경과 지능형 에이전트들이 유기적으로 데이터를 주고받는 분산 AIoT 시스템을 설계하기 위해서는 빠르고, 가벼우며, 타입 안전성이 보장되는 통신 프로토콜이 필수적입니다.
- 본 프로젝트는 추후 개발할 gRPC 기반 AIoT 멀티 에이전트 인터페이스 모듈의 핵심 통신 기법을 선제적으로 실습하고 검증하기 위한 기술적 초석입니다.
후배 개발자 교육 및 공동 협업을 위한 가이드북
- 사용자 본인의 지식 내재화뿐만 아니라, 함께 개발에 참여할 후배 개발자들의 빠른 온보딩(Onboarding)과 체계적인 백엔드 통신 교육 자료 제공을 주요 목적으로 합니다.
- 이를 위해 단계적 예제와 한국어 주석, 상세 이론 원고(docs/MANUSCRIPT.md)를 꼼꼼하게 구성해 두고 있습니다.

📂 프로젝트 구조 및 학습 단계 (3-Step Curriculum)

본 예제는 데이터의 형태를 정하는 기초적인 단계부터 고성능 네트워크 통신까지 난이도별로 3단계 학습을 진행할 수 있도록 구조화되어 있습니다.

grpccanary/
├── README.md                    # 본 프로젝트 종합 소개 및 실행 가이드 (교육용)
├── go.mod / go.sum               # Go 모듈 의존성 정의 (Go 1.25.4+)
├── protoapi/                     # protoc로 컴파일 생성된 Go Stub 코드
├── examples/
│   ├── main.go                    # 학습 예제 통합 실행 진입점 (수동 전환)
│   ├── jsonexample/               # 1단계: JSON 데이터 다루기 실습 예제
│   ├── httpentity/                # 2단계: HTTP & Gin 웹 서버 실습 예제 (WIP)
│   └── grpcentity/                # 3단계: gRPC 통신 구현 실습 예제 (서버/클라이언트 데모)
│       └── protoapi.proto         # gRPC 인터페이스 정의서 (IDL)
└── docs/
    ├── MANUSCRIPT.md              # 학습 로드맵 및 각 단계별 심화 가이드로의 안내서
    ├── JSON.md                    # 1단계: JSON 데이터 다루기 상세 가이드
    ├── HTTP.md                    # 2단계: HTTP & Gin 웹 서버 상세 가이드
    └── GRPC.md                    # 3단계: gRPC 통신 구현 상세 가이드

1단계: JSON 데이터 다루기 (`examples/jsonexample`)

Go 표준 라이브러리인 encoding/json을 활용하여 구조체(Struct)와 JSON 데이터 간의 마샬링(Serialization) 및 언마샬링(Deserialization) 기법을 학습합니다.

2단계: HTTP & Gin 웹 서버 (`examples/httpentity`)

대중적인 Go 웹 프레임워크 gin-gonic을 활용해 RESTful API 사양을 구축하는 방법을 이해합니다. (현재 주석 해제 후 실습하도록 설계된 Work-in-Progress 단계)

3단계: gRPC 통신 구현 (`examples/grpcentity`)

.proto 정의를 바탕으로 통신 스키마 계약을 강제하고, Go 언어로 gRPC 서버를 띄워 클라이언트가 날짜/시간, 무작위 비밀번호 및 정수 데이터를 실시간 원격 호출로 송수신하는 분산 통신 기초를 학습합니다.
.proto 정의를 바탕으로 통신 스키마 계약을 강제하고, Go 언어로 gRPC 서버를 띄워 클라이언트가 날짜/시간, 무작위 비밀번호 및 정수 데이터를 실시간 원격 호출로 송수신하는 분산 통신 기초를 학습합니다.

🤖 AI 에이전트 협업 인프라 (`multi-agent-mux`)

본 저장소에는 학습용 Go 소스코드 외에도 AI 에이전트(Claude, Cline 등)가 TMUX와 MQTT 브로커를 활용해 스스로 개발하고 검수하는 다중 에이전트 협업 인프라가 함께 내장되어 있습니다.

AGENTS.md: AI 코딩 에이전트가 코드를 안전하게 수정할 수 있도록 제한하는 핵심 행동 지침(Surgical Changes, Simplicity First)입니다.
.agents/MULTI_AGENT_RULES.ko.md: 총괄 매니저, 개발 팀장, 리뷰어 팀장 간의 역할 정의 및 비동기 작업 결재 루프 프로토콜을 다룹니다.
resume_all.sh: 로컬에서 멈춘 작업 에이전트의 세션을 동적으로 한 번에 복원해 주는 자동화 복구 스크립트입니다. (로컬 전용 헬퍼로 Git 추적에서 제외됨)

🚀 실행 및 실습 방법

1. 사전 준비사항

Go 개발 환경이 필요합니다. (버전 1.25.4 이상 권장)
리포지토리 루트에서 다음 명령어로 의존성 모듈을 설치합니다.
```
go mod download
```

2. 실습 예제 실행 방법 (진입점 전환)

이 프로젝트는 교육적 목적을 위해 하나의 main.go 파일 안에서 주석 처리를 통해 학습 단계를 수동 전환하여 실행하도록 설계되어 있습니다.

examples/main.go 파일을 엽니다.
아래와 같이 실행하고자 하는 예제의 주석을 해제하고 다른 예제는 주석 처리합니다.
- JSON 예제 실행 시: jsonexample.JsonParsingExample() 활성화
- gRPC 예제 실행 시: grpcSample() 활성화 (미사용 import 에러를 피하기 위해 jsonexample import는 주석 처리 필요)
루트 디렉토리에서 다음 명령어로 실행합니다:
```
go run ./examples
```

3. gRPC 예제 동작 흐름 및 기대 출력

gRPC 예제 실행 시, 서버가 백업 고루틴으로 :8080 포트에 대기한 후 클라이언트가 접속하여 다음과 같은 출력을 냅니다.

Serving requests...
Client:
Server Date and Time: 2026-07-12 20:00:00.123456789 +0900 KST m=+1.000000001
Random Password: &c(D7f/G#s%d
Received sensing data - Device: sensor-room-01, Temp: 24.50°C, Humid: 52.30%
Sensing Update Success: true
Sensing Update Message: Sensing data updated successfully for device sensor-room-01

4. 트러블슈팅

module grpccanary: package ... is not in GOROOT:
- 모듈 로드 에러가 발생한 경우, 리포지토리 루트 경로(작업 디렉토리)에서 명령어를 올바르게 실행했는지 재확인하고, go clean -modcache 후 go mod tidy를 수행해 보십시오.

📚 추가 학습 리소스

docs/MANUSCRIPT.md: JSON, HTTP, gRPC 통신의 원리와 배경지식(REST의 한계와 gRPC 도입 이유 등)을 담은 학습 로드맵 및 가이드 안내서
docs/JSON.md: 1단계 JSON 데이터 다루기 상세 학습 가이드
docs/HTTP.md: 2단계 HTTP & Gin 웹 프레임워크 상세 학습 가이드
docs/GRPC.md: 3단계 gRPC & Protobuf 상세 학습 가이드 (컴파일 절차 및 소스코드 구현체 분석 포함)
examples/grpcentity/README.md: gRPC 실습 디렉토리 안내 및 docs/GRPC.md 심화 가이드로의 링크

README.md

grpccanary: gRPC & Multi-Agent Interface Study Repository

🎯 프로젝트 목적 및 배경