the signals and their derived score are provisional and subject to change.
validate manually before sharing.
3253b1264a821d85858e438f6008cbaf369a0fcb9da0c1daeae81 month agoCo-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>89b476ef942b1 month agoCo-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>bff95f2320f01 month agoCo-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>6d7a146a62131 month agoCo-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>a516925749261 month agoCo-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>ed6793449ff81 month agoCo-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>505ca504b12d1 month agoCo-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>157f21b418191 month agoClaude-Session: https://claude.ai/code/session_01AyxJz1fsojfXbxJUBBsivyeb99646c42fe2 months agoClaude-Session: https://claude.ai/code/session_0134chdSgpm7YBoYkmuA27SK2ba5eafb7cff4 months agoCo-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>14730fde700a4 months agoCo-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>7404eb9b936b4 months agoCo-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>9e1fd2aebdd24 months agoCo-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>a6c486b617fd4 months agoCo-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>58afb68cb37a11 months agoCo-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>fb406de40b9c11 months agoCo-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>8e66d0af677211 months agoCo-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>ad711b70617511 months agoCo-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>8b527936648711 months agoCo-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>3a4367cbcf3111 months agoCo-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>b8a96cc0573a11 months agoCo-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>997eb242588611 months agoCo-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>515be6287c0511 months agoCo-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>26ef6ca640a611 months agoCo-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>6182444e0d8211 months agoCo-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>b56701f670ed11 months agoCo-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>a22b3d3e5ceb11 months agoCo-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>d8627f1db32411 months agoCo-authored-by: Copilot <175728472+Copilot@users.noreply.github.com># Agent Instructions
This repo's knowledge base lives in `CLAUDE.md` files, not here.
Start at the root [`CLAUDE.md`](CLAUDE.md) for project orientation, then follow its
directory-specific pointers (e.g. `lib/CLAUDE.md`, `android/CLAUDE.md`, `windows/CLAUDE.md`, `linux/CLAUDE.md`) based on
what part of the codebase you're touching. Many subdirectories under `lib/` have their own
`CLAUDE.md` as well — check for one in the target directory before making changes.
For coding standards and conventions, read# lib/models/ — Cross-Cutting DTOs & View Models
See `docs/MODELS.md` for the consolidated cross-directory entity/DTO field reference.
Plain data classes used across multiple layers. Not ObjectBox entities — no `@Entity` annotations. All serializable and safe to cross isolate boundaries.
Barrel export: `models/models.dart`
## File Map
| File | Purpose |
|------|---------|
| `app_update_info.dart` | App version check result (latest version, download URL) |
| `attachment_upload_progress.dart` | Uploa# reaction/ — Tapback Display
Renders the tapback emoji row that appears above or below a message bubble.
## Files
| File | Purpose |
|------|---------|
| `reaction.dart` | `ReactionWidget` — single tapback emoji with skin-specific styling |
| `reaction_holder.dart` | Horizontal row container for all reactions on a message part |
| `reaction_clipper.dart` | `CustomClipper` for the pill-shaped reaction bubble |
## Data Source
Reactions come from `MessageState.associatedMessages` (an `RxList<Message># app/layouts/fullscreen_media/ — Full-Screen Media Viewer
## Files
| File | Purpose |
|------|---------|
| `conversation_fullscreen_holder.dart` | Gallery holder for a chat's attachments — pinch-zoom, `PageView` paging, reply-to-attachment, keyboard arrow navigation |
| `single_attachment_fullscreen_viewer.dart` | Single-item holder for one local/unsent attachment — no paging, reply, or gallery state |
| `fullscreen_image.dart` | Full-screen image viewer |
| `fullscreen_video.dart` | Full-screen vid# widgets/tile/ — Conversation List Tile
Individual chat row rendered in the conversation list. Each tile displays the chat avatar, name, last message preview, timestamp, and unread badge.
## Files
| File | Purpose |
|------|---------|
| `conversation_tile.dart` | Base widget + `ConversationTileController`; dispatches to skin via `ThemeSwitcher` |
| `material_conversation_tile.dart` | Material Design skin |
| `cupertino_conversation_tile.dart` | iOS Cupertino skin |
| `samsung_conversation_tile.dart` |# setup/pages/ — Setup Step Pages
Individual step-pages shown in sequence during the first-run server connection setup flow.
## Subdirectories
| Directory | File(s) | Step |
|-----------|---------|------|
| `welcome/` | `welcome_page.dart` | Introduction screen with "Get Started" |
| `permissions/` | `request_permissions.dart` | Request notification + battery optimization permissions |
| `setup_checks/` | `battery_optimization.dart`, `mac_setup_check.dart` | Platform-specific requirement checks |
| `sy# services/network/api/ — HTTP API Sub-Services
One file per server API domain. Each class implements `BaseApi` and is exposed on `HttpService` as `HttpSvc.<name>` (see the method table in `../CLAUDE.md`).
## Files
| File | Class | Property on `HttpSvc` |
|------|-------|------------------------|
| `base_api.dart` | `BaseApi` (abstract interface) | — |
| `server_api.dart` | `ServerApi` | `server` |
| `fcm_api.dart` | `FcmApi` | `fcm` |
| `attachment_api.dart` | `AttachmentApi` | `attachment` |
| `chat# interactive/ — Rich / Interactive Message Renderers
Handles messages with Apple payload data: URL previews, Apple Pay, Game Pigeon invitations, embedded media (maps, music, iBooks), and generic interactive types.
## Files
| File | Purpose |
|------|---------|
| `interactive_holder.dart` | **Entry point** — routes on `message.payloadData` type |
| `url_preview.dart` | Link previews — owns `UrlPreviewController`, dispatches to a skin |
| `url_preview_controller.dart` | All fetch/cache/policy wiring# lib/helpers/ — Cross-Cutting Utilities
Import via barrel: `package:bluebubbles/helpers/helpers.dart` (re-exports most files below — a few are imported directly; see note).
## UI Helpers (`ui/`) → `ui/CLAUDE.md`
- `ui_helpers.dart` — general UI utilities (back button, safe area, etc.)
- `theme_helpers.dart` — `ThemeHelpers` mixin; mixed into `CustomState`; provides `iOS`, `material`, `samsung` skin booleans
- `message_widget_helpers.dart` — message-specific UI utilities
- `reaction_helpers.da# helpers/network/ — Network Utility Functions
Pure helpers for network operations. No UI dependencies.
## File Routing
| File | What's inside |
|------|---------------|
| `network_helpers.dart` | `sanitizeServerAddress(url)` — normalizes server URLs (detects ngrok/Cloudflare tunnels, ensures correct scheme); `isValidServerAddress(url)` — accepts LAN hostnames, localhost, IPs, and long TLDs that GetX `isURL` rejects; `getOrCreateUniqueId()` — persistent install ID; `getDeviceName()` — device na# widgets/message/text/ — Text Bubble Renderer
## Files
| File | Purpose |
|------|---------|
| `text_bubble.dart` | Renders the text content for a single message part; handles plain text, rich text (attributed body), mentions, and edit-unsent styling |
## How Text is Rendered
1. If `part.attributedBody` is non-null → `AttributedBodyHelpers.buildAttributedText()` for rich text (bold/italic/mentions/links)
2. Otherwise → plain `SelectableText` with `TextStyle` from `context.theme`
## Edit / Unsent S# conversation_view/widgets/effects/ — Send Effect UI
UI for selecting and displaying iMessage send effects (balloon, confetti, echo, etc.).
## Files
| File | Purpose |
|------|---------|
| `screen_effects_widget.dart` | Full-screen animated overlay that plays a send effect (rendered on top of the conversation) |
| `send_effect_picker.dart` | Picker sheet that lists available effects; lets user choose before sending |
## Effect Definitions
The animation classes and renderers live in `lib/app/animation# conversation_list/widgets/header/ — Chat List Headers (Tri-Platform)
Platform-specific header widgets for the conversation list screen. Each implements the same logical header (search button, title, action icons) adapted to its design language.
## Files
| File | Purpose |
|------|---------|
| `cupertino_header.dart` | iOS-style large title + inline search (collapses on scroll) |
| `material_header.dart` | Material Design app bar with search + compose icons |
| `samsung_header.dart` | Samsung One UI h# conversation_view/widgets/media_picker/ — Attachment Picker UI
UI for selecting media files to attach before sending a message.
## Files
| File | Purpose |
|------|---------|
| `text_field_attachment_picker.dart` | Bottom-sheet picker that browses the photo library and recent files; tapping an item adds it to the composer draft |
| `attachment_picker_file.dart` | Renders a single file/photo thumbnail item inside the picker |
## Integration
Opened from the compose bar via the attachment (paperclip / # database/global/ — Shared DTOs (All Platforms)
Plain Dart classes — no ObjectBox annotations. Safe to use on web. All have `fromMap`/`toMap`.
## Core App Models
| File | Purpose |
|------|---------|
| `settings.dart` | 50+ `Rx*` preference fields — the single source of truth for all app settings |
| `message_part.dart` | One content chunk of a multi-part message |
| `attributed_body.dart` | Rich text formatting metadata (bold, italic, mention, link, attachment) |
| `message_summary_info.dart` | Re# services/ui/ — UI State Services
All are GetX singletons. Shorthand getters live in `lib/services/services.dart`.
## Chat → `chat/CLAUDE.md`
- `chat/chats_service.dart` (`ChatsSvc`) — sorted chat list, unread count, `ChatState` map, active chat tracking; loads in batches of 100
- `chat/conversation_view_controller.dart` — state for the currently open conversation (text, attachments, reply, scroll position)
## Messages → `message/CLAUDE.md`
- `message/messages_service.dart` (`MessagesSvc`) —# database/html/ — Web Platform Stubs (Deprecated)
**Web support is deprecated. Do not extend these files.**
These are stub implementations of the ObjectBox entity classes that compile for the web platform, where ObjectBox is unavailable. They mirror the API surface of `lib/database/io/` but hold no data and perform no actual persistence.
All 12 files here (`chat.dart`, `message.dart`, `attachment.dart`, `handle.dart`, `theme.dart`, `fcm_data.dart`, `launch_at_startup.dart`, `media_kit.dart`, `network_# findmy/ — Find My Device Locator
## Files
- `findmy_page.dart` — main screen (map + list tabs)
- `findmy_controller.dart` — state and logic: location polling, device/friend tracking
- `findmy_location_clipper.dart` — custom `CustomClipper` for location shape
- `findmy_pin_clipper.dart` — custom `CustomClipper` for map pin shape
## Widgets (`widgets/`)
- `findmy_map_widget.dart` — interactive map view
- `findmy_friend_list_tile.dart` — friend location list row
- `findmy_device_list_tile.dar# services/backend/lifecycle/ — App Lifecycle Service
## File
`lifecycle_service.dart` — `AppLifecycleService` (registered with GetIt)
## Responsibilities
- Listens to Flutter `AppLifecycleState` changes (resumed, paused, detached, inactive)
- On **resume**: reconnects socket, triggers incremental sync, refreshes contact sync state
- On **pause**: records last-active timestamp, optionally disconnects socket (configurable), drains the global isolate (Android), and purges rebuildable caches via `CacheSv# timestamp/ — Delivery Status & Date Separators
Shows when a message was sent and its delivery/read status.
## Files
| File | Purpose |
|------|---------|
| `message_timestamp.dart` | Timestamp label (iOS: slides in from right on tap; Samsung: always visible) |
| `delivered_indicator.dart` | Delivery status checkmarks (sent / delivered / read) |
| `timestamp_separator.dart` | Full-width date header between messages from different days ("Today", "Yesterday", etc.) |
## Skin Behavior
| Skin | Timestam# setup/ — Onboarding Flow
## Entry Point
`setup_view.dart` — `PageView` orchestrator driven by `SetupViewController`
## Page Order
1. `pages/welcome/welcome_page.dart`
2. `pages/setup_checks/mac_setup_check.dart` — macOS permission checks
3. `pages/setup_checks/battery_optimization.dart` — Android battery optimization warning
4. `pages/permissions/request_permissions.dart` — contact/notification permission request
5. `pages/sync/qr_code_scanner.dart` OR `pages/sync/server_credentials.dart` — # Claude Workflow — BlueBubbles
## Rules
Detailed coding standards live in `.claude/rules/`:
- `frontend.md` — widget patterns, state, theming, naming
- `api.md` — HTTP calls, interface→action pattern, error handling
- `database.md` — ObjectBox entities, queries, transactions, serialization
- `services.md` — service access, event dispatch, method channels, navigation
- `git.md` — commit message format
## Architecture & Design Decisions
- `docs/ARCHITECTURE.md` — how the system's major subs# conversation_view/widgets/header/shared/ — Shared Header Logic
Utilities shared across all three platform-specific conversation header variants (cupertino, material, samsung).
## Files
| File | Purpose |
|------|---------|
| `chat_title_mixin.dart` | Provides `chatTitle`, `chatSubtitle`, and contact-name resolution logic; mixed into all three header widgets so they compute the same display name without duplication |
| `header_components.dart` | Shared sub-widgets: back button, video/audio call button# message_holder/ — Master Message Composition
`MessageHolder` is the outermost widget for each message row. It composes every sub-widget into the final rendered bubble.
## Files
| File | Purpose |
|------|---------|
| `../message_holder.dart` | Main widget; lives one level up in `widgets/message/` |
| `message_holder_wrappers.dart` | `SelectModeWrapper` — Obx wrapper for selection-mode checkbox visibility |
| `message_holder_reactions.dart` | `ReactionObserver`, `StickerObserver` — isolated Obx sc# lib/app/animations/ — iMessage Send Effects
Rendered as full-screen overlays when a message is sent with an iMessage effect.
## Pattern: Two Files Per Effect
| File suffix | Purpose |
|-------------|---------|
| `*_classes.dart` | Data/controller classes — particle state, physics math, animation controllers |
| `*_rendering.dart` | `LeafRenderObjectWidget` + `RenderBox` — the actual custom paint/draw logic |
## Effects
| Effect | Classes | Rendering |
|--------|---------|-----------|
| Celebrat# conversation_view/widgets/header/ — Conversation Header Bar
Three files. The header follows the standard skin pattern — each skin has its own implementation sharing the same controller.
## Files
| File | Contents |
|------|---------|
| `cupertino_header.dart` | iOS-skin header (title, back button, avatar, call button) |
| `material_header.dart` | Material-skin header |
| `header_widgets.dart` | Shared sub-widgets used across skins — `ManualMark` (private API read receipt button), connection status# lib/app/state/ — Reactive State Wrappers
These are the bridge between ObjectBox DB entities and the UI.
## Files
- `chat_state.dart` — `ChatState`: reactive wrapper for a `Chat` entity
- `message_state.dart` — `MessageState`: reactive wrapper for a `Message` entity
- `attachment_state.dart` — `AttachmentState`: reactive wrapper for an `Attachment` entity
- `handle_state.dart` — `HandleState`: reactive wrapper for a `Handle` entity, owned by `HandleService`
- `chat_state_scope.dart`, `message_s# lib/utils/ — Low-Level Pure Utilities
No business logic. No service dependencies. No GetX.
## Logger (`logger/`)
- `logger.dart` — `Logger.debug/info/warn/error(msg, tag: 'Tag')` — **always use this, never `print()`**
- `task_logger.dart` — task-scoped logging with start/complete/fail lifecycle
- `outputs/debug_console_output.dart` — console sink
- `outputs/rotating_file_output.dart` — rotating file sink implementation
- `outputs/file_output_wrapper.dart` — wraps `rotating_file_output.dart# services/backend/settings/actions/ — SharedPreferences Category Actions
One class per preference category, each wrapping a `SharedPreferencesService` instance with typed get/set methods for that category's keys. These are the implementation behind the `PrefsSvc.<category>` category helpers described in `../CLAUDE.md` — call through `PrefsSvc`, not these classes directly.
## Files
| File | Class | Category (`PrefsSvc.<category>`) |
|------|-------|-----------------------------------|
| `shared_prefer# conversation_details/dialogs/ — Detail Panel Dialogs
Dialogs shown from within the conversation details / info panel.
## Files
| File | Purpose |
|------|---------|
| `add_participant.dart` | Dialog for adding a new participant to a group chat |
| `address_picker.dart` | Picker for choosing which address/handle to use when sending to a contact with multiple numbers |
| `change_name.dart` | Dialog for renaming a group conversation |
| `chat_sync_dialog.dart` | Progress dialog shown during a manual cha# lib/services/ — Business Logic & State
## Subsystems
- `backend/` — server interaction, sync, queues, action dispatch → `CLAUDE.md` inside
- `network/` — HTTP, WebSocket, downloads, Firebase → `CLAUDE.md` inside
- `ui/` — UI-facing state services → `CLAUDE.md` inside
- `backend_ui_interop/` — event dispatch between backend and UI → `CLAUDE.md` inside
- `isolates/` — cross-isolate communication → `CLAUDE.md` inside
## UI Services (`ui/`)
| File | Manages |
|------|---------|
| `ui/c# conversation_details/ — Chat Info Panel
Displayed as a right-side panel on tablet or pushed screen on mobile.
## Main Screen
`conversation_details.dart` — top-level screen
`conversation_attachments.dart` — full-page view for a single attachment category
## Dialogs (`dialogs/`)
- `address_picker.dart` — pick which phone/email address to use for a contact
- `change_name.dart` — rename a group chat
- `timeframe_picker.dart` — date range selector (for media/docs filtering)
- `add_participant.da# settings/widgets/layout/ — Settings Page Layout Helpers
Structural widgets used as building blocks inside every settings panel to maintain consistent spacing and visual hierarchy.
## Files
| File | Purpose |
|------|---------|
| `settings_scaffold.dart` | Wraps a settings page with the correct app bar, background color, and scroll container |
| `settings_header.dart` | Section header label with uppercase tracking (e.g., "NOTIFICATIONS") |
| `settings_divider.dart` | Horizontal rule between sections |# settings/ — App Settings
## Page Categories (`pages/`) → `pages/CLAUDE.md`
| Directory | Content |
|-----------|---------|
| `theming/` | Theme picker; `advanced/` for color customization; `avatar/` for avatar colors |
| `message_view/` | Message display preferences |
| `conversation_list/` | Chat list display preferences |
| `server/` | Server connection, backup/restore, OAuth |
| `system/` | Notifications, permissions |
| `profile/` | User profile |
| `scheduling/` | Scheduled messages and reminder# services/network/firebase/ — Firebase Services
Firebase integration for push notifications and real-time database fallback.
## Files
| File | Purpose |
|------|---------|
| `cloud_messaging_service.dart` | Firebase Cloud Messaging (FCM) — receives push tokens, handles background message delivery when socket is disconnected |
| `firebase_database_service.dart` | Firebase Realtime Database — optional relay channel for receiving messages when direct socket is unavailable (e.g., behind NAT) |
## Whe# conversation_list/ — Chat List / Inbox
## Pages (`pages/`)
- `conversation_list.dart` — main entry; uses `ConversationListController`
- `cupertino_conversation_list.dart` — iOS skin
- `material_conversation_list.dart` — Material skin
- `samsung_conversation_list.dart` — Samsung skin
- `search/search_view.dart` — full-text search results page (UI + filter state orchestration)
- `search/search_query_helper.dart` — local/network message search query execution and result hydration
- `search/sea# settings/pages/scheduling/ — Scheduled Messages & Reminders
UI for creating, viewing, and managing scheduled messages and message reminders.
## Files
| File | Purpose |
|------|---------|
| `scheduled_messages_panel.dart` | Entry point — routes to platform variant |
| `cupertino_scheduled_messages_panel.dart` | iOS-skin scheduled messages list |
| `material_scheduled_messages_panel.dart` | Material-skin scheduled messages list |
| `samsung_scheduled_messages_panel.dart` | Samsung-skin scheduled mes# conversation_view/ — Message Thread UI
## Structure
- `pages/conversation_view.dart` — main chat screen
- `pages/messages_view.dart` — scrollable message list
- `widgets/messages_view_components.dart` — extracted widgets shared by the message list (e.g. `TypingIndicatorRow`)
- `widgets/message/` — all message rendering → `CLAUDE.md` inside
- `widgets/header/` — chat header bar and info → `CLAUDE.md` inside
- `widgets/text_field/` — message composer
- `buttons/` — attachment, emoji, # widgets/message/attachment/parts/ — Attachment Render States
Per-transfer-state renderers for a single attachment slot. `AttachmentContent` (parent) picks the right widget based on `AttachmentState.transferState`.
## Files
| File | Renders when... |
|------|----------------|
| `not_loaded_content.dart` | Attachment exists on server but has not been downloaded; shows thumbnail placeholder + download button |
| `downloading_content.dart` | Download in progress; shows progress bar |
| `download_progress# android/ — Android Native (Kotlin)
Source: `app/src/main/kotlin/com/bluebubbles/messaging/`
## Key Modules
| Directory | Purpose |
|-----------|---------|
| `services/foreground/` | Foreground service to keep socket alive |
| `services/firebase/` | FCM push notifications and Firebase auth |
| `services/notifications/` | Notification channels, message/FaceTime builders |
| `services/intents/` | Intent receivers (deep links, auto-start) |
| `services/system/` | Calendar, contacts, browser, Chrome OS int# popup/ — Long-Press Context Menu
Handles the action sheet / context menu shown when the user long-presses (or right-clicks on desktop) a message bubble.
## Files
| File | Purpose |
|------|---------|
| `message_popup_holder.dart` | `GestureDetector` wrapper inside message bubbles; triggers popup presentation |
| `message_popup.dart` | Core popup layout/composition and action availability rules |
| `message_popup_action_context.dart` | Shared typed context passed to extracted action functions |
| `det# conversation_details/widgets/ — Detail Panel Sub-Widgets
Reusable widgets composing the conversation details / info panel.
## Root widgets
| File | Purpose |
|------|---------|
| `chat_info.dart` | **iOS-only.** Top section: avatar, name, participant count, edit name button. Material/Samsung use `../material/material_chat_header.dart` instead — routed from `conversation_details.dart` by skin |
| `chat_options.dart` | **iOS-only.** Action row: mute, pin, archive, block, delete. Material/Samsung use # linux/ — Linux Native (Minimal Custom Code)
C++ code: `main.cc` + `my_application.cc/h` — standard GTK-based Flutter app wrapper. `splash_screen.cc/h` — native splash screen shown before the Flutter engine attaches.
## Distribution Packages (project root)
- `flatpak/` — Flatpak package (`app.bluebubbles.BlueBubbles`)
- `snap/` — Snap package (`snapcraft.yaml`); core24 base, amd64/arm64, GNOME extension
## Notable Dependencies
- `desktop_webview_auth` — WebKit2GTK 4.1 (custom fork) for OAuth# reply/ — Quoted Reply Bubbles & Thread UI
Displays reply threading: the quoted preview above a message and the thread connector lines (iOS only).
## Files
| File | Purpose |
|------|---------|
| `reply_bubble.dart` | Quoted reply preview widget (shows target message's text/attachment snippet) |
| `reply_line_painter.dart` | `CustomPainter` that draws the vertical thread connector line (iOS only) |
| `reply_thread_popup.dart` | Full-screen modal showing all messages in a reply thread |
## How `ReplyB# services/ui/navigator/ — Navigation Service
## File
`navigator_service.dart` — `NavigatorService` (shorthand: `NavigationSvc`)
## Responsibilities
GetX-based navigation helper. Always use this instead of calling `Navigator.of(context)` directly in feature code.
## Key Methods
```dart
NavigationSvc.push(context, widget) // push route
NavigationSvc.pushAndRemoveUntil(context, widget) // push + clear stack
NavigationSvc.pop(context) // pop current route
Navig# chat_creator/widgets/ — New Chat Creator Widgets
Sub-widgets for the new conversation creation UI.
## Files
| File | Purpose |
|------|---------|
| `recipient_chips_row.dart` | Horizontal scrollable row of selected contact chips (To: field) |
| `selected_contact_chip.dart` | Single removable chip representing a chosen recipient |
| `search_results_list.dart` | Scrollable list of contact/handle search results |
| `search_contact_tile.dart` | Single search result row (avatar, name, address) |
| `chat_l# settings/pages/storage/ — Storage Analyzer
Measures on-disk storage usage (by media type, filterable by chat and age) and lets the user
reclaim it. See `docs/feature-planning/storage-analyzer/STORAGE_ANALYZER_PLAN.md` for the full design.
## Global Segments
Most segments live under `attachments/<guid>/` and can be narrowed by chat and age.
`StorageSegmentType.orphaned` and `StorageSegmentType.urlPreviews` cannot — orphan folders map to no
DB row, and link preview images are content-addressed and sha# conversation_view/pages/ — Top-Level Page Widgets
Two entry-point widgets for the conversation screen.
## Files
| File | Purpose |
|------|---------|
| `conversation_view.dart` | Outer container; sets up `ConversationViewController`, handles routing, manages keyboard/layout |
| `messages_view.dart` | Scrollable message list; owns `CustomScrollView`, loads messages in pages, triggers `MessagesService` |
## Handlers (`handlers/`)
Extracted orchestration logic used by `messages_view.dart` / `conversati# services/backend/setup/ — App Setup Service
## File
`setup_service.dart` — `SetupService` (GetX singleton via `SetupSvc` shorthand)
## Responsibilities
- Orchestrates the first-run server connection flow
- Validates server URL, tests connectivity, and stores credentials
- Triggers the initial full data sync after a successful connection
- Tracks setup progress state so `SetupView` can show step-by-step progress UI
## Usage
Called exclusively from `lib/app/layouts/setup/` during onboarding.
Do not c# macos/ — macOS Native (Minimal Custom Code)
Custom Swift:
- `Runner/AppDelegate.swift` — sets `applicationShouldTerminateAfterLastWindowClosed = true` (app quits when main window closes)
- `Runner/MainFlutterWindow.swift` — window initialization
All macOS behavior is plugin-driven. macOS-specific Flutter code lives in:
- `lib/utils/window_effects.dart` — Mica/acrylic transparency (`flutter_acrylic`)
- `lib/app/wrappers/titlebar_wrapper.dart` — custom window chrome (`bitsdojo_window`)
- `lib/ap# helpers/types/helpers/ — Type-Specific Utility Functions
Pure functions, no state or service dependencies.
## File Routing
| File | What's inside |
|------|---------------|
| `string_helpers.dart` | `randomString(n)` — generates n-char alphanumeric string (used for tempGuids); `sanitizeString()` strips U+FFFC; `sanitizeFileName()` / `hasReservedFileNameChars()` — make a foreign string safe as a file name (always run IDs/names through this before building a path); `isNullOrEmptyString()`; `parseLi# BlueBubbles App
iMessage client for Android and Desktop (Windows, Linux). Flutter/Dart.
Web support exists in the codebase but is **deprecated** — do not design for it.
iOS and macOS clients are not supported and never will be — do not design for them. (The server component runs on macOS only.)
## Code → `lib/CLAUDE.md`
## Android native → `android/CLAUDE.md`
## iOS native → `ios/CLAUDE.md`
## macOS native → `macos/CLAUDE.md`
## Windows native → `windows/CLAUDE.md`
## Linux native → `linu# lib/app/components/ — Reusable UI Components
## Avatars (`avatars/`)
- `contact_avatar_widget.dart` — single contact avatar (initials, photo, gradient color, typing indicator)
- `contact_avatar_group_widget.dart` — stacked multi-contact avatar for group chats
Every avatar file decodes at `ContactAvatarWidget.avatarDecodeSize` (256 px), group photos included — never draw one
with a bare `FileImage`, and keep the conversation list warm-up's `ResizeImage` params identical or its precache is
never h# ios/ — iOS Native (Minimal Custom Code)
Custom Swift: `Runner/AppDelegate.swift` — standard Flutter app delegate (13 lines). Registers plugins only via `GeneratedPluginRegistrant`.
All iOS-specific Flutter behavior is plugin-driven. iOS-specific Dart code lives in:
- `lib/services/backend/java_dart_interop/` — method channel setup
- `lib/services/network/` — push notification registration
## Adding a Method Channel on iOS
1. Add the channel handler in `AppDelegate.swift` inside `application(_:d# services/ui/message/ — Message State
## Files
| File | Purpose |
|------|---------|
| `messages_service.dart` | Per-chat message cache, `MessageState` map, update triggers |
Per-message widget state (parts, edits, audio) lives directly on `MessageState` (`lib/app/state/message_state.dart`) — the old standalone `MessageWidgetController` was merged into it.
---
## MessagesService (`messages_service.dart`)
One instance per chat GUID. Accessed via `MessagesSvc(chatGuid)`.
**What it owns:**
- `messag# attachment/ — Attachment Renderers
Renders all non-text media inside message bubbles. Entry point: `AttachmentHolder`, which dispatches to the appropriate renderer based on MIME type.
## Files
| File | Purpose |
|------|---------|
| `attachment_holder.dart` | **Entry point** — MIME type dispatcher; manages download state |
| `image_viewer.dart` | Images with tap-to-fullscreen gesture |
| `video_player.dart` | Video playback with custom controls |
| `audio_player.dart` | Audio playback with progress# services/ui/cache/ — Cache Service
Registry of every in-process cache the app can shrink or drop, and the policies that decide what
happens to each one at each purge level. Exists because Android's low memory killer evicts the
largest cached process first, and most of what this app holds while backgrounded is rebuildable.
## Files
| File | Contents |
|------|----------|
| `clearable_cache.dart` | `ClearableCache` interface, `CachePurgeLevel`, `CachePurgeAction`, `CachePurgeReport` |
| `cache_service.d# services/network/ — Network Communication
## HTTP (`http_service.dart`)
Dio-based REST client. `HttpService` is the entrypoint — it holds core boilerplate and named
sub-service instances. Each sub-service lives in `api/` and handles one domain area → `api/CLAUDE.md`
**Sub-services (accessed via `HttpSvc.<sub-service>.<method>()`):**
| Property | Class | File | Key Methods |
|---|---|---|---|
| `server` | `ServerApi` | `api/server_api.dart` | `ping`, `lockMac`, `restartImessage`, `serverInfo`, `sof# helpers/ui/ — UI Utility Functions
Pure helper functions and small utility classes for the UI layer. No service dependencies; no state.
## File Routing
| File | What's inside |
|------|---------------|
| `ui_helpers.dart` | General widget utilities; custom back button with gesture support |
| `theme_helpers.dart` | `HexColor` (hex string → `Color`), `BubbleColors` theme extension, desktop window effects (Mica/acrylic) |
| `message_widget_helpers.dart` | `buildMessageSpans()` — rich text rendering# settings/pages/theming/ — Theme & Visual Customization
Settings panels for all visual customization: color schemes, gradients, fonts, avatars, and the full Theme Studio editor.
## Files & Subdirectories
| Path | Purpose |
|------|---------|
| `theming_panel.dart` | Entry point — top-level theme settings (skin selector, preset themes, dark mode) |
| `advanced/` | Font picker, gradient editor, custom color tokens → `CLAUDE.md` below |
| `avatar/` | Custom avatar color + image settings → `CLAUDE.m# widgets/message/chat_event/ — System / Chat Event Messages
## Files
| File | Purpose |
|------|---------|
| `chat_event.dart` | Renders system-generated chat event rows (member added/removed, name changed, group photo changed, video/audio call started, etc.) |
## Usage
Rendered instead of a normal message bubble when `message.isGroupAction == true` or `message.itemType != 0`.
## Styling
Centered, muted text without a bubble tail. Uses `context.theme.textTheme.bodySmall` with reduced opacity.
## Rela# services/backend/notifications/ — Local Notifications
`notifications_service.dart` — dispatches local notifications across all platforms.
## Notification Channels
| Channel | Purpose |
|---------|---------|
| `NEW_MESSAGE` | Incoming message notification |
| `ERROR` | App error alerts |
| `REMINDER` | Scheduled message reminders |
| `FACETIME` | Incoming FaceTime call alert |
| `FOREGROUND_SERVICE` | Android persistent foreground service notification |
## Platform Implementations
| Platform | Libra# helpers/types/classes/ — Typed Helper Classes
Utility classes that don't belong to the DTO or extension layer.
## Files
| File | Purpose |
|------|---------|
| `chat_service_type.dart` | `ChatServiceType` enum — values: `iMessage`, `SMS`, `RCS`; used when creating chats and filtering handles |
| `language_codes.dart` | ISO 639-1 language code ↔ display name mapping; used by ML Kit language identification and Smart Reply |
## Related
- Extension methods: `../extensions/extensions.dart`
- Type hel# scripts/ — Developer Scripts
## dart-fix-common-issues.sh
Runs `dart fix --apply` across the project to automatically resolve common lint issues (unused imports, deprecated APIs, etc.).
```bash
bash scripts/dart-fix-common-issues.sh
```
Run this after making broad changes or before committing if the linter is reporting auto-fixable issues.
## bump_desktop_versions.dart
Sets the 4-digit desktop version in every spot it's hardcoded:
| File | What |
|---|---|
| `windows/runner/Runner.rc` | `VERSION_AS# lib/app/layouts/startup/ — App Boot Screens
Two screens shown before the main app UI is ready.
## Files
| File | Purpose |
|------|---------|
| `splash_screen.dart` | Initial loading screen shown while services initialize; transitions to either setup or conversation list |
| `failure_to_start.dart` | Error screen shown if a fatal startup failure occurs (DB init failed, etc.) |
## Flow
`SplashScreen` → checks server connection + DB init → routes to `SetupView` (first launch) or `ConversationList`# app/components/avatars/ — Contact Avatar Widgets
Two widgets for rendering contact or group avatars throughout the app.
## Files
| File | Purpose |
|------|---------|
| `contact_avatar_widget.dart` | Single-contact avatar: shows profile photo if available, falls back to initials circle with `toColorGradient(handle.address)` gradient |
| `contact_avatar_group_widget.dart` | Group conversation avatar: stacks up to 4 individual `ContactAvatarWidget`s in a 2×2 or overlapping layout |
## Key Parameters # app/components/custom/ — Custom Flutter Widget Overrides
Override or extend built-in Flutter widgets to fix platform-specific issues or add BlueBubbles-specific behavior.
## Files
| File | Purpose |
|------|---------|
| `custom_bouncing_scroll_physics.dart` | Tweaked `BouncingScrollPhysics` with reduced overscroll; prevents excessive bounce on desktop |
| `custom_cupertino_alert_dialog.dart` | `CupertinoAlertDialog` wrapper that fixes text-scaling issues and adds dark/light mode theming |
| `custom_c# windows/ — Windows Native
## C++ Runner (`runner/`)
- `main.cpp` — entry point: COM init, `DartProject` setup, 1280×720 `FlutterWindow`, Win32 message loop
- `flutter_window.cpp/h` — `FlutterViewController` host; plugin registration on `OnCreate`
- `win32_window.cpp/h` — Win32 window base class (creation, message routing)
- `utils.cpp/h` — UTF-8 / UTF-16 helpers
- `splash_screen.cpp/h` — native splash screen shown before the Flutter engine attaches
- `store_update.cpp/h` — `bluebubbles/sto# widgets/search/ — Settings Search UI
Implements the settings search feature — finding settings panels by keyword across all settings pages.
## Files
| File | Purpose |
|------|---------|
| `settings_search_bar.dart` | Search input with 500ms debounce; skin-aware (dispatches to iOS variant) |
| `settings_search_bar_ios.dart` | iOS Cupertino-style search bar |
| `searchable_setting_item.dart` | Individual search result row |
| `settings_items_list.dart` | List container for search results and setting# services/backend/sync/ — Data Synchronization
## Managers
| File | Role |
|------|------|
| `sync_service.dart` | Entry point — decides full vs incremental; tracks `lastIncrementalSync` timestamp |
| `full_sync_manager.dart` | Bulk fetch all chats + messages (initial setup or full resync); batches 25–100 msgs/chat |
| `incremental_sync_manager.dart` | Delta sync since last run; paginated by timestamp/rowId; saves resume markers |
| `chat_sync_manager.dart` | Syncs chat list only (no messages); tra# helpers/types/extensions/ — Extension Methods
## Files
| File | Purpose |
|------|---------|
| `extensions.dart` | Barrel that exports all extension files; import this instead of individual extension files |
## What's Exported
Extension methods on: `String`, `DateTime`, `Color`, `List`, `int`, `Uint8List`, `Uri`, `BuildContext`, `Message`, `Chat`, `Handle`, `ThemeData`, and more.
Two worth knowing about because they're easy to reimplement badly:
- `Uri.hostMatches(domain)` / `Uri.hostMatchesAny(domai# lib/ — Dart Source Code
## Architecture Layers
| Directory | Role |
|-----------|------|
| `app/` | UI widgets, layouts, screens → `app/CLAUDE.md` |
| `services/` | Business logic, state, network → `services/CLAUDE.md` |
| `database/` | Models, persistence → `database/CLAUDE.md` |
| `helpers/` | Cross-cutting utilities → `helpers/CLAUDE.md` |
| `models/` | Cross-cutting DTOs and view models → `models/CLAUDE.md` |
| `utils/` | Low-level pure utilities (logger, color engine, parsers) → `utils# services/backend/interfaces/ — Isolate Interface Layer
Interfaces are the **only** public API for triggering backend operations. They route each call to the right execution context, then hydrate the returned IDs into full model objects.
## File → Resource Mapping
| File | Resource |
|------|----------|
| `app_interface.dart` | App update check, FCM data |
| `attachment_interface.dart` | Save / find / delete attachments |
| `chat_interface.dart` | Save / delete / mark-read chats |
| `contact_v2_inter# conversation_view/mixins/ — Conversation View Mixins
## Files
| File | Purpose |
|------|---------|
| `messages_service_mixin.dart` | Mixed into `MessagesView`; wires up `MessagesService` init/dispose and provides `newFunc`, `updateFunc`, `removeFunc`, and `jumpToMessage` callbacks that `MessagesService` calls when the message list changes |
## Rules
This mixin is the **only** place where message list callbacks are registered. Do not subscribe to message events directly in widget `initState` — use t# services/backend_ui_interop/ — Backend-to-UI Event Bridge
Two files. This subsystem decouples backend services from UI widgets for one-off cross-cutting events.
## Files
- `event_dispatcher.dart` — `EventDispatcher` broadcast stream; shorthand getter `EventDispatcherSvc`
- `intents.dart` — Flutter `Intent`/`Action` pairs for keyboard shortcuts and system-level commands
## EventDispatcher
A singleton `StreamController<Tuple2<String, dynamic>>.broadcast()`. Any backend service can emit a named eve# metadata/ — URL Preview Metadata Pipeline
Fetches and parses Open Graph / Twitter Card / JSON-LD / oEmbed metadata for link previews.
Replaces the former `metadata_fetch` package dependency.
Public entry point is `MetadataHelper` (`../metadata_helper.dart`), re-exported by
`helpers/helpers.dart`. Import the barrel `metadata/metadata.dart`, not individual files.
## Layout
| Directory | Responsibility |
|-----------|----------------|
| `models/` | `UrlMetadata`, `MetadataFetchResult`, `MetadataSource`# conversation_list/dialogs/ — Chat List Dialogs
## Files
| File | Purpose |
|------|---------|
| `conversation_peek_view.dart` | Pop-up preview of a chat shown on long-press (iOS 3D Touch / force-touch peek); renders a compact message list overlay without navigating away |
## Related
- Long-press trigger: `../widgets/tile/CLAUDE.md`
- Full conversation view: `lib/app/layouts/conversation_view/CLAUDE.md`
# utils/color_engine/ — Color Space Math & Theme Generation
## Files
| File | Contents |
|------|---------|
| `engine.dart` | Barrel export — re-exports `colors.dart` and `theme.dart` |
| `colors.dart` | Color space implementations: `LinearSrgb`, `Srgb`, `Oklab` with conversion math |
| `theme.dart` | Theme color derivation — generates complementary/harmonious colors from a seed |
## Purpose
This is the low-level color science layer that powers the dynamic theme system. It converts between color sp# conversation_list/widgets/footer/ — Samsung Footer
## Files
| File | Purpose |
|------|---------|
| `samsung_footer.dart` | Bottom navigation bar for the Samsung One UI skin; shows Home / Search / Settings tabs in a bottom nav style |
## Platform
Samsung One UI only. Not rendered on iOS or Material skins. Controlled via `ThemeSwitcher` in the parent conversation list pages.
## Related
- Samsung headers: `../header/CLAUDE.md`
- Parent list: `../../CLAUDE.md` (conversation_list)
# settings/pages/ — Settings Page Router
One subdirectory per settings category. Each contains one or more `*_panel.dart` files.
## Subdirectories
| Directory | Contents | Panel Count |
|-----------|----------|-------------|
| `advanced/` | Firebase, Private API, Redacted Mode, Notification Providers, Tasker, UnifiedPush | 6 |
| `conversation_list/` | Chat list appearance, pinned order | 2 |
| `desktop/` | Desktop-specific settings | 1 |
| `message_view/` | Attachment, conversation, message options ord# lib/database/ — Data Persistence
See `docs/MODELS.md` for the consolidated cross-directory entity/DTO field reference.
## Platform Abstraction
| Directory | Platform | Role |
|-----------|----------|------|
| `io/` | Android, iOS, Desktop | ObjectBox `@Entity` classes |
| `html/` | Web (deprecated) | Stubs only — do not extend → `html/CLAUDE.md` |
| `global/` | All | Shared DTOs, no DB annotations |
Conditional imports resolve the correct implementation at compile time.
## Key Entities (`io/`) # chat_creator/ — New Chat Creation
## Pages
### New (iOS-native, preferred)
- `new_chat_creator.dart` — `NewChatCreator` widget; drop-in replacement for `ChatCreator`
- `chat_creator_controller.dart` — `ChatCreatorController extends StatefulController`; owns all state and logic
- `chat_service_type.dart` — `ChatServiceType` enum (`iMessage`, `sms`, `rcs`); set `isVisible: false` to hide a type
### Legacy
- `chat_creator.dart` — original multi-skin implementation; kept as reference
- `chat_crea# lib/services/isolates/ — Background Isolate System
## Files
| File | Purpose |
|------|---------|
| `global_isolate.dart` | Base isolate manager + `IsolateRequestType` enum + `IsolateRequest`/`IsolateResponse` types |
| `incremental_sync_isolate.dart` | Lightweight sync-only subclass of `GlobalIsolate` |
| `isolate_actions.dart` | `IsolateActons.actions` — the `Map<IsolateRequestType, Function>` routing table |
| `isolate_event.dart` | `IsolateEvent` enum + `IsolateEventMessage` + `IsolateEventEmitte# database/io/ — ObjectBox Entities (Native & Desktop)
Not used on web — `database/html/` provides web stubs.
After any `@Entity` annotation change: **`dart run build_runner build`**
## Entities
| File | Key Fields | Relations |
|------|-----------|-----------|
| `chat.dart` | guid (unique+indexed), chatIdentifier, isArchived, isPinned, muteType, displayName | → dbLatestMessage (ToOne), → messages (ToMany backlink), → handles (ToMany) / participants (transient mirror) |
| `message.dart` | guid # widgets/message/ — Message Rendering (54+ files)
A message renders as a composition of specialized sub-widgets.
## Component Routing
| Directory | Renders | Details |
|-----------|---------|---------|
| `message_holder/` | Outer bubble, alignment, tail, sender name | → CLAUDE.md inside |
| `text/` | Text content inside bubble | |
| `attachment/` | Images, video, audio, stickers, contact cards | → CLAUDE.md inside |
| `reaction/` | Tapback emoji display and picker | → CLAUDE.md inside |
| `reply/# services/ui/chat/ — Chat List & Conversation State
## Files
| File | Purpose |
|------|---------|
| `chats_service.dart` | Global chat list state — the source of truth for all `ChatState` objects |
| `conversation_view_controller.dart` | Per-chat controller for the active conversation screen |
| `message_list_gate.dart` | FIFO gate that defers message list mutations while a send animation is in flight |
---
## ChatsService (`chats_service.dart`)
GetIt singleton. Accessed via `ChatsSvc`.
**What it# lib/app/ — UI Layer
## Major Subsystems
- `layouts/conversation_view/` — message thread UI → `CLAUDE.md` inside
- `layouts/conversation_list/` — chat list/inbox → `CLAUDE.md` inside
- `layouts/settings/` — preferences → `CLAUDE.md` inside
- `layouts/setup/` — onboarding flow → `CLAUDE.md` inside
- `layouts/conversation_details/` — chat info panel → `CLAUDE.md` inside
- `layouts/chat_creator/` — new chat creation → `CLAUDE.md` inside
- `layouts/findmy/` — Find My device locator# services/backend/filesystem/ — File System Service
## File
`filesystem_service.dart` — `FilesystemService` (registered with GetIt via `FileSystemSvc` shorthand)
## Responsibilities
- Resolves platform-specific paths for attachments, cache, and temp files
- Manages attachment download destinations (per-GUID subdirectories)
- Cleans up orphaned/cached files when attachments are deleted
- Copies, moves, and deletes files as part of the attachment pipeline
## Key Methods
- `getAttachmentPath(Attachment# widgets/message/typing/ — Typing Indicator
## Files
| File | Purpose |
|------|---------|
| `typing_indicator.dart` | Animated three-dot typing bubble shown when a participant is composing; driven by socket events |
| `typing_clipper.dart` | `CustomClipper` that shapes the typing bubble's rounded tail |
## Lifecycle
`TypingIndicator` appears at the bottom of the message list when `ChatState.showTypingIndicator` is true.
The `ChatsService` toggles this flag when the server sends a `typing` socket event# services/backend/actions/ — Isolate Action Implementations
Actions are pure functions that run **inside** the background isolate. They perform ObjectBox reads/writes and return primitive values (IDs, maps, booleans) — never full model objects with DB relations.
## File → Resource Mapping
| File | Resource |
|------|----------|
| `app_actions.dart` | App update check, FCM data |
| `attachment_actions.dart` | Save / find / delete attachments |
| `chat_actions.dart` | Save / delete / mark-read chats,# helpers/backend/ — Backend Bootstrap & Service Helpers
## File Routing
| File | What's inside |
|------|---------------|
| `startup_tasks.dart` | `StartupTasks` — ordered service initialization; the single source of truth for startup sequence |
| `settings_helpers.dart` | `saveNewServerUrl()`, `clearServerUrl()`, `disableBatteryOptimizations()` — convenience wrappers for common settings mutations |
| `foreground_service_helpers.dart` | `runForegroundService()`, `restartForegroundService()` — And# misc/ — Message Utilities & Composition Dispatcher
Shared utilities that don't belong to a single message type. The most important file here is `message_part_content.dart`, which decides what to render for each part of a message.
## Files
| File | Purpose |
|------|---------|
| `message_part_content.dart` | **Central dispatcher** — routes each message part to text, attachment, or interactive |
| `message_properties.dart` | Effect label, reply count badge, edit indicator (below bubble) |
| `message_# widgets/content/ — Reusable Settings Tile Building Blocks
These are the **primary building blocks** for all settings pages. Assemble settings UIs by composing these widgets — do not build custom `ListTile` rows from scratch.
## Files
| Widget | File | Purpose |
|--------|------|---------|
| `SettingsTile` | `settings_tile.dart` | Base row: title, subtitle, leading icon, trailing widget, onTap |
| `SettingsSwitch` | `settings_switch.dart` | Toggle row with a `BBSwitch` (skin-aware — `lib/app/compo# conversation_view/dialogs/ — Conversation Dialogs
## Files
| File | Purpose |
|------|---------|
| `custom_mention_dialog.dart` | `@mention` autocomplete dialog shown while typing `@` in the text field; fetches matching handles and inserts the mention on selection |
## Related
- Text field: `../widgets/text_field/CLAUDE.md`
- Handle lookup: `lib/services/backend/interfaces/handle_interface.dart`
# database/migrations/ — ObjectBox Schema Migrations
Contains migration scripts that run when the database version is incremented.
## Files
| File | Purpose |
|------|---------|
| `message_handle_relationship_migration.dart` | Migrates legacy message→handle relationships to the new N:M `ToMany` schema |
| `chat_latest_message_migration.dart` | Backfills `Chat.dbLatestMessage` / `dbOnlyLatestMessageDate` |
## How Migrations Work
1. `database.dart` stores `Database.version`
2. On startup, if the store# settings/pages/server/ — Server Connection & Management
Settings panels for managing the BlueBubbles server connection, authentication, backup/restore, and iMessage statistics.
## Files (top-level)
| File | Purpose |
|------|---------|
| `server_management_panel.dart` | Main server settings panel: URL, QR scan, ping, restart server |
| `backup_restore_panel.dart` | Backup/restore UI for settings + themes |
| `backup_restore_actions.dart` | Backup/restore data operations (fetch, delete, device default# services/backend/java_dart_interop/ — Dart ↔ Android Bridge
Three files that form the Dart side of the Android method channel bridge. The Kotlin side lives in `android/app/src/main/kotlin/com/bluebubbles/messaging/`.
For the full Android bridge overview, see `android/CLAUDE.md`.
## Files
### `method_channel_service.dart` — `MethodChannelService` / `MethodChannelSvc`
GetIt singleton. The primary bridge between Dart and Android. Uses `MethodChannel('com.bluebubbles.messaging')`.
**Calling Androi# widgets/text_field/ — Message Composer
## Files (top-level)
- `conversation_text_field.dart` — composer entry point / orchestration
- `conversation_text_field_local_controller.dart` — local (non-service) text field controller state
- `text_field_component.dart` — main composable text input widget
- `send_button.dart` — send / schedule button
- `text_field_icon_bar.dart` — attachment/emoji/etc. icon row
- `text_field_suffix.dart` — trailing icon(s) inside the field
- `text_field_emoji_picker# lib/app/wrappers/ — Base Widget Classes & Scaffold Composition
## State Base Classes → `stateful_boilerplate.dart`
Pick the right base for every stateful widget:
| Class | Use when |
|-------|----------|
| `CustomStateful<T>` + `CustomState<T, R, S>` | Widget owns or shares a `StatefulController` |
| `StatelessWidget` | No state |
See `.claude/rules/frontend.md` for full controller tagging, `forceDelete`, and `Obx` rules.
## Scaffold & Layout
- `bb_scaffold.dart` — use instead of raw `Scaffold`# services/backend/ — Server Interaction
## Request Pattern
Each resource has an interface and a concrete action file → `interfaces/CLAUDE.md` + `actions/CLAUDE.md`
- `interfaces/chat_interface.dart` → `actions/chat_actions.dart`
- `interfaces/message_interface.dart` → `actions/message_actions.dart`
- (same for: app, attachment, contact_v2, handle, image, log, prefs, send_message, server, sync, test)
## Sync System (`sync/`) → `sync/CLAUDE.md`
- `sync_service.dart` — coordinator
- `full_sync_m# findmy/widgets/ — Find My UI Widgets
Sub-widgets for the Find My device/friends/items tracking screen.
## Files
| File | Purpose |
|------|---------|
| `findmy_map_widget.dart` | Interactive map overview showing all tracked devices and friends |
| `findmy_devices_tab_view.dart` | Tab content listing the user's own Apple devices |
| `findmy_friends_tab_view.dart` | Tab content listing shared-location friends |
| `findmy_items_tab_view.dart` | Tab content listing AirTag / Find My accessory items |
| `f# services/backend/settings/ — Settings Persistence
## Files
### `settings_service.dart` — `SettingsService` / `SettingsSvc`
GetIt singleton. The authoritative source for all app settings at runtime.
- Holds the `Settings` object (defined in `lib/database/global/settings.dart`) as `SettingsSvc.settings`
- All settings fields are `Rx*` observables — widgets can `Obx()` directly on any field
- Reads/writes settings via `PrefsInterface` → `PrefsActions` → ObjectBox in the GlobalIsolate
**Reading# settings/pages/advanced/ — Advanced Settings Panels
Integration-level settings panels for power users and developers.
## Files
| File | Purpose |
|------|---------|
| `firebase_panel.dart` | Firebase project config (API key, project ID, sender ID) for FCM push delivery |
| `private_api_panel.dart` | Private API feature toggles: typing status, read receipts, send-as-SMS fallback, force SMS |
| `redacted_mode_panel.dart` | Redacted Mode settings: hide message content, avatars, names in screenshots |
| # settings/pages/misc/ — Miscellaneous Settings Panels
## Files
| File | Purpose |
|------|---------|
| `about_panel.dart` | App version, credits, links to GitHub and privacy policy |
| `logging_panel.dart` | View and export saved log files |
| `live_logging_panel.dart` | Real-time scrolling log output (debug mode) |
| `misc_panel.dart` | Miscellaneous tweaks: haptics, URL handling, Smart Reply, send-on-enter |
| `soft_deleted_chats_panel.dart` | View/restore chats that were soft-deleted locally |
| `tr# GitHub Copilot Instructions — BlueBubbles App
This project uses CLAUDE.md files as the authoritative source for all coding conventions, architecture guidance, and workflow rules. Follow them exactly.
## Required Reading (load before making changes)
- **Project overview & key conventions** → [CLAUDE.md](../CLAUDE.md)
- **Workflow, code generation, lint** → [.claude/CLAUDE.md](../.claude/CLAUDE.md)
## Coding Standards (`.claude/rules/`)
Load the relevant rule file(s) before writing any code:
- *none