iop/docs/architecture.md

IOP Architecture

개요

IOP(Inference Operations Platform)는 분산 AI 모델 추론을 위한 플랫폼이다. 단일 서비스가 아니라 협력하는 여러 앱으로 구성된다.

  Client (OpenAI SDK)
       │
       ▼
  ┌─────────┐
  │  edge   │  OpenAI-compatible HTTP API
  └────┬────┘
       │ IOP TCP + Protobuf + mTLS
       ▼
  ┌──────────────────┐
  │  control-plane   │  노드 등록 / 정책 / 스케줄링
  └────────┬─────────┘
           │
     ┌─────┴──────┐
     ▼            ▼
  ┌──────┐    ┌──────┐   (N개의 node)
  │ node │    │ node │
  └──┬───┘    └──┬───┘
     │            │
  ┌──┴──┐      ┌──┴──┐
  │mock │      │ollama│  어댑터
  │cli  │      │vllm  │
  └─────┘      └──────┘

  ┌────────┐
  │ worker │  비동기 작업 처리
  └────────┘

내부 통신 프로토콜

와이어 포맷

Frame: [4 bytes big-endian uint32: length] [payload]
Payload: JSON-encoded Envelope
Envelope.Payload: JSON-encoded inner message

TODO: Payload 인코딩을 protobuf로 교체 (proto/iop/runtime.proto 참고)

메시지 타입

Type	방향	설명
run.request	client → node	추론 실행 요청
run.event	node → client	스트리밍 이벤트 (start/delta/complete/error)
heartbeat	양방향	연결 유지 (30초 간격)
cancel.request	client → node	실행 중단 요청
register.request	node → edge	사전 발급 token 기반 등록 요청
register.response	edge → node	등록 수락 여부와 중앙 관리 node 설정 응답
error	node → client	에러 응답

mTLS

tls:
  enabled: true
  cert: certs/node.crt
  key:  certs/node.key
  ca:   certs/ca.crt

tls.enabled: true로 설정하면 RequireAndVerifyClientCert (mTLS) 모드로 동작.

apps/node 내부 구조

Hexagonal Architecture

         ┌───────────────────────────────┐
         │           node.Node           │  (application core)
         │                               │
  TCP    │  transport.Handler interface  │
─────────►  OnRunRequest()               │
  client │  OnCancel()                   │
         └───────┬───────────────────────┘
                 │
          router.Resolve()     → ExecutionSpec
                 │
          adapter.Execute()    → RuntimeEvent stream
                 │
          store.CompleteRun()  → SQLite

어댑터 패턴

type Adapter interface {
    Name() string
    Capabilities(ctx) (Capabilities, error)
    Execute(ctx, spec ExecutionSpec, sink EventSink) error
}

새 어댑터를 추가하려면:

1. apps/node/internal/adapters/<name>/ 패키지 생성
2. runtime.Adapter 인터페이스 구현
3. bootstrap/module.go에서 Registry에 등록

라이브러리 선택

라이브러리	역할
go.uber.org/fx	의존성 주입
go.uber.org/zap	구조화 로깅
github.com/spf13/cobra	CLI
github.com/spf13/viper	설정 파일
google.golang.org/protobuf	Protobuf (spec용)
github.com/prometheus/client_golang	메트릭
modernc.org/sqlite	실행 이력 저장

금지 사항

• gRPC (grpc-go) 사용 금지
• WebSocket 기본 transport 사용 금지
• Actor framework 사용 금지
• External worker pool 사용 금지
• FSM framework 사용 금지
• Plugin framework 사용 금지
• Kubernetes 의존성 금지