Kord/Docs/Decisions/Dashboard_Architecture_gRPC.md

결정 사항: 대시보드-봇 통신 아키텍처 (gRPC Proxy)

배경 (Context)

대시보드(Next.js)와 멀티 인스턴스 샤딩 환경의 봇 간에 실시간 통신이 필요합니다. 대시보드는 특정 길드의 설정을 변경하거나 채널 목록을 조회해야 하지만, 봇이 여러 프로세스(Shard)로 쪼개져 있어 어떤 인스턴스가 해당 길드를 관리하는지 대시보드가 알기 어려운 문제가 있습니다.

결정된 사항 (Decision)

1. 통신 프로토콜: gRPC (HTTP/2) 선택

   • 강력한 타입 시스템(packages/grpc-contracts) 공유를 위해 선택했습니다.
   • 대량의 데이터 전송 및 실시간 양방향 통신 확장에 유리합니다.

2. Manager as API Proxy 패턴 채택

   • 구조: Dashboard <-> ShardingManager (gRPC Server) <-> Shards (IPC)
   • 모든 대시보드 요청은 단 하나의 포트(50051)를 가진 ShardingManager로 집중됩니다.
   • 매니저는 guildId 등의 키를 확인하여 내부적으로 broadcastEval 또는 IPC를 통해 해당 Shard에게 업무를 하달합니다.

3. 데이터 보관 전략: DB (Prisma) 중심

   • 실시간성이 극도로 중요한 요청 외의 설정값 변경은 DB를 우선 업데이트하고, 봇이 이를 캐시 동기화하도록 인터페이스를 구성합니다.

장점 (Pros)

• 인프라 간소화: 봇 인스턴스가 100개로 늘어나도 대시보드 입장에서는 50051 포트 하나만 바라보면 됩니다.
• 포트 충돌 방지: 각 샤드 워커마다 별도의 서버 포트를 할당할 필요가 없습니다.
• 코드 공유: 모노레포 구조를 통해 클라이언트와 서버가 동일한 .proto 계약을 공유합니다.

단점 (Cons)

• 매니저 오버헤드: 매니저가 모든 통신을 중계하므로, 통신량이 극도로 많아질 경우 매니저가 병목이 될 수 있습니다. (이 경우 추후 Redis Pub/Sub으로 전환 고려)

대안 (Alternatives)

• Redis Pub/Sub: 가장 유연하지만 추가 인프라(Redis) 관리가 필요합니다. 현재는 단일 서버 환경이므로 gRPC Proxy가 더 효율적이라고 판단했습니다.