---
domain: mobile
last_rule_review_commit: a95fc27151e5e0750c1e25df3f72ad10f2d89506
last_rule_updated_at: 2026-06-24
---

# mobile

## 목적 / 책임

NomadCode의 Flutter-first 제품 UI 도메인이다. 모바일/데스크톱/선택적 web target의 기준 클라이언트, 앱 entrypoint, Mattermost auth, push notification, platform integration을 담당한다.

## 포함 경로

- `apps/client/lib/` — Flutter application code.
- `apps/client/lib/src/app/` — app host, bootstrap, workbench shell.
- `apps/client/lib/src/features/` — product feature UI and local feature state.
- `apps/client/lib/src/features/workspaces/domain/` — workspace/project/task UI model.
- `apps/client/lib/src/integrations/` — Mattermost, proto-socket, workspace launcher 같은 외부 경계 adapter.
- `apps/client/test/` — Flutter widget/service tests.
- `apps/client/assets/` — Flutter asset bundle과 ignored local smoke credential 위치.
- `apps/client/android/`, `apps/client/ios/`, `apps/client/macos/`, `apps/client/linux/`, `apps/client/windows/`, `apps/client/web/` — platform-specific runner/config.
- `apps/client/pubspec.yaml`, `apps/client/pubspec.lock`, `apps/client/analysis_options.yaml` — Dart/Flutter dependencies and analysis.
- `apps/client/README.md`, `apps/client/push-notification-todo.md` — mobile 운영 메모와 push notification 작업 메모.

## 제외 경로

- `services/core/` — backend orchestration/API implementation.
- `apps/web/` — [Legacy/Retired] React/Vite scaffold 경로는 완전히 제거되어 제외 대상입니다.
- `packages/contracts/` — shared API/schema contracts.

## 주요 구성 요소

- `lib/main.dart` — Flutter app entrypoint.
- `lib/src/app/nomadcode_client_app.dart` — MaterialApp host와 integration lifecycle wiring.
- `lib/src/app/nomadcode_workbench_shell.dart` — top titlebar, 우측 activity rail, 중앙 content 전환, 우측 Agent dock panel, 하단 IOP slot을 가진 workbench shell.
- `lib/src/features/workspaces/domain/project_workspace.dart` — workspace/project 목록 UI 모델과 mock workspace seed.
- `lib/src/features/workspaces/domain/workspace_task.dart` — Core `task` channel 응답을 파싱하는 client-side task 모델.
- `lib/src/features/workspaces/presentation/workspace_home_page.dart` — workspace project/task UI. workbench mount 시 `showAppBar: false`로 내부 app bar를 숨길 수 있다.
- `lib/src/integrations/mattermost/mattermost_auth_service.dart` — Mattermost auth flow.
- `lib/src/integrations/mattermost/mattermost_push_client.dart` — Mattermost-compatible push interface.
- `lib/src/integrations/mattermost/mattermost_push_plugin_client.dart` — production-only `NexoMessagingPlugin.instance` adapter.
- `lib/src/integrations/mattermost/mattermost_push_host_integration.dart` — Mattermost push host initialization, auth handoff, notification navigation.
- `lib/src/integrations/proto_socket/proto_socket_client.dart` — local `proto_socket` package 기반 real connector/transport.
- `lib/src/integrations/proto_socket/proto_socket_endpoint_config.dart` — `PROTO_SOCKET_*` env/dart-define 기반 endpoint value object.
- `lib/src/integrations/proto_socket/proto_socket_envelope.dart` — core와 공유하는 semantic envelope DTO.
- `lib/src/integrations/proto_socket/proto_socket_lifecycle.dart` — proto-socket connection lifecycle facade.
- `lib/src/integrations/proto_socket/proto_socket_task_service.dart` — workspace task loading over proto-socket transport.
- `lib/src/integrations/proto_socket/proto_socket_branch_event_service.dart` — Gito `branch.updated` event subscribe/wakeup service.
- `lib/src/integrations/workspace/workspace_launcher.dart` — workspace/code-server launch boundary.
- `android/app/src/main/java/com/tokilabs/mattermost/MainActivity.kt` — Android Flutter activity host.
- `test/widget_test.dart` — baseline widget test.

## 유지할 패턴

- platform-specific permission/capability 변경은 해당 platform 디렉터리와 Dart service 변경을 같이 확인한다.
- Firebase Messaging 변경은 foreground, background, permission flow를 함께 검토한다.
- Android native push 변경은 Kotlin/Java receiver/service, manifest, Dart bridge 영향을 함께 확인한다.
- public API 호출을 추가하면 contracts/core 영향 여부를 확인한다.
- project/task/agent/workspace 제품 UI는 Flutter 앱을 기준 구현으로 둔다.
- NomadCode app shell은 top titlebar와 우측 activity rail을 가진 workbench 구조를 기준으로 한다. 우측 Agent dock은 rail에 붙는 panel로 열고 닫으며, 중앙 영역은 workspace/workflow/terminal/review/web context/settings 같은 product section을 전환한다.
- IOP entry는 우측 rail 하단에 둔다. IOP-specific 운영 화면은 `iopContent` 같은 선택적 widget slot으로 mount하고, IOP package가 없는 기본 빌드에서는 placeholder로 유지한다.
- 공통 agent interaction UI는 sibling `agent_shell` package를 사용한다. NomadCode-specific workflow/web context capability는 NomadCode mobile domain이 소유하고, IOP-specific 운영 화면은 향후 IOP-owned package/widget을 선택적으로 mount한다.
- proto-socket 연결은 `ProtoSocketLifecycle`과 connector/transport interface 뒤에 두고, bootstrap은 안전한 no-op 기본값으로 시작한다.
- `PROTO_SOCKET_HOST`가 없으면 endpoint config는 null/disabled로 두고, bootstrap에서 네트워크 연결을 강제하지 않는다.
- Gito `branch.updated` event는 UI wakeup hint로만 소비하고, 클라이언트가 source-of-truth 상태나 provider/roadmap mutation을 직접 수행하지 않는다.
- production code에서 `NexoMessagingPlugin.instance` 직접 참조는 `MattermostPushPluginClient`에만 둔다.
- `assets/mattermost_credentials.json`은 local smoke credential로만 쓰며 ignored file 상태를 유지한다.
- `flutter test`를 기본 검증으로 사용한다.
- 현재 baseline의 `avoid_print` info는 별도 cleanup 작업으로 다루고, 기능 변경과 섞지 않는다.

## 다른 도메인과의 경계

- **core**: mobile은 core API/notification 계약에 의존하되 core 내부 구현을 알지 않는다.
- **contracts**: mobile이 사용하는 API/event/proto-socket envelope shape와 Gito branch event 소비 의미는 contracts 후보로 올린다.
- **agent-shell**: common chat/agent shell widget과 message model만 제공하는 sibling package다. Product routing, workbench section, web context 조작, IOP mount 결정은 mobile domain에서 조립한다.
- **IOP**: IOP는 runtime/operation/agent capability와 IOP console widget/package 경계를 소유한다. mobile은 IOP 기능을 직접 복제하지 않고 선택적 section으로 mount한다.
- **web**: [Legacy/Retired] React web 도메인은 완전히 제거되었습니다.
- **workspace-ops**: root scripts와 agent rules는 mobile 내부에 복제하지 않는다.

## 금지 사항

- Android/iOS/macOS 권한 변경을 Dart service 변경 없이 단독으로 넣지 않는다.
- Android native notification helper 변경을 FCM service와 reply/dismiss receiver 영향 검토 없이 단독으로 넣지 않는다.
- Firebase 초기화/handler 변경을 테스트나 수동 검증 메모 없이 마무리하지 않는다.
- IOP client UI나 runtime/operation semantics를 NomadCode mobile code에 직접 복제하지 않는다.
- `agent_shell` package에 NomadCode 전용 workflow/web context/IOP product logic을 밀어 넣지 않는다.
- branch event 수신만으로 roadmap/provider 상태를 변경하지 않는다.
- `nexo_messaging` plugin singleton을 host UI나 auth service에서 직접 호출하지 않는다.
- local smoke credential 파일을 tracked asset으로 커밋하지 않는다.
- generated/platform build output을 의도 없이 커밋하지 않는다.
- mobile 내부에 별도 `agent-ops` scaffold를 다시 만들지 않는다.
