# File Guide

Use this as the shortest path through the source bundle.

## Start with the app shell

- `client_app/lib/main.dart`
  - boot path, global services, and route setup
- `client_app/lib/utils/app_config.dart`
  - runtime flags and endpoint selection
- `client_app/lib/services/api_service.dart`
  - request and response layer for the major client flows

## Follow auth and protected state

- `client_app/lib/services/hash_service.dart`
  - password hashing and login-proof helpers
- `client_app/lib/services/auth_service.dart`
  - sign-in state and authenticated session helpers
- `client_app/lib/services/encrypted_store.dart`
  - encrypted local state container
- `client_app/lib/services/key_service.dart`
  - device key generation and key protection

## Follow encrypted messaging

- `client_app/lib/services/prekey_service.dart`
  - signed-prekey and one-time-prekey generation and upload handling
- `client_app/lib/services/ratchet_service.dart`
  - direct-message session bootstrap and ratchet advancement
- `client_app/lib/services/sender_key_service.dart`
  - group sender-key distribution and progression
- `client_app/lib/services/message_ingest_service.dart`
  - decrypt-and-store path for incoming payloads
- `client_app/lib/chat_screen.dart`
  - direct-message UI path
- `client_app/lib/group_chat_screen.dart`
  - group-message UI path

## Follow rich composer internals

- `client_app/lib/widgets/fullscreen_rich_composer.dart`
  - fullscreen compose shell and collapse/submit affordances
- `client_app/lib/widgets/rich_text_format_toolbar.dart`
  - rich-text controls (formatting, list operations, undo/redo)
- `client_app/lib/widgets/rich_message_view.dart`
  - render path for rich-text content stored with messages
- `client_app/lib/utils/rich_message_codec.dart`
  - normalization and serialization of rich-text JSON payloads
- `client_app/lib/chat_screen.dart` and `client_app/lib/group_chat_screen.dart`
  - inline composer wiring, compact editor theme, and media/recording coexistence

## Follow feature surfaces

- `client_app/lib/services/push_notification_service.dart`
  - push registration and notification handling
- `client_app/lib/services/call_service.dart`
  - direct-call client service
- `client_app/lib/services/group_call_service.dart`
  - group-call client service
- `client_app/lib/recovery_setup_screen.dart`
  - recovery creation flow
- `client_app/lib/recovery_rebind_screen.dart`
  - recovery rebind flow
- `client_app/lib/decoy_setup_screen.dart`
  - privacy-oriented decoy flow
- `client_app/lib/account_management_screen.dart`
  - paid-account, entitlement, and account controls
- `client_app/lib/sticker_editor_screen.dart`
  - sticker creation and editing tools
- `client_app/lib/stylized_card_studio_screen.dart`
  - stylized card creation and profile customization tools

## Follow the server reference

- `backend_reference/app/models/device.py`
  - stores the device public key used for encrypted delivery
- `backend_reference/app/models/signed_prekey.py`
  - stores the signed prekey used for session bootstrap
- `backend_reference/app/models/one_time_prekey.py`
  - stores one-time prekeys consumed during session setup
- `backend_reference/app/models/message.py`
  - stores direct-message ciphertext and ratchet metadata
- `backend_reference/app/models/message_key.py`
  - stores per-device encrypted message keys
- `backend_reference/app/models/group.py`
  - stores encrypted group payloads and sender-key metadata
- `backend_reference/app/routers/prekeys.py`
  - accepts prekey registration and serves bundles
- `backend_reference/app/routers/messages.py`
  - reference relay path for ciphertext write, pending fetch, ack, and sync
- `backend_reference/app/routers/websocket.py`
  - reference realtime channel for message fanout, typing, and call signaling
