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

---
domain: client
last_rule_review_commit: 7ca329ac9e03bf7cfebfac4517559fc1e2f0bca8
last_rule_updated_at: 2026-07-14
---

# client

## 목적 / 책임

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

## 포함 경로

- `apps/client/lib/` — Flutter app source, build-time client config, Control Plane HTTP status repository/controller, proto-socket wire client, generated Dart proto 사용, client integration code
- `apps/client/lib/iop_wire/` — Client-Control Plane proto-socket client와 parser map
- `apps/client/lib/widgets/` — Edge/Node/runtime/execution-log 운영 panel widget
- `apps/client/lib/src/integrations/` — client-side external integration host와 Nexo notification 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
- `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
- `ControlPlaneStatusController` / `ControlPlaneStatusRepository` — Control Plane HTTP status/operation view 로딩과 UI state 관리
- `EdgeRegistryView` / `EdgeStatusResponseView` / `FleetStatusResponseView` / `EdgeOperationsResponseView` — Control Plane JSON view를 client-side DTO로 정규화
- `EdgesPanel` / `NodesPanel` / `RuntimePanel` / `ExecutionLogsPanel` — 운영 상태를 스캔 가능한 panel UI로 표시하는 widget
- `apps/client/lib/gen/proto/iop/*.dart` — `make proto-dart`로 생성되는 Dart protobuf binding
- `NexoNotificationHostIntegration` / `NexoNotificationPluginClient` / `NexoNotificationClient` — Nexo messaging notification stream integration host
- `IopConsoleShell` — IOP 단독 앱과 외부 임베더가 공유할 수 있는 좌측 rail console shell
- `IopAgentPanel` — 공통 `agent_shell` package를 사용한 IOP 운영 agent panel scaffold
- `IopConsoleConfig` / `IopCapabilityPack` / `IopConsoleOverview` — IOP console package의 embeddable configuration, capability, overview widget boundary
- `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 HTTP 상태 조회는 repository/controller/DTO 경계에서 처리하고, panel widget이 raw JSON parsing이나 endpoint path 조립을 직접 소유하지 않도록 유지한다.
- 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` 생성물은 사람이 직접 수정하지 않는다.
- Nexo notification 연동은 `lib/src/integrations/` 아래 통합 모듈로 둔다. Mattermost-compatible 인증/등록/서버 책임은 Nexo 쪽 경계에 남기고 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 패키지와 섞지 않는다.
- **Nexo**: Nexo/Mattermost-compatible notification auth, registration, server integration은 외부 integration boundary에 두고, client domain은 notification stream 소비와 UI 표시만 담당한다.
- **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` 생성 파일을 직접 수정하지 않는다.
- Nexo/Mattermost smoke credential 같은 local/private 값을 tracked asset이나 README에 기록하지 않는다.
- Control Plane server 상태 저장, Edge registry, run dispatch, stream relay 구현을 client domain으로 끌어오지 않는다.