iop/agent-ops/rules/project/domain/client/rules.md

---
domain: client
last_rule_review_commit: 49872ae120627c47175194e837d90f8915d67397
last_rule_updated_at: 2026-06-01
---

# client

## 목적 / 책임

IOP의 공식 Flutter client UI/UX 영역이다. Control Plane HTTP/WS endpoint를 소비해 운영 상태를 표시하고, Flutter Web/Desktop/Mobile shell, Client-Control Plane proto-socket client, client-side integration host를 관리한다.

## 포함 경로

- `apps/client/lib/` — Flutter app source, build-time client config, proto-socket wire client, generated Dart proto 사용, client integration code
- `apps/client/lib/src/integrations/` — client-side external integration host와 Mattermost-compatible push integration
- `packages/flutter/iop_console/` — IOP-owned embeddable Flutter console package, left-rail shell, agent panel widget
- `apps/client/test/` — Flutter widget/config/wire/integration 테스트
- `apps/client/web/` — Flutter Web shell과 web asset
- `apps/client/assets/` — Flutter asset placeholder와 local-only Mattermost smoke credential mount 지점
- `apps/client/android/` — Android runner와 Firebase 설정 표면
- `apps/client/ios/` — iOS runner scaffold
- `apps/client/macos/` — macOS runner scaffold
- `apps/client/linux/` — Linux runner scaffold
- `apps/client/windows/` — Windows runner scaffold
- `apps/client/pubspec.yaml` — Flutter dependency와 asset 설정
- `apps/client/pubspec.lock` — Flutter dependency lock
- `apps/client/analysis_options.yaml` — Dart/Flutter lint 설정
- `apps/client/Dockerfile` — Flutter Web build와 nginx static serving 이미지
- `apps/client/nginx.conf` — Flutter Web 정적 서빙 설정
- `apps/client/README.md` — client 개발, 검증, build-time 설정 안내

## 제외 경로

- `apps/control-plane/` — Client가 연결하는 Control Plane server와 wire endpoint 구현 영역
- `apps/edge/` — Edge-local 실행 그룹과 node registry/operation 소유자
- `apps/node/` — adapter execution과 runtime session 소유자
- `packages/go/**` — Go 공통 설정/관측성/정책 helper 영역.
- `proto/iop/` — protobuf 계약 원본
- `proto/gen/iop/` — Go protobuf 생성물
- `scripts/dev/` — repo 내부 개발 실행 helper 영역
- `docker-compose.yml` — local dev stack 조립과 검증 환경 영역

## 주요 구성 요소

- `IopClientApp` / `ClientHomePage` — IOP client Flutter app shell과 현재 wire status UI
- `ClientConfig` — `--dart-define` 기반 Control Plane HTTP/WS URL 설정
- `ClientWireClient` — Control Plane `/client` WebSocket proto-socket client와 hello request helper
- `clientParserMap` — Client-Control Plane proto message parser map
- `apps/client/lib/gen/proto/iop/*.dart` — `make proto-dart`로 생성되는 Dart protobuf binding
- `MattermostPushHostIntegration` / `MattermostPushPluginClient` — Nexo messaging / Mattermost-compatible push integration host
- `IopConsoleShell` — IOP 단독 앱과 외부 임베더가 공유할 수 있는 좌측 rail console shell
- `IopAgentPanel` — 공통 `agent_shell` package를 사용한 IOP 운영 agent panel scaffold
- `apps/client/Dockerfile` — sibling `proto-socket/dart` path dependency를 포함해 Flutter Web artifact를 빌드하는 이미지

## 유지할 패턴

- Client는 Control Plane을 통해 Edge/Node 운영 상태를 조회한다. Client에서 Edge-Node TCP transport나 Node execution 경로에 직접 붙지 않는다.
- Client-Control Plane native 경계는 `/client` WebSocket proto-socket과 `ClientHelloRequest`/`ClientHelloResponse` baseline을 따른다.
- Client-Control Plane wire 상세는 `agent-contract/inner/client-control-plane-wire.md`를 기준으로 확인한다.
- Control Plane URL은 `IOP_CONTROL_PLANE_HTTP_URL`, `IOP_CONTROL_PLANE_WIRE_URL` `--dart-define`으로 주입한다. 실제 환경값이나 private endpoint를 tracked source에 고정하지 않는다.
- Dart protobuf binding은 `proto/iop/*.proto`에서 생성한다. proto 계약 변경 시 `make proto-dart` 산출물과 Go 생성물 갱신 여부를 함께 확인한다.
- `apps/client/lib/gen/proto/iop/*.dart` 생성물은 사람이 직접 수정하지 않는다.
- Mattermost/Nexo 연동은 `lib/src/integrations/` 아래 통합 모듈로 둔다. IOP client app shell을 NomadCode 전용 UX로 바꾸지 않는다.
- `packages/flutter/iop_console`은 IOP UI의 공개 Flutter widget/package 경계다. IOP 단독 앱은 이 package를 mount하고, 외부 소비자는 이 package 또는 동등한 IOP-owned widget boundary를 통해 조립한다.
- `agent_shell`은 제품 중립 chat/agent interaction shell로만 사용한다. IOP client에는 IOP 운영/유지보수 capability와 panel widget을 담고, NomadCode의 workbench/right-rail layout은 가져오지 않는다.
- IOP UI를 NomadCode에 제공해야 할 때는 IOP-owned widget/package 경계로 노출하고, NomadCode product shell 내부 구현을 IOP client에 복제하지 않는다.
- client 변경 후에는 변경 범위에 맞게 `flutter test` 또는 `make client-test`를 확인한다. Web build, Dockerfile, compose 경로를 바꾸면 `make client-build-web` 또는 해당 build 경로를 확인한다.

## 다른 도메인과의 경계

- **control-plane**: Control Plane은 `/client` WS endpoint, HTTP 상태 endpoint, Edge connection registry를 제공한다. Client는 이를 소비하는 UI/UX와 client-side wire wrapper를 소유한다.
- **platform-common**: protobuf 원본 계약은 platform-common이 소유한다. Client는 해당 계약에서 생성된 Dart binding을 사용한다.
- **agent-shell**: `agent_shell` sibling package는 공통 chat/agent shell widget과 message model만 제공한다. IOP-specific operation semantics와 Control Plane 연동은 client domain에 남긴다.
- **platform-common**: `packages/flutter/iop_console`은 Flutter UI package이므로 Go 공통 설정/proto/helper 패키지와 섞지 않는다.
- **NomadCode**: NomadCode는 IOP의 중요한 UI 소비자일 수 있지만, IOP client는 NomadCode 전용 navigation, workspace, web context UX를 소유하지 않는다.
- **testing**: client test/build target, `scripts/dev/web.sh`, compose 기반 local dev 검증 기준은 testing domain rule을 따른다.
- **edge/node**: Client는 Edge와 Node를 직접 제어하지 않고 Control Plane 표면을 통해 관찰/명령한다.

## 금지 사항

- Client에서 Edge 또는 Node TCP/protobuf 내부 transport에 직접 연결하지 않는다.
- Client를 NomadCode 전용 shell, project workspace, diff/PR/branch/commit UX 중심으로 만들지 않는다.
- NomadCode right rail, workspace tab, web context 조작 UX를 IOP client domain에 직접 구현하지 않는다.
- `apps/client/lib/gen/proto/iop/*.dart` 생성 파일을 직접 수정하지 않는다.
- Mattermost smoke credential 같은 local/private 값을 tracked asset이나 README에 기록하지 않는다.
- Control Plane server 상태 저장, Edge registry, run dispatch, stream relay 구현을 client domain으로 끌어오지 않는다.