---
domain: client
last_rule_review_commit: 3b1be95e625cfd110a42d2ee0d12653dc35f7579
last_rule_updated_at: 2026-05-31
---

# client

## 목적 / 책임

ALT의 Flutter client surface를 담당한다. web/mobile/desktop targets, application shell, routing, feature presentation, socket integration adapters, optional external push integrations, and client-side tests belong here.

## 포함 경로

- `apps/client/lib/main.dart` - Flutter app bootstrap
- `apps/client/lib/src/app/` - app shell, theme, router
- `apps/client/lib/src/contracts/` - client-side contract parser helpers
- `apps/client/lib/src/features/` - feature presentation code
- `apps/client/lib/src/generated/` - generated Dart protobuf outputs consumed by the client
- `apps/client/lib/src/integrations/` - client-side external integration adapters
- `apps/client/integration_test/` - Flutter integration tests
- `apps/client/test/` - Flutter widget/unit tests
- `apps/client/test_runtime/` - runtime smoke test helpers
- `apps/client/pubspec.yaml` - Flutter package dependencies

## 제외 경로

- `services/api/` - socket server runtime
- `packages/contracts/` - schema source for generated contracts
- `packages/domain/` - Go domain models

## 주요 구성 요소

- `AltClientApp` - Material app shell using Riverpod
- `appRouterProvider` - `go_router` configuration
- `DashboardScreen` - initial responsive dashboard surface
- `altParserMap` - generated ALT protobuf message parser registration for Dart clients
- `AltSocketClient` - proto-socket client wrapper for ALT request/response flows
- `AltSocketEndpoint` - local/default socket endpoint value object
- `SocketConnectionController` - Riverpod connection state controller for socket lifecycle
- `MattermostPushHostIntegration` - optional external push integration boundary
- `bootstrapAltClient` - app bootstrap and platform integration startup

## 유지할 패턴

- Keep app-level shell and router under `lib/src/app`.
- Put user-facing screens under the `lib/src/features/feature-name/presentation` pattern.
- Put socket and other external adapters under `lib/src/integrations`.
- Treat files under `lib/src/generated` as generated outputs; update them through codegen.
- Use Material 3 components and responsive navigation patterns.
- Test user-visible app shell behavior through Flutter tests.
- Use `services/api` as the only ALT-owned runtime endpoint. Do not connect directly to worker runtime surfaces from client code.
- Keep operator shell bootstrapping separable from optional push/Firebase/Mattermost setup so core operator UI can start without external push readiness.
- Keep endpoint defaults in `AltSocketEndpoint` or provider/config boundaries; presentation widgets should consume state, not hard-code runtime endpoints.
- Keep Mattermost/Firebase/platform-channel behavior under `lib/src/integrations` and out of dashboard presentation widgets.

## 다른 도메인과의 경계

- **api**: client connects to API through integration adapters; server lifecycle and server-side socket parsing stay in `services/api`.
- **contracts**: client consumes generated/mapped contracts and owns Dart parser helpers; protobuf source stays in `packages/contracts`.
- **operations**: `bin/test`, `bin/lint`, and `bin/build` run client checks from the workspace root.
- **worker**: client never connects to worker directly; worker state reaches client only through API contracts.

## 금지 사항

- Do not place backend service code or Go module files under `apps/client`.
- Do not hand-edit platform generated files unless the Flutter platform integration explicitly requires it.
- Do not hand-edit generated protobuf Dart outputs.
- Do not hard-code production endpoint assumptions in presentation widgets.
- Do not add direct worker, database, Redis, or ALT-owned non-API runtime connections to Flutter client code.
- Do not make push notification or Mattermost availability a prerequisite for the base operator shell unless a dedicated push Milestone explicitly changes that boundary.