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

domain	last_rule_review_commit	last_rule_updated_at
client	49872ae120	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으로 끌어오지 않는다.