# 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

```yaml
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
```

### 어댑터 패턴

```go
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 의존성 금지