# Module Guide

This guide explains the major parts of the source bundle and why each part matters.

## 1. App entry and startup

- `client_app/lib/main.dart`
  - starts the app, configures global services, and routes into the rest of the product

Why it matters:

This is the best first file for understanding how the application boots and how the major systems connect.

## 2. Root screens in `client_app/lib/`

Examples:

- `chat_screen.dart`
- `group_chat_screen.dart`
- `contacts_screen.dart`
- `settings_screen.dart`
- `account_management_screen.dart`
- `decoy_setup_screen.dart`
- `stylized_card_studio_screen.dart`
- `sticker_editor_screen.dart`

Why they matter:

These files turn the lower-level services into user-visible features such as conversations, recovery, privacy controls, calls, media, personalization, developer capabilities, and VIP-facing flows.

## 3. `client_app/lib/services/`

This is the most important folder in the client.

### Crypto and protected-state services

- `hash_service.dart`
  - credential hashing and login-proof helpers
- `key_service.dart`
  - device key generation and key protection
- `prekey_service.dart`
  - signed-prekey and one-time-prekey management
- `ratchet_service.dart`
  - direct-message session setup and ratchet progression
- `sender_key_service.dart`
  - group sender-key handling
- `encrypted_store.dart`
  - encrypted local persistence for credential and key-related structured state

Why they matter:

These files show where key and credential state is created, stored, and used before data leaves the device.

### Transport and sync services

- `api_service.dart`
  - HTTP requests and app-facing payloads
- `websocket_service.dart`
  - realtime connection handling
- `sync_service.dart`
  - refresh and synchronization behavior
- `message_repository.dart`
  - message fetch, save, update, and stream coordination

Why they matter:

These files show how the client moves between screens, storage, and the network.

### Device and feature services

Examples:

- notifications and calls
- local databases and media caching
- avatars, stickers, stylized cards, and profile sync
- recovery helpers, privacy tools, and nearby or device helpers

Why they matter:

This layer connects the product features to platform APIs and on-device state.

## 4. `client_app/lib/models/`

This folder defines typed data used across the client.

Why it matters:

Models make message records, avatars, stickers, cards, calls, and related state easier to trace across screens and services.

## 5. `client_app/lib/widgets/`

This folder contains reusable UI pieces such as media previews, banners, call overlays, avatar surfaces, and app shells.

Why it matters:

It keeps the main screens focused on flow logic while common UI stays shareable.

## 6. `client_app/lib/utils/`

Examples:

- `app_config.dart`
- `screen_linking.dart`
- `platform_info.dart`
- `feature_flags.dart`

Why it matters:

These helpers control runtime selection, linking, platform behavior, and small shared utilities used across the app.

## 7. Platform folders

- `client_app/android/`
- `client_app/ios/`
- `client_app/web/`

Why they matter:

Flutter shares most source, but each platform still needs native project files, manifests, resources, and app delegates.

## 8. Server reference

- `backend_reference/app/models/`
  - shows the records used for devices, public-key material, ciphertext, encrypted per-device message keys, and group payload storage
- `backend_reference/app/routers/`
  - shows request handlers for prekey exchange, ciphertext relay, and websocket delivery

Why it matters:

These files show the key material and encrypted records the relay stores for encrypted messaging.

## 9. Chat composer and rich-text module (newest review surface)

Primary files:

- `client_app/lib/chat_screen.dart`
  - direct chat composer flow, inline rich-text field, and fullscreen composer trigger
- `client_app/lib/group_chat_screen.dart`
  - group chat version of the same composer architecture
- `client_app/lib/widgets/fullscreen_rich_composer.dart`
  - fullscreen editing shell with formatting toolbar and compose actions
- `client_app/lib/widgets/rich_text_format_toolbar.dart`
  - inline formatting actions (bold/italic/underline/strike/list/undo/redo)
- `client_app/lib/widgets/rich_message_view.dart`
  - read-only renderer for stored rich-text payloads
- `client_app/lib/utils/rich_message_codec.dart`
  - conversion and normalization between plain text and serialized rich-text JSON

Why this module matters:

- it is where message input UX, formatting behavior, and payload shaping meet
- it includes the inline composer sizing safeguards that keep chat composer height stable
- it shows how fullscreen compose is implemented as an overlay-style surface on top of chat context

## 10. Suggested reading order

1. `client_app/lib/main.dart`
2. `client_app/lib/utils/app_config.dart`
3. `client_app/lib/services/api_service.dart`
4. `client_app/lib/services/hash_service.dart`
5. `client_app/lib/services/key_service.dart`
6. `client_app/lib/services/prekey_service.dart`
7. `client_app/lib/services/ratchet_service.dart`
8. `client_app/lib/services/sender_key_service.dart`
9. `client_app/lib/chat_screen.dart`
10. `client_app/lib/group_chat_screen.dart`
11. `client_app/lib/widgets/fullscreen_rich_composer.dart`
12. `client_app/lib/widgets/rich_text_format_toolbar.dart`
13. `client_app/lib/widgets/rich_message_view.dart`
14. `client_app/lib/utils/rich_message_codec.dart`
15. `backend_reference/app/routers/prekeys.py`
16. `backend_reference/app/routers/messages.py`
17. `backend_reference/app/routers/websocket.py`
18. `backend_reference/app/models/message.py`
19. `backend_reference/app/models/message_key.py`
20. `backend_reference/app/models/group.py`
