# Halo Bestie — Mitra App

Flutter mobile application for mental health professionals (mitra/partners).

> See root `CLAUDE.md` for full project context and architectural decisions.

## Stack

- **Framework:** Flutter (iOS + Android)
- **Auth:** Self-managed (Phase 3.4). Phone OTP only — no Google / Apple. Access token lives in memory on an `AuthBridge`; refresh token persists in `flutter_secure_storage`. `firebase_auth` is no longer used; `firebase_messaging` is kept for FCM push.
- **API:** Calls public Fastify backend (`/api/mitra/` and `/api/shared/` routes). `shared.auth` covers refresh + logout for both apps.

## Key Concepts

- Users are **mitra** — trained mental health professionals
- Core flow: phone OTP login → set availability → accept sessions → chat with client → receive payment
- Mitra accounts require approval from control center before going live (backend returns `ACCOUNT_INACTIVE` 403 on OTP verify when `is_active=false`)

## Conventions

- Never call `/api/client/` or `/internal/` routes from this app
- API calls go through `ApiClient`; it auto-attaches the JWT from `AuthBridge` and auto-refreshes on 401
- WebSocket handshake (`/api/shared/ws`) sends the same access token in the first frame's `{type:"auth", token}` message
- Mitra role is encoded in the JWT claims (`user_type: "mitra"`) — the backend enforces the role per route; never trust client state alone

## Pitfalls (HARD rules — silent failure modes)

### Never call `ref.read` / `ref.watch` / `ref.listen` from `State.dispose()`

In a `ConsumerStatefulWidget`, Riverpod invalidates `ref` the instant `dispose()` starts. Any `ref.*` call throws `Bad state: Cannot use "ref" after the widget was disposed.`. Flutter catches it inside `BuildOwner.finalizeTree` — **so it does not surface as a red-screen crash**. Instead the widget tree is left half-finalized and the NEXT screen freezes (looks like a hang; the app process is alive). Real case in this app: `mitra_chat_screen.dart` (2026-05-14).

**Rule:** any cleanup that needs `ref` goes in `deactivate()`, which runs *before* `dispose()` while `ref` is still valid. Non-Riverpod cleanup (`TextEditingController.dispose()`, `WidgetsBinding.removeObserver`, `StreamSubscription.cancel`) stays in `dispose()`.

```dart
@override
void deactivate() {
  ref.read(someProvider.notifier).cleanup();
  super.deactivate();
}

@override
void dispose() {
  WidgetsBinding.instance.removeObserver(this);
  super.dispose();
}
```

A lint rule (`no_ref_in_dispose` in `halo_lints`) fails `dart run custom_lint` on this pattern. When debugging "screen frozen after navigation", grep the *previous* screen's State for `void dispose()` followed by `ref\.` — that's the first suspect.

### Never mutate notifier `state` synchronously from `deactivate()` cleanup

`deactivate()` is the safe place to call `ref.read(...).cleanup()`, but if that cleanup does `state = SomeData()`, Riverpod will notify watchers while the widget tree is mid-teardown → `Tried to modify a provider while the widget tree was building.` → red error screen + engine restart (in debug) or silent state loss (in release). Real case: `mitra_chat_notifier.dart::disconnect()` was firing this on back-press from the session-ended chat screen.

**Rule:** when a notifier's cleanup-from-`deactivate()` path needs to reset its own state, defer the assignment to the next frame:

```dart
void disconnect() {
  _cleanup();  // closing channels / cancelling subs is fine synchronously
  SchedulerBinding.instance.addPostFrameCallback((_) {
    state = const SomeInitialData();
  });
}
```

The synchronous side-effects (closing the WS, cancelling timers) still happen immediately. Only the `state =` assignment is deferred, which is a no-op for users — they're navigating away anyway. Regression coverage: `.maestro/flows/ts-mitra-3-08-back_press_after_session_expired_no_red_screen.yaml`.

### Custom-styled TextField must override the theme's min-height constraint

The app-wide `InputDecorationTheme` in `lib/core/theme/halo_theme.dart` sets a 48dp min-height for form fields (auth, profile, etc.). Any pill-style chat-input or compact TextField that has a fixed-height parent (≤ 48dp) will **silently lose vertical centering** — the field refuses to collapse below 48dp, the line-box can't sit on the parent's midline, and `textAlignVertical` becomes a no-op. Text anchors top.

**Rule:** when building a custom-shaped TextField (pill, dense, fixed-height), explicitly null the theme constraint:

```dart
TextField(
  textAlignVertical: TextAlignVertical.center,
  decoration: const InputDecoration(
    isCollapsed: true,
    contentPadding: EdgeInsets.symmetric(horizontal: 16),
    constraints: BoxConstraints(), // ← REQUIRED — overrides theme min-height
    border: InputBorder.none,
    enabledBorder: InputBorder.none,
    focusedBorder: InputBorder.none,
    disabledBorder: InputBorder.none,
    errorBorder: InputBorder.none,
    focusedErrorBorder: InputBorder.none,
    filled: false,
  ),
)
```

Wrap in `Material(shape: StadiumBorder(...), clipBehavior: antiAlias) + Center(child: TextField)` for proper pill clipping. The chat input bar in [mitra_chat_screen.dart](lib/features/chat/screens/mitra_chat_screen.dart) and [client_app/chat_screen.dart::_InputBar](../client_app/lib/features/chat/screens/chat_screen.dart) both use this pattern; copy from there rather than reinventing.