From 0269d934953f9e65b3bc0ee54ecf65bc49549325 Mon Sep 17 00:00:00 2001 From: Sergei Bakhtiarov Date: Mon, 23 Mar 2026 16:39:27 +0100 Subject: [PATCH 1/3] fix: banner flicker (WPB-23994) --- .github/workflows/pr-review-service.yml | 157 ++++++++++++++++++ .../topappbar/CommonTopAppBarViewModel.kt | 47 ++++-- 2 files changed, 187 insertions(+), 17 deletions(-) create mode 100644 .github/workflows/pr-review-service.yml diff --git a/.github/workflows/pr-review-service.yml b/.github/workflows/pr-review-service.yml new file mode 100644 index 00000000000..9afa2c59ae1 --- /dev/null +++ b/.github/workflows/pr-review-service.yml @@ -0,0 +1,157 @@ +name: "Automated PR Review" + +on: + pull_request: + types: [opened, synchronize, reopened] + +permissions: + contents: read + pull-requests: write + issues: write + +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number }} + cancel-in-progress: true + +jobs: + pr-review: + if: github.event.pull_request.head.repo.full_name == github.repository + runs-on: ubuntu-latest + timeout-minutes: 5 + env: + GH_TOKEN: ${{ github.token }} + REVIEW_SERVICE_URL: http://91.99.71.160:8080/review-pr + COMMENT_MARKER: '' + PR_NUMBER: ${{ github.event.pull_request.number }} + PR_URL: ${{ github.event.pull_request.html_url }} + REPOSITORY: ${{ github.repository }} + steps: + - name: Generate automated review and update PR comment + shell: bash + run: | + set -u + + comment_id="$( + gh api "repos/${REPOSITORY}/issues/${PR_NUMBER}/comments" --paginate \ + --jq ".[] | select(.body | contains(\"${COMMENT_MARKER}\")) | .id" \ + | head -n 1 + )" + + summarize_failure() { + local message="$1" + + { + echo "### Automated PR Review" + echo "${message}" + } >> "$GITHUB_STEP_SUMMARY" + } + + publish_comment() { + local body_file="$1" + local request_json + + request_json=$(mktemp) + jq -Rs '{body: .}' < "${body_file}" > "${request_json}" + + if [ -n "${comment_id}" ]; then + gh api "repos/${REPOSITORY}/issues/comments/${comment_id}" \ + -X PATCH \ + --input "${request_json}" >/dev/null + else + gh api "repos/${REPOSITORY}/issues/${PR_NUMBER}/comments" \ + --input "${request_json}" >/dev/null + fi + } + + create_failure_comment_if_missing() { + if [ -n "${comment_id}" ]; then + return + fi + + local body + body=$(mktemp) + { + echo "${COMMENT_MARKER}" + echo "## Automated PR Review" + echo + echo "_Automated review could not be generated for this run._" + } > "${body}" + + publish_comment "${body}" + } + + payload=$(mktemp) + response=$(mktemp) + error_log=$(mktemp) + comment_body=$(mktemp) + + jq -n --arg pr_url "${PR_URL}" '{pr_url: $pr_url}' > "${payload}" + + http_code="$( + curl \ + --silent \ + --show-error \ + --output "${response}" \ + --write-out "%{http_code}" \ + --max-time 60 \ + -X POST "${REVIEW_SERVICE_URL}" \ + -H "Content-Type: application/json" \ + --data "@${payload}" \ + 2>"${error_log}" + )" + curl_exit_code=$? + + if [ "${curl_exit_code}" -ne 0 ]; then + error_message=$(cat "${error_log}") + summarize_failure "Review service request failed: ${error_message:-curl exited with code ${curl_exit_code}}" + create_failure_comment_if_missing + exit 0 + fi + + if [ "${http_code}" -lt 200 ] || [ "${http_code}" -ge 300 ]; then + summarize_failure "Review service returned HTTP ${http_code}." + create_failure_comment_if_missing + exit 0 + fi + + if ! jq -e . "${response}" >/dev/null 2>&1; then + summarize_failure "Review service returned invalid JSON." + create_failure_comment_if_missing + exit 0 + fi + + status=$(jq -r '.status // empty' "${response}") + if [ "${status}" != "ok" ]; then + summarize_failure "Review service returned status '${status:-missing}'." + create_failure_comment_if_missing + exit 0 + fi + + review_markdown=$(jq -r '.review_markdown // empty' "${response}") + if [ -z "${review_markdown}" ]; then + summarize_failure "Review service returned no review markdown." + create_failure_comment_if_missing + exit 0 + fi + + model=$(jq -r '.model // "unknown"' "${response}") + elapsed_ms=$(jq -r '.elapsed_ms // "unknown"' "${response}") + + { + echo "${COMMENT_MARKER}" + echo "## Automated PR Review" + echo + echo "_Generated by \`${model}\` in ${elapsed_ms} ms._" + echo + printf '%s\n' "${review_markdown}" + } > "${comment_body}" + + if ! publish_comment "${comment_body}"; then + summarize_failure "Review was generated, but publishing the PR comment failed." + exit 1 + fi + + { + echo "### Automated PR Review" + echo "Review comment posted successfully." + } >> "$GITHUB_STEP_SUMMARY" diff --git a/app/src/main/kotlin/com/wire/android/ui/common/topappbar/CommonTopAppBarViewModel.kt b/app/src/main/kotlin/com/wire/android/ui/common/topappbar/CommonTopAppBarViewModel.kt index 81e935e6028..98cb5b581d0 100644 --- a/app/src/main/kotlin/com/wire/android/ui/common/topappbar/CommonTopAppBarViewModel.kt +++ b/app/src/main/kotlin/com/wire/android/ui/common/topappbar/CommonTopAppBarViewModel.kt @@ -66,7 +66,10 @@ class CommonTopAppBarViewModel @Inject constructor( coreLogic.get().sessionScope(userId) { combine(observeSyncState(), coreLogic.get().networkStateObserver.observeNetworkState()) { syncState, networkState -> when (syncState) { - is Waiting -> Connectivity.WaitingConnection(null, null) + // Waiting is a pure pre-initialization state: the sync worker has not been + // scheduled yet. It carries no information about network health, so map it + // to Connected (no banner) rather than WaitingConnection or Connecting. + is Waiting -> Connectivity.Connected is Failed -> Connectivity.WaitingConnection(syncState.cause, syncState.retryDelay) is GatheringPendingEvents, is SlowSync -> Connectivity.Connecting @@ -79,6 +82,17 @@ class CommonTopAppBarViewModel @Inject constructor( } } } + }.debounce { connectivity -> + when (connectivity) { + // Pass through immediately so the banner is dismissed without delay + // once sync finishes, and any pending debounce timer in the per-session + // debounce below is canceled before it can show a stale banner. + Connectivity.Connected -> 0L + // Hold Connecting / WaitingConnection for the full debounce window. + // If sync or network recovers within that window the timer is canceled + // and no banner is ever shown. + else -> CONNECTIVITY_STATE_DEBOUNCE_DEFAULT + } } @VisibleForTesting @@ -112,25 +126,24 @@ class CommonTopAppBarViewModel @Inject constructor( connectivityFlow(userId), ) { activeCalls, currentScreen, connectivity -> mapToConnectivityUIState(currentScreen, connectivity, userId, activeCalls) + }.debounce { state -> + // Scoped inside flatMapLatest so this debounce is canceled + // together with the inner flow on session change, preventing + // stale state from leaking into a new session. + when { + // Delay the ongoing-call bar slightly to absorb rapid + // mute/unmute state changes without flickering. + state is ConnectivityUIState.Calls && state.hasOngoingCall -> + CONNECTIVITY_STATE_DEBOUNCE_ONGOING_CALL + // Everything else (connectivity banners, incoming/outgoing + // calls, None) passes through immediately. Connectivity + // states are already debounced inside connectivityFlow. + else -> 0L + } } } } } - .debounce { state -> - /** - * Adding some debounce here to avoid some bad UX and prevent from having blinking effect when the state changes - * quickly, e.g. when displaying ongoing call banner and hiding it in a short time when the user hangs up the call. - * Call events could take some time to be received and this function could be called when the screen is changed, - * so we delayed showing the banner until getting the correct calling values and for calls this debounce is bigger - * than for other states in order to allow for the correct handling of hanging up a call. - * When state changes to None, handle it immediately, that's why we return 0L debounce time in this case. - */ - when { - state is ConnectivityUIState.None -> 0L - state is ConnectivityUIState.Calls && state.hasOngoingCall -> CONNECTIVITY_STATE_DEBOUNCE_ONGOING_CALL - else -> CONNECTIVITY_STATE_DEBOUNCE_DEFAULT - } - } .collectLatest { connectivityUIState -> state = state.copy(connectivityState = connectivityUIState) } @@ -181,6 +194,6 @@ class CommonTopAppBarViewModel @Inject constructor( private companion object { const val CONNECTIVITY_STATE_DEBOUNCE_ONGOING_CALL = 600L - const val CONNECTIVITY_STATE_DEBOUNCE_DEFAULT = 200L + const val CONNECTIVITY_STATE_DEBOUNCE_DEFAULT = 1000L } } From 9db6734e93596415dcf390402764d12a41e81b81 Mon Sep 17 00:00:00 2001 From: Sergei Bakhtiarov Date: Wed, 1 Apr 2026 12:55:52 +0200 Subject: [PATCH 2/3] Add repository docs and update kalium submodule --- docs/README.md | 31 ++++ docs/architecture.md | 223 ++++++++++++++++++++++++++++ docs/dependencies.md | 196 ++++++++++++++++++++++++ docs/features.md | 222 +++++++++++++++++++++++++++ docs/general-project-description.md | 104 +++++++++++++ docs/project-structure.md | 216 +++++++++++++++++++++++++++ kalium | 2 +- 7 files changed, 993 insertions(+), 1 deletion(-) create mode 100644 docs/README.md create mode 100644 docs/architecture.md create mode 100644 docs/dependencies.md create mode 100644 docs/features.md create mode 100644 docs/general-project-description.md create mode 100644 docs/project-structure.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000000..0a197c4fbc6 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,31 @@ +# Wire Android Documentation + +This documentation set describes the `wire-android` repository for engineers who are onboarding to the codebase or preparing retrieval-friendly reference material. + +Each document is intentionally scoped, sectioned, and cross-linked so it can be indexed in a RAG pipeline without depending on one large README. + +## Documentation Map + +- [General Project Description](./general-project-description.md) +- [Project Structure](./project-structure.md) +- [Architecture](./architecture.md) +- [Dependencies](./dependencies.md) +- [Features](./features.md) + +## Existing Reference Material + +- [Architecture Decision Records](./adr/) +- Root-level project overview: [`README.md`](../README.md) +- Contribution guide: [`CONTRIBUTING.md`](../CONTRIBUTING.md) + +## How To Use This Documentation + +Use [General Project Description](./general-project-description.md) to understand what the repository contains and how it fits into Wire as a product and open-source project. + +Use [Project Structure](./project-structure.md) to locate modules, included builds, and top-level responsibilities. + +Use [Architecture](./architecture.md) to understand runtime flow, dependency injection, navigation, background processing, and the boundary with `kalium`. + +Use [Dependencies](./dependencies.md) to understand build tooling, first-party module relationships, included-build substitution, and major third-party libraries. + +Use [Features](./features.md) to map end-user capabilities and platform capabilities to app packages and feature modules. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 00000000000..2534e0b8450 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,223 @@ +# Architecture + +This document describes the main runtime architecture of the Android app, the dependency direction between module families, and the boundary between this repository and the included `kalium` build. + +For the repository map, see [Project Structure](./project-structure.md). For dependency inventories, see [Dependencies](./dependencies.md). + +## Purpose + +The architecture of `wire-android` follows a layered integration model: + +- the Android application layer lives in `app/` +- reusable Android building blocks live in `core/*` +- feature-focused Android UI lives in `features/*` +- shared business logic and lower-level capabilities come from `kalium` + +This repo does not implement every layer directly. Much of the domain and data-facing behavior is delegated to `kalium`, while this repo focuses on Android runtime integration and user-facing UI. + +## Runtime Entry Flow + +### Application Startup + +The Android process starts in `WireApplication`, which is annotated with `@HiltAndroidApp`. + +At startup, `WireApplication` configures and coordinates: + +- Hilt-backed application dependency injection +- global logging setup +- StrictMode in debug builds +- WorkManager configuration through a custom `WireWorkerFactory` +- lifecycle observers and global observers +- sync-related background observation +- analytics observation +- call background-state observation +- asset-upload observation and worker enqueueing + +This makes `WireApplication` the application-level composition root for process-wide services. + +### Activity Shell + +The main user-facing shell is `WireActivity`. + +`WireActivity` is responsible for: + +- installing and holding the splash screen until first draw +- selecting the initial destination based on app state and login mode +- setting the Compose content tree +- handling new intents and deep links +- integrating dynamic receivers and managed configurations +- providing activity-scoped coordination for top-level UI, dialogs, and navigation events + +### Navigation Host + +`MainNavHost` hosts the top-level Compose Destinations graph. + +Its role includes: + +- creating the navigation engine +- mounting the root navigation graph +- sharing selected Hilt view models across nested navigation graphs +- wiring cross-module destination dependencies +- keeping selected manual composable calls where generated wiring is not sufficient yet + +This design allows feature modules to contribute destinations while the app module remains the top-level orchestration point. + +## Dependency Injection + +### Purpose + +Dependency injection is handled with Hilt and acts as the bridge between Android framework code and `kalium` use cases or services. + +### Key Components + +- app-scoped Hilt modules in `app/src/main/kotlin/com/wire/android/di` +- account-scoped Hilt modules in `app/src/main/kotlin/com/wire/android/di/accountScoped` +- `WireApplication` and Android entry points such as `WireActivity` + +### How It Connects + +The DI layer constructs: + +- application-level infrastructure such as logging, WorkManager, and configuration managers +- a shared `CoreLogic` instance from `kalium` +- session-aware and account-aware use cases derived from the current session +- feature-specific bindings consumed by view models and Android services + +This means the DI layer is a key architectural seam. Android code does not manually construct most business-layer objects; it receives them from Hilt, and Hilt in turn adapts them from `kalium`. + +## Module Layering + +### Purpose + +The repository uses module layering to keep Android concerns separated from reusable Android support code and feature-specific UI. + +### Key Components + +- `app/` integrates everything +- `core/*` provides reusable support code +- `features/*` provides isolated feature libraries +- `kalium` provides shared logic/data/domain capabilities + +### Dependency Direction + +At a high level, the dependency flow is: + +- `app` depends on `core/*`, `features/*`, and `kalium` +- `features/*` depend on selected `core/*` modules and `kalium` +- `core/*` may depend on `kalium` where shared logic or data APIs are needed +- `tests/*` depend on app-facing modules for verification support + +The intended architectural direction is inward toward shared logic. Android-specific code depends on reusable support layers and `kalium`, not the other way around. + +## Navigation Architecture + +### Purpose + +Navigation is Compose-based and type-aware. + +### Key Components + +- Jetpack Navigation Compose +- Compose Destinations +- `core:navigation` +- app-level nav graph declarations and host wiring + +### How It Connects + +Navigation definitions are spread across app and feature modules, but the top-level host remains in the app module. Shared transitions, destination styles, typed routes, and shared graph-scoped view models are coordinated centrally. + +This pattern allows modular feature navigation without fully decentralizing the runtime shell. + +## Background Work, Sync, And Notifications + +### Purpose + +The app performs background observation and worker-based coordination for sync and platform events. + +### Key Components + +- WorkManager integration in `WireApplication` +- custom worker factory +- workers such as `AssetUploadObserverWorker`, `NotificationFetchWorker`, `PersistentWebsocketCheckWorker`, and `DeleteConversationLocallyWorker` +- notification support in `core:notification` and app notification packages +- sync-related surfaces in `features:sync` and app sync UI packages + +### How It Connects + +The app observes state from `kalium` and other Android services, then schedules or executes Android-native work through WorkManager and notification channels. This keeps platform execution details in the Android repo while allowing shared logic to remain in `kalium`. + +## Analytics And Flavor-Dependent Behavior + +### Purpose + +Analytics and some integrations are flavor-dependent rather than uniform across all builds. + +### Key Components + +- `core:analytics` +- `core:analytics-enabled` +- `core:analytics-disabled` +- flavor configuration from `default.json` +- conditional plugin and dependency setup in Gradle + +### How It Connects + +The app module chooses analytics-enabled or analytics-disabled implementations per flavor. Similar flavor-aware behavior also affects Google services, developer tooling, logging, and the F-Droid build path. + +This is an architectural concern because some runtime behavior is selected at build time rather than only at runtime. + +## The `kalium` Boundary + +### Purpose + +`kalium` is an included build that provides shared logic and lower-level capabilities used by the Android app. + +### Key Components + +The Android build substitutes selected `com.wire.kalium:*` dependencies with local projects from the included `kalium` build, including: + +- `kalium-logic` +- `kalium-util` +- `kalium-data` +- `kalium-common` +- `kalium-cells` +- selected test-facing modules + +### How It Connects + +From the Android repo perspective, `kalium` supplies capabilities such as: + +- `CoreLogic` +- session and account handling +- messaging and calling use cases +- data and persistence-facing APIs +- network-facing abstractions +- shared domain logic for Cells and other features + +The Android app does not duplicate those layers. Instead, it adapts them into Android entry points, Hilt bindings, Compose screens, notification flows, and WorkManager jobs. + +This makes `kalium` an architectural boundary, not just a library dependency. + +## ADRs Related To Architecture + +The existing ADR set in `docs/adr/` records several architecture-affecting decisions, including: + +- deep link handling refactors +- calling activity refactors +- conversation list composable refactors +- enterprise login flow support +- UI Automator adoption +- EMM config capabilities +- tablet dialog navigation parity after Compose Destinations upgrade + +These ADRs are useful when the current architecture looks unusual or carries historical constraints. + +## Where To Look + +- Application entry point: [`../app/src/main/kotlin/com/wire/android/WireApplication.kt`](../app/src/main/kotlin/com/wire/android/WireApplication.kt) +- Main activity shell: [`../app/src/main/kotlin/com/wire/android/ui/WireActivity.kt`](../app/src/main/kotlin/com/wire/android/ui/WireActivity.kt) +- Main navigation host: [`../app/src/main/kotlin/com/wire/android/navigation/MainNavHost.kt`](../app/src/main/kotlin/com/wire/android/navigation/MainNavHost.kt) +- Manifest entry points: [`../app/src/main/AndroidManifest.xml`](../app/src/main/AndroidManifest.xml) +- Hilt modules: [`../app/src/main/kotlin/com/wire/android/di/`](../app/src/main/kotlin/com/wire/android/di/) +- Included build substitution: [`../include_builds.gradle.kts`](../include_builds.gradle.kts) +- ADRs: [`./adr/`](./adr/) diff --git a/docs/dependencies.md b/docs/dependencies.md new file mode 100644 index 00000000000..dc056a0d6df --- /dev/null +++ b/docs/dependencies.md @@ -0,0 +1,196 @@ +# Dependencies + +This document describes the build stack, first-party module relationships, included-build substitution, and major third-party libraries used in the repository. + +For the module map, see [Project Structure](./project-structure.md). For runtime integration details, see [Architecture](./architecture.md). + +## Purpose + +`wire-android` uses a mixed dependency model: + +- local Gradle modules inside this repository +- included builds for shared build logic and shared Wire logic +- external Android, Kotlin, and tooling libraries +- flavor-dependent dependencies that change by distribution target + +## Build System And Plugin Stack + +### Purpose + +The project uses Gradle Kotlin DSL with central version management and convention plugins. + +### Key Components + +- root `build.gradle.kts` +- root `settings.gradle.kts` +- `gradle/libs.versions.toml` +- included build `build-logic` +- standard Android, Kotlin, KSP, Compose, and CycloneDX plugins + +### How It Connects + +The root build declares shared plugins and repositories, while `build-logic` supplies repository-specific convention plugins such as: + +- `com.wire.android.application` +- `com.wire.android.library` +- `com.wire.android.test.library` +- `com.wire.android.navigation` +- `com.wire.android.kmp.library` +- `com.wire.android.hilt` +- `com.wire.android.kover` +- `com.wire.android.versionizer` + +This keeps individual module build files relatively small and consistent. + +## First-Party Module Dependencies + +### App Module Dependencies + +`app/` depends directly on: + +- `core:ui-common` +- `core:di` +- `core:media` +- `core:notification` +- `features:cells` +- `features:sketch` +- `features:meetings` +- `features:sync` +- `core:analytics-enabled` or `core:analytics-disabled`, selected by flavor +- `com.wire.kalium:*` dependencies such as `kalium-logic`, `kalium-util`, and `kalium-cells` + +### Core Module Patterns + +Core modules provide reusable support libraries. Examples: + +- `core:navigation` depends on `core:ui-common` plus navigation libraries +- `core:notification` depends on `core:media` and selected `kalium` modules +- `core:ui-common` depends on `kalium-logic` and shared Compose/Hilt infrastructure + +### Feature Module Patterns + +Feature modules depend on shared UI and selected `kalium` APIs. Examples: + +- `features:cells` depends on `core:ui-common`, `kalium-common`, `kalium-logic`, and `kalium-cells` +- `features:meetings` depends on `core:ui-common` and `kalium` +- `features:sync` depends on `core:notification`, `core:ui-common`, `core:di`, and `kalium` +- `features:sketch` primarily depends on `core:ui-common` and Compose/UI support + +## Included Builds And Substitution + +### Purpose + +The repository uses included builds to keep local development aligned across shared codebases. + +### Key Components + +- `includeBuild("build-logic")` +- `includeBuild("kalium")` +- dependency substitution in `include_builds.gradle.kts` + +### How It Connects + +When the Android app depends on selected `com.wire.kalium:*` coordinates, the build substitutes them with local `kalium` projects during the included-build workflow. + +This means local development can consume `kalium` source directly instead of only relying on published artifacts. The substitution currently covers modules such as: + +- `com.wire.kalium:kalium-logic` +- `com.wire.kalium:kalium-util` +- `com.wire.kalium:kalium-data` +- `com.wire.kalium:kalium-common` +- `com.wire.kalium:kalium-cells` +- test-facing modules like `kalium-mocks` and `kalium-network` + +From a documentation perspective, this is one of the most important dependency facts in the repo. + +## Major Third-Party Libraries + +### Android And Platform + +- AndroidX core libraries +- AppCompat +- DataStore +- SplashScreen +- Browser +- Biometric +- Startup +- WorkManager + +### UI And Navigation + +- Jetpack Compose BOM and Compose UI libraries +- Material and Material3 +- Navigation Compose +- Compose Destinations +- Accompanist placeholder support +- Coil for image loading + +### Dependency Injection And Code Generation + +- Hilt +- KSP +- JavaPoet + +### Kotlin And Concurrency + +- Kotlinx Coroutines +- Kotlinx Serialization +- Kotlinx Datetime +- Kotlinx Immutable Collections + +### Logging, Analytics, And Reporting + +- DataDog SDK integration paths +- Countly in analytics-enabled builds +- AboutLibraries for license/about screens +- CycloneDX for SBOM generation + +### Testing And Quality + +- JUnit 4 and JUnit 5 +- MockK +- Turbine +- Robolectric +- Espresso +- AndroidX test libraries +- UI Automator +- Allure Kotlin +- Kover +- Detekt + +## Flavor-Specific And Optional Dependencies + +### Google Services + +The root build conditionally includes the Google services Gradle plugin depending on whether the build is targeting F-Droid. + +### Analytics + +The app selects either analytics-enabled or analytics-disabled implementations by flavor using values loaded from `default.json`. + +### FOSS Versus Non-Free Source Sets + +The app module configures flavor-specific source-set additions for: + +- internal versus public logging paths +- FOSS versus non-free code +- F-Droid-specific behavior and resources + +This affects not only runtime features but also which dependencies and source directories participate in the build. + +## Dependency Management Conventions + +Centralized versions live in `gradle/libs.versions.toml`. + +Most module build files use the shared version catalog and convention plugins rather than declaring fully custom dependency-management logic. + +The build also generates a CycloneDX software bill of materials from the root build. + +## Where To Look + +- Root build: [`../build.gradle.kts`](../build.gradle.kts) +- Root settings: [`../settings.gradle.kts`](../settings.gradle.kts) +- Version catalog: [`../gradle/libs.versions.toml`](../gradle/libs.versions.toml) +- Included-build substitution: [`../include_builds.gradle.kts`](../include_builds.gradle.kts) +- App module dependencies: [`../app/build.gradle.kts`](../app/build.gradle.kts) +- Kalium overview: [`../kalium/README.md`](../kalium/README.md) diff --git a/docs/features.md b/docs/features.md new file mode 100644 index 00000000000..887e02afbb1 --- /dev/null +++ b/docs/features.md @@ -0,0 +1,222 @@ +# Features + +This document groups the repository's visible capabilities into feature areas and notes where each capability is implemented in the Android repo. + +The descriptions in this document are derived from module names, package structure, manifests, flavor configuration, and app/runtime wiring. For architectural context, see [Architecture](./architecture.md). + +## Purpose + +The repository combines end-user features, platform integration features, and internal tooling features. Not every capability is isolated into its own Gradle module; many live directly in the app module and are supported by `core/*`, `features/*`, and `kalium`. + +## Authentication And Account Access + +### Purpose + +The app supports sign-in, account entry flows, and related account-state transitions. + +### Key Components + +- app packages under `ui/authentication`, `ui/newauthentication`, and `ui/registration` +- login support packages under `feature/login` +- deep-link and SSO-related manifest entries +- session and account use cases provided through Hilt from `kalium` + +### How It Connects + +Authentication UI lives primarily in the app module, while account/session logic is adapted from `kalium`. + +### Where To Look + +- [`../app/src/main/kotlin/com/wire/android/ui/authentication`](../app/src/main/kotlin/com/wire/android/ui/authentication) +- [`../app/src/main/kotlin/com/wire/android/ui/newauthentication`](../app/src/main/kotlin/com/wire/android/ui/newauthentication) +- [`../app/src/main/kotlin/com/wire/android/ui/registration`](../app/src/main/kotlin/com/wire/android/ui/registration) +- [`../app/src/main/kotlin/com/wire/android/feature/login`](../app/src/main/kotlin/com/wire/android/feature/login) + +## Conversations, Messaging, And Home UI + +### Purpose + +The app includes conversation-centric flows for browsing conversations, opening message threads, composing messages, sharing content, and navigating the main logged-in experience. + +### Key Components + +- `ui/home/conversations` +- `ui/home/conversationslist` +- `ui/home/messagecomposer` +- `ui/sharing` +- `ui/joinConversation` +- `ui/home/newconversation` + +### How It Connects + +The app module owns much of the conversation UI shell, while message and conversation logic comes from `kalium` via injected use cases and session scope access. + +### Where To Look + +- [`../app/src/main/kotlin/com/wire/android/ui/home`](../app/src/main/kotlin/com/wire/android/ui/home) +- [`../app/src/main/kotlin/com/wire/android/ui/sharing`](../app/src/main/kotlin/com/wire/android/ui/sharing) +- [`../app/src/main/kotlin/com/wire/android/navigation`](../app/src/main/kotlin/com/wire/android/navigation) + +## Calling And Meetings + +### Purpose + +The repository contains both calling flows and meetings-related UI surfaces. + +### Key Components + +- calling activities in the app manifest +- `ui/calling` packages in the app module +- `features:meetings` +- call-related analytics and lifecycle observation in `WireApplication` + +### How It Connects + +Calling uses dedicated Android activities and app-level coordination, while meetings UI is split into a dedicated feature module. Lower-level calling logic is provided through shared dependencies rather than fully implemented in the UI layer. + +### Where To Look + +- [`../app/src/main/kotlin/com/wire/android/ui/calling`](../app/src/main/kotlin/com/wire/android/ui/calling) +- [`../features/meetings/src/main/java/com/wire/android/feature/meetings`](../features/meetings/src/main/java/com/wire/android/feature/meetings) +- [ADR 0002: Calling Activities Refactor](./adr/0002-calling-activities-refactor.md) + +## Cells And File Management + +### Purpose + +The repository contains a dedicated Cells feature area for file and storage-oriented interactions. + +### Key Components + +- `features:cells` +- Cells UI for create, rename, recycle bin, search, public links, versioning, tags, and downloads +- app packages such as `ui/home/cell` and `ui/home/vault` + +### How It Connects + +The feature module provides a distinct UI/domain surface, while backing logic and data capabilities rely on `kalium` and app-level DI wiring. + +### Where To Look + +- [`../features/cells/src/main/java/com/wire/android/feature/cells`](../features/cells/src/main/java/com/wire/android/feature/cells) +- [`../app/src/main/kotlin/com/wire/android/ui/home/cell`](../app/src/main/kotlin/com/wire/android/ui/home/cell) +- [`../app/src/main/kotlin/com/wire/android/ui/home/vault`](../app/src/main/kotlin/com/wire/android/ui/home/vault) + +## Sync, Background Processing, And Notifications + +### Purpose + +The app includes synchronization flows, background workers, and notification handling. + +### Key Components + +- `features:sync` +- app sync UI packages +- WorkManager workers +- notification packages and notification support modules +- lifecycle-driven observers in `WireApplication` + +### How It Connects + +This feature area mixes UI, background work, and platform services. The Android repo owns worker execution and notification presentation, while underlying state often comes from `kalium`. + +### Where To Look + +- [`../features/sync/src/main`](../features/sync/src/main) +- [`../app/src/main/kotlin/com/wire/android/ui/home/sync`](../app/src/main/kotlin/com/wire/android/ui/home/sync) +- [`../app/src/main/kotlin/com/wire/android/workmanager`](../app/src/main/kotlin/com/wire/android/workmanager) +- [`../core/notification`](../core/notification) + +## Security, Admin, And Compliance Surfaces + +### Purpose + +The app contains several security-oriented and enterprise-oriented capabilities. + +### Key Components + +- E2EI enrollment and certificate-related UI +- legal hold UI +- app lock flows +- biometric support +- EMM and managed configurations support +- screenshot-censoring and other security-related use cases exposed through DI + +### How It Connects + +Some of these capabilities are user-facing screens, while others are policy or compliance surfaces integrated into lifecycle, configuration, and session flows. + +### Where To Look + +- [`../app/src/main/kotlin/com/wire/android/ui/e2eiEnrollment`](../app/src/main/kotlin/com/wire/android/ui/e2eiEnrollment) +- [`../app/src/main/kotlin/com/wire/android/ui/legalhold`](../app/src/main/kotlin/com/wire/android/ui/legalhold) +- [`../app/src/main/kotlin/com/wire/android/ui/home/appLock`](../app/src/main/kotlin/com/wire/android/ui/home/appLock) +- [`../app/src/main/kotlin/com/wire/android/emm`](../app/src/main/kotlin/com/wire/android/emm) +- [ADR 0008: Introducing EMM Config Capabilities](./adr/0008-introducing-emm-config-capabilities.md) + +## Settings, Profile, And Device Management + +### Purpose + +The app includes account settings, device management, profile management, and related support screens. + +### Key Components + +- `ui/settings` +- `ui/userprofile` +- `ui/settings/devices` +- QR/profile-related packages +- self-device and profile destinations referenced in navigation + +### How It Connects + +These flows live primarily in the app module and consume injected session-aware use cases for account and device operations. + +### Where To Look + +- [`../app/src/main/kotlin/com/wire/android/ui/settings`](../app/src/main/kotlin/com/wire/android/ui/settings) +- [`../app/src/main/kotlin/com/wire/android/ui/userprofile`](../app/src/main/kotlin/com/wire/android/ui/userprofile) + +## Developer And Internal Tooling Features + +### Purpose + +The repository includes internal-only or debugging-oriented capabilities that are exposed selectively by flavor. + +### Key Components + +- debug screens +- feature-flag visibility controls +- logging configuration differences +- flavor-specific source sets for public/private and FOSS/non-free behavior + +### How It Connects + +These capabilities are part of the shipped architecture even when they are not enabled in every flavor. They are selected through build configuration and runtime flags rather than existing as a completely separate application. + +### Where To Look + +- [`../app/src/main/kotlin/com/wire/android/ui/debug`](../app/src/main/kotlin/com/wire/android/ui/debug) +- [`../app/src/main/kotlin/com/wire/android/util/debug`](../app/src/main/kotlin/com/wire/android/util/debug) +- [`../default.json`](../default.json) + +## Cross-Platform And Shared UI Experiments + +### Purpose + +The repository also contains limited cross-platform UI work beyond the main Android app. + +### Key Components + +- `core:ui-common-kmp` +- `wireone-kmp` + +### How It Connects + +These modules are not the main app path, but they show that parts of the UI stack are being shared across Android, iOS, and web-facing targets. + +### Where To Look + +- [`../core/ui-common-kmp`](../core/ui-common-kmp) +- [`../wireone-kmp`](../wireone-kmp) +- [`../wireone-kmp/README.md`](../wireone-kmp/README.md) diff --git a/docs/general-project-description.md b/docs/general-project-description.md new file mode 100644 index 00000000000..7b4c8dfbe1d --- /dev/null +++ b/docs/general-project-description.md @@ -0,0 +1,104 @@ +# General Project Description + +This document describes what the `wire-android` repository contains, how it is positioned within the Wire codebase, and which major technical and product concerns shape the project. + +For the module map, see [Project Structure](./project-structure.md). For runtime behavior, see [Architecture](./architecture.md). + +## Purpose + +`wire-android` is the Android client repository for Wire. It contains the Android application, Android support modules, test modules, benchmark code, and a small Kotlin Multiplatform surface used for shared UI experiments and companion targets. + +The repository is not a standalone monolith. It depends heavily on an included build named `kalium`, which provides much of the domain, data, and logic layer consumed by the Android app. + +## What The Repository Includes + +The root Gradle build currently includes these main projects: + +- `:app` +- `:benchmark` +- `:core:*` +- `:features:*` +- `:ksp` +- `:tests:*` +- `:wireone-kmp` + +The root build also includes two separate builds: + +- `build-logic` for convention plugins and shared Gradle setup +- `kalium` for shared Wire logic and supporting modules + +For a module-by-module breakdown, see [Project Structure](./project-structure.md). + +## Build Targets And Outputs + +The primary build target is the Android application in `app/`. + +The repository also contains: + +- Android libraries in `core/` and `features/` +- Android test infrastructure in `tests/` +- Macrobenchmark code in `benchmark/` +- a Kotlin Multiplatform module in `wireone-kmp/` that targets Android, iOS, and WebAssembly browser builds +- a small `ksp/` helper module for symbol-processing-related build support + +## App Flavors And Distribution Modes + +The app is built in multiple flavors defined by configuration in `default.json` and Gradle source-set setup in `app/build.gradle.kts`. + +Documented flavors include: + +- `dev` +- `staging` +- `internal` +- `beta` +- `prod` +- `fdroid` + +At a high level, the flavors separate development, QA, internal dogfooding, production, and F-Droid distribution use cases. They also change behavior such as logging, analytics, backend defaults, developer tooling, and inclusion of non-free integrations. + +The `fdroid` flavor is the FOSS-oriented production variant and excludes non-free pieces that are present in other flavors. + +## Major Technologies + +The repository is primarily built with: + +- Kotlin +- Gradle Kotlin DSL +- Android Gradle Plugin +- Jetpack Compose for UI +- Hilt for dependency injection +- WorkManager for background work +- Compose Destinations for typed navigation +- Kotlin Symbol Processing for generated code +- Kotlin Multiplatform in selected modules + +The Android app also consumes `kalium` artifacts or substituted modules for shared business logic, networking, persistence-facing APIs, and other core capabilities. + +## Relationship To The Wire Ecosystem + +This repository is one part of Wire's broader client and platform ecosystem. + +From the root README and build setup, the practical relationship is: + +- this repo owns the Android application shell and Android-facing UI/features +- `kalium` provides shared logic and lower-level capabilities used by the Android app +- some repository content, such as `wireone-kmp`, extends beyond Android-only concerns and supports iOS or web-facing experiments + +## Open-Source Constraints And Notes + +The repository is open source, but the root README explicitly calls out important limits: + +- some third-party service API keys are not included in the open-source project +- the open-source app differs from the Play Store binary in some integrated calling/audio-video signaling details +- trademark usage is restricted +- connecting custom-built apps to Wire servers is subject to Wire terms described in the root README + +These constraints matter when documenting build behavior, flavor behavior, and dependency choices. They also explain why certain integrations are flavor-specific or absent from open-source builds. + +## Where To Look + +- Root overview: [`../README.md`](../README.md) +- Flavor and backend configuration: [`../default.json`](../default.json) +- Root Gradle build: [`../build.gradle.kts`](../build.gradle.kts) +- Root settings and module inclusion: [`../settings.gradle.kts`](../settings.gradle.kts) +- Included builds: [`../include_builds.gradle.kts`](../include_builds.gradle.kts) diff --git a/docs/project-structure.md b/docs/project-structure.md new file mode 100644 index 00000000000..d57fb5700a9 --- /dev/null +++ b/docs/project-structure.md @@ -0,0 +1,216 @@ +# Project Structure + +This document maps the top-level layout of the repository and explains the responsibility of each included module family. + +For the repository purpose, see [General Project Description](./general-project-description.md). For runtime relationships between modules, see [Architecture](./architecture.md). + +## Purpose + +The repository is organized as a multi-module Gradle build centered on one Android application module plus supporting Android libraries, test modules, benchmark code, and included builds. + +The authoritative module list comes from `settings.gradle.kts` and `./gradlew -q projects`. + +## Top-Level Directory Map + +### `app/` + +Contains the Android application shell. This module defines the application entry points, manifest, flavor-aware source sets, top-level UI flows, navigation host setup, dependency injection bindings, services, notifications, and Android-specific integrations. + +### `core/` + +Contains reusable Android support libraries shared across the app and feature modules. + +Current included modules are: + +- `core:analytics` +- `core:analytics-disabled` +- `core:analytics-enabled` +- `core:di` +- `core:media` +- `core:navigation` +- `core:notification` +- `core:ui-common` +- `core:ui-common-kmp` + +### `features/` + +Contains feature-focused Android libraries that can be consumed by the app module. + +Current included modules are: + +- `features:cells` +- `features:meetings` +- `features:sketch` +- `features:sync` + +The repository also contains `features/template`, which is intentionally excluded from the root build and acts as scaffolding for future feature modules. + +### `tests/` + +Contains Android test infrastructure. + +Current included modules are: + +- `tests:testsCore` +- `tests:testsSupport` + +These modules support instrumentation, shared test utilities, UI automation helpers, custom runners, and secrets-loading support for test environments. + +### `benchmark/` + +Contains macrobenchmark-oriented code for measuring performance characteristics of the Android app. + +### `wireone-kmp/` + +Contains a Kotlin Multiplatform module with shared WireOne UI for Android, iOS, and browser-based Wasm targets. + +### `ksp/` + +Contains a small JVM/KSP helper module used for symbol-processing-related build support. + +### `build-logic/` + +Contains shared Gradle convention plugins and build configuration used by the root build through `includeBuild("build-logic")`. + +### `kalium/` + +Contains an included build that provides shared Wire logic and supporting lower-level modules. In this repository's architecture, `kalium` is primarily a boundary dependency rather than part of the Android UI layer. + +### `docs/` + +Contains project documentation and ADRs. + +### `scripts/` + +Contains repository scripts for APK wrapping, release notes, QA UI tests, and other development or CI support tasks. + +## Included Gradle Projects + +The root project currently includes these main Gradle projects: + +- `:app` +- `:benchmark` +- `:core` +- `:features` +- `:ksp` +- `:tests` +- `:wireone-kmp` + +Within those groupings, the included leaf modules are: + +- `:core:analytics` +- `:core:analytics-disabled` +- `:core:analytics-enabled` +- `:core:di` +- `:core:media` +- `:core:navigation` +- `:core:notification` +- `:core:ui-common` +- `:core:ui-common-kmp` +- `:features:cells` +- `:features:meetings` +- `:features:sketch` +- `:features:sync` +- `:tests:testsCore` +- `:tests:testsSupport` + +The root build also includes: + +- included build `:build-logic` +- included build `:kalium` + +## Responsibilities By Module Family + +### App Module + +### Purpose + +`app/` owns the Android application process and the composition root for runtime behavior. + +### Key Components + +- `WireApplication` +- `WireActivity` +- Android manifest declarations +- app-scoped and account-scoped Hilt modules +- top-level navigation host setup +- Android services, broadcast receivers, notifications, and WorkManager integration + +### How It Connects + +`app/` depends on `core/*`, `features/*`, and multiple `kalium` artifacts. It is the integration point where Android UI and platform concerns meet shared logic from `kalium`. + +### Core Modules + +### Purpose + +`core/*` provides shared Android libraries and reusable building blocks. + +### Key Components + +- `core:ui-common` for reusable UI infrastructure +- `core:navigation` for shared navigation abstractions and styles +- `core:notification` for notification-related support +- `core:media` and `core:di` for media and shared DI support +- analytics variants for enabling or disabling analytics implementation by flavor +- `core:ui-common-kmp` for limited shared UI code across Android and other targets + +### How It Connects + +Feature modules and the app module depend on these libraries to avoid duplicating common Android-specific code. + +### Feature Modules + +### Purpose + +`features/*` isolates larger feature areas into separate Android libraries. + +### Key Components + +- `features:cells` for Cells and file-management-related UI +- `features:meetings` for meetings-related UI +- `features:sketch` for drawing/sketch interactions +- `features:sync` for sync-related UI and background coordination surfaces + +### How It Connects + +These modules depend on `core/*` and `kalium` APIs, then plug into the app navigation graph and app runtime shell. + +### Test Modules + +### Purpose + +`tests/*` packages shared test support and Android instrumentation setup. + +### Key Components + +- custom test runner setup +- shared Android test dependencies +- UI automation support +- environment secret injection for test runs + +### How It Connects + +These modules support app and module-level verification rather than shipping runtime behavior. + +### Included Builds + +### `build-logic` + +Provides convention plugins and standardized Gradle behavior used across modules. + +### `kalium` + +Provides shared logic/data/domain capabilities and is substituted into the Android build through `include_builds.gradle.kts`. + +For more detail on the `kalium` boundary, see [Architecture](./architecture.md) and [Dependencies](./dependencies.md). + +## Where To Look + +- Root project inclusion logic: [`../settings.gradle.kts`](../settings.gradle.kts) +- Included build substitution: [`../include_builds.gradle.kts`](../include_builds.gradle.kts) +- App module: [`../app/`](../app/) +- Core modules: [`../core/`](../core/) +- Feature modules: [`../features/`](../features/) +- Test modules: [`../tests/`](../tests/) +- WireOne KMP module: [`../wireone-kmp/`](../wireone-kmp/) diff --git a/kalium b/kalium index 83f70d55a71..55fa7705e72 160000 --- a/kalium +++ b/kalium @@ -1 +1 @@ -Subproject commit 83f70d55a711418a993b8af63d58e438ba3281f3 +Subproject commit 55fa7705e721902d8eb92b88337bf01425090753 From 2f31d5ece9747b9861ef707d38620a41b70490fb Mon Sep 17 00:00:00 2001 From: Sergei Bakhtiarov Date: Wed, 1 Apr 2026 12:58:32 +0200 Subject: [PATCH 3/3] Revert "Add repository docs and update kalium submodule" This reverts commit 9db6734e93596415dcf390402764d12a41e81b81. --- .github/workflows/pr-review-service.yml | 157 ----------------- docs/README.md | 31 ---- docs/architecture.md | 223 ------------------------ docs/dependencies.md | 196 --------------------- docs/features.md | 222 ----------------------- docs/general-project-description.md | 104 ----------- docs/project-structure.md | 216 ----------------------- kalium | 2 +- 8 files changed, 1 insertion(+), 1150 deletions(-) delete mode 100644 .github/workflows/pr-review-service.yml delete mode 100644 docs/README.md delete mode 100644 docs/architecture.md delete mode 100644 docs/dependencies.md delete mode 100644 docs/features.md delete mode 100644 docs/general-project-description.md delete mode 100644 docs/project-structure.md diff --git a/.github/workflows/pr-review-service.yml b/.github/workflows/pr-review-service.yml deleted file mode 100644 index 9afa2c59ae1..00000000000 --- a/.github/workflows/pr-review-service.yml +++ /dev/null @@ -1,157 +0,0 @@ -name: "Automated PR Review" - -on: - pull_request: - types: [opened, synchronize, reopened] - -permissions: - contents: read - pull-requests: write - issues: write - -concurrency: - group: ${{ github.workflow }}-${{ github.event.pull_request.number }} - cancel-in-progress: true - -jobs: - pr-review: - if: github.event.pull_request.head.repo.full_name == github.repository - runs-on: ubuntu-latest - timeout-minutes: 5 - env: - GH_TOKEN: ${{ github.token }} - REVIEW_SERVICE_URL: http://91.99.71.160:8080/review-pr - COMMENT_MARKER: '' - PR_NUMBER: ${{ github.event.pull_request.number }} - PR_URL: ${{ github.event.pull_request.html_url }} - REPOSITORY: ${{ github.repository }} - steps: - - name: Generate automated review and update PR comment - shell: bash - run: | - set -u - - comment_id="$( - gh api "repos/${REPOSITORY}/issues/${PR_NUMBER}/comments" --paginate \ - --jq ".[] | select(.body | contains(\"${COMMENT_MARKER}\")) | .id" \ - | head -n 1 - )" - - summarize_failure() { - local message="$1" - - { - echo "### Automated PR Review" - echo "${message}" - } >> "$GITHUB_STEP_SUMMARY" - } - - publish_comment() { - local body_file="$1" - local request_json - - request_json=$(mktemp) - jq -Rs '{body: .}' < "${body_file}" > "${request_json}" - - if [ -n "${comment_id}" ]; then - gh api "repos/${REPOSITORY}/issues/comments/${comment_id}" \ - -X PATCH \ - --input "${request_json}" >/dev/null - else - gh api "repos/${REPOSITORY}/issues/${PR_NUMBER}/comments" \ - --input "${request_json}" >/dev/null - fi - } - - create_failure_comment_if_missing() { - if [ -n "${comment_id}" ]; then - return - fi - - local body - body=$(mktemp) - { - echo "${COMMENT_MARKER}" - echo "## Automated PR Review" - echo - echo "_Automated review could not be generated for this run._" - } > "${body}" - - publish_comment "${body}" - } - - payload=$(mktemp) - response=$(mktemp) - error_log=$(mktemp) - comment_body=$(mktemp) - - jq -n --arg pr_url "${PR_URL}" '{pr_url: $pr_url}' > "${payload}" - - http_code="$( - curl \ - --silent \ - --show-error \ - --output "${response}" \ - --write-out "%{http_code}" \ - --max-time 60 \ - -X POST "${REVIEW_SERVICE_URL}" \ - -H "Content-Type: application/json" \ - --data "@${payload}" \ - 2>"${error_log}" - )" - curl_exit_code=$? - - if [ "${curl_exit_code}" -ne 0 ]; then - error_message=$(cat "${error_log}") - summarize_failure "Review service request failed: ${error_message:-curl exited with code ${curl_exit_code}}" - create_failure_comment_if_missing - exit 0 - fi - - if [ "${http_code}" -lt 200 ] || [ "${http_code}" -ge 300 ]; then - summarize_failure "Review service returned HTTP ${http_code}." - create_failure_comment_if_missing - exit 0 - fi - - if ! jq -e . "${response}" >/dev/null 2>&1; then - summarize_failure "Review service returned invalid JSON." - create_failure_comment_if_missing - exit 0 - fi - - status=$(jq -r '.status // empty' "${response}") - if [ "${status}" != "ok" ]; then - summarize_failure "Review service returned status '${status:-missing}'." - create_failure_comment_if_missing - exit 0 - fi - - review_markdown=$(jq -r '.review_markdown // empty' "${response}") - if [ -z "${review_markdown}" ]; then - summarize_failure "Review service returned no review markdown." - create_failure_comment_if_missing - exit 0 - fi - - model=$(jq -r '.model // "unknown"' "${response}") - elapsed_ms=$(jq -r '.elapsed_ms // "unknown"' "${response}") - - { - echo "${COMMENT_MARKER}" - echo "## Automated PR Review" - echo - echo "_Generated by \`${model}\` in ${elapsed_ms} ms._" - echo - printf '%s\n' "${review_markdown}" - } > "${comment_body}" - - if ! publish_comment "${comment_body}"; then - summarize_failure "Review was generated, but publishing the PR comment failed." - exit 1 - fi - - { - echo "### Automated PR Review" - echo "Review comment posted successfully." - } >> "$GITHUB_STEP_SUMMARY" diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 0a197c4fbc6..00000000000 --- a/docs/README.md +++ /dev/null @@ -1,31 +0,0 @@ -# Wire Android Documentation - -This documentation set describes the `wire-android` repository for engineers who are onboarding to the codebase or preparing retrieval-friendly reference material. - -Each document is intentionally scoped, sectioned, and cross-linked so it can be indexed in a RAG pipeline without depending on one large README. - -## Documentation Map - -- [General Project Description](./general-project-description.md) -- [Project Structure](./project-structure.md) -- [Architecture](./architecture.md) -- [Dependencies](./dependencies.md) -- [Features](./features.md) - -## Existing Reference Material - -- [Architecture Decision Records](./adr/) -- Root-level project overview: [`README.md`](../README.md) -- Contribution guide: [`CONTRIBUTING.md`](../CONTRIBUTING.md) - -## How To Use This Documentation - -Use [General Project Description](./general-project-description.md) to understand what the repository contains and how it fits into Wire as a product and open-source project. - -Use [Project Structure](./project-structure.md) to locate modules, included builds, and top-level responsibilities. - -Use [Architecture](./architecture.md) to understand runtime flow, dependency injection, navigation, background processing, and the boundary with `kalium`. - -Use [Dependencies](./dependencies.md) to understand build tooling, first-party module relationships, included-build substitution, and major third-party libraries. - -Use [Features](./features.md) to map end-user capabilities and platform capabilities to app packages and feature modules. diff --git a/docs/architecture.md b/docs/architecture.md deleted file mode 100644 index 2534e0b8450..00000000000 --- a/docs/architecture.md +++ /dev/null @@ -1,223 +0,0 @@ -# Architecture - -This document describes the main runtime architecture of the Android app, the dependency direction between module families, and the boundary between this repository and the included `kalium` build. - -For the repository map, see [Project Structure](./project-structure.md). For dependency inventories, see [Dependencies](./dependencies.md). - -## Purpose - -The architecture of `wire-android` follows a layered integration model: - -- the Android application layer lives in `app/` -- reusable Android building blocks live in `core/*` -- feature-focused Android UI lives in `features/*` -- shared business logic and lower-level capabilities come from `kalium` - -This repo does not implement every layer directly. Much of the domain and data-facing behavior is delegated to `kalium`, while this repo focuses on Android runtime integration and user-facing UI. - -## Runtime Entry Flow - -### Application Startup - -The Android process starts in `WireApplication`, which is annotated with `@HiltAndroidApp`. - -At startup, `WireApplication` configures and coordinates: - -- Hilt-backed application dependency injection -- global logging setup -- StrictMode in debug builds -- WorkManager configuration through a custom `WireWorkerFactory` -- lifecycle observers and global observers -- sync-related background observation -- analytics observation -- call background-state observation -- asset-upload observation and worker enqueueing - -This makes `WireApplication` the application-level composition root for process-wide services. - -### Activity Shell - -The main user-facing shell is `WireActivity`. - -`WireActivity` is responsible for: - -- installing and holding the splash screen until first draw -- selecting the initial destination based on app state and login mode -- setting the Compose content tree -- handling new intents and deep links -- integrating dynamic receivers and managed configurations -- providing activity-scoped coordination for top-level UI, dialogs, and navigation events - -### Navigation Host - -`MainNavHost` hosts the top-level Compose Destinations graph. - -Its role includes: - -- creating the navigation engine -- mounting the root navigation graph -- sharing selected Hilt view models across nested navigation graphs -- wiring cross-module destination dependencies -- keeping selected manual composable calls where generated wiring is not sufficient yet - -This design allows feature modules to contribute destinations while the app module remains the top-level orchestration point. - -## Dependency Injection - -### Purpose - -Dependency injection is handled with Hilt and acts as the bridge between Android framework code and `kalium` use cases or services. - -### Key Components - -- app-scoped Hilt modules in `app/src/main/kotlin/com/wire/android/di` -- account-scoped Hilt modules in `app/src/main/kotlin/com/wire/android/di/accountScoped` -- `WireApplication` and Android entry points such as `WireActivity` - -### How It Connects - -The DI layer constructs: - -- application-level infrastructure such as logging, WorkManager, and configuration managers -- a shared `CoreLogic` instance from `kalium` -- session-aware and account-aware use cases derived from the current session -- feature-specific bindings consumed by view models and Android services - -This means the DI layer is a key architectural seam. Android code does not manually construct most business-layer objects; it receives them from Hilt, and Hilt in turn adapts them from `kalium`. - -## Module Layering - -### Purpose - -The repository uses module layering to keep Android concerns separated from reusable Android support code and feature-specific UI. - -### Key Components - -- `app/` integrates everything -- `core/*` provides reusable support code -- `features/*` provides isolated feature libraries -- `kalium` provides shared logic/data/domain capabilities - -### Dependency Direction - -At a high level, the dependency flow is: - -- `app` depends on `core/*`, `features/*`, and `kalium` -- `features/*` depend on selected `core/*` modules and `kalium` -- `core/*` may depend on `kalium` where shared logic or data APIs are needed -- `tests/*` depend on app-facing modules for verification support - -The intended architectural direction is inward toward shared logic. Android-specific code depends on reusable support layers and `kalium`, not the other way around. - -## Navigation Architecture - -### Purpose - -Navigation is Compose-based and type-aware. - -### Key Components - -- Jetpack Navigation Compose -- Compose Destinations -- `core:navigation` -- app-level nav graph declarations and host wiring - -### How It Connects - -Navigation definitions are spread across app and feature modules, but the top-level host remains in the app module. Shared transitions, destination styles, typed routes, and shared graph-scoped view models are coordinated centrally. - -This pattern allows modular feature navigation without fully decentralizing the runtime shell. - -## Background Work, Sync, And Notifications - -### Purpose - -The app performs background observation and worker-based coordination for sync and platform events. - -### Key Components - -- WorkManager integration in `WireApplication` -- custom worker factory -- workers such as `AssetUploadObserverWorker`, `NotificationFetchWorker`, `PersistentWebsocketCheckWorker`, and `DeleteConversationLocallyWorker` -- notification support in `core:notification` and app notification packages -- sync-related surfaces in `features:sync` and app sync UI packages - -### How It Connects - -The app observes state from `kalium` and other Android services, then schedules or executes Android-native work through WorkManager and notification channels. This keeps platform execution details in the Android repo while allowing shared logic to remain in `kalium`. - -## Analytics And Flavor-Dependent Behavior - -### Purpose - -Analytics and some integrations are flavor-dependent rather than uniform across all builds. - -### Key Components - -- `core:analytics` -- `core:analytics-enabled` -- `core:analytics-disabled` -- flavor configuration from `default.json` -- conditional plugin and dependency setup in Gradle - -### How It Connects - -The app module chooses analytics-enabled or analytics-disabled implementations per flavor. Similar flavor-aware behavior also affects Google services, developer tooling, logging, and the F-Droid build path. - -This is an architectural concern because some runtime behavior is selected at build time rather than only at runtime. - -## The `kalium` Boundary - -### Purpose - -`kalium` is an included build that provides shared logic and lower-level capabilities used by the Android app. - -### Key Components - -The Android build substitutes selected `com.wire.kalium:*` dependencies with local projects from the included `kalium` build, including: - -- `kalium-logic` -- `kalium-util` -- `kalium-data` -- `kalium-common` -- `kalium-cells` -- selected test-facing modules - -### How It Connects - -From the Android repo perspective, `kalium` supplies capabilities such as: - -- `CoreLogic` -- session and account handling -- messaging and calling use cases -- data and persistence-facing APIs -- network-facing abstractions -- shared domain logic for Cells and other features - -The Android app does not duplicate those layers. Instead, it adapts them into Android entry points, Hilt bindings, Compose screens, notification flows, and WorkManager jobs. - -This makes `kalium` an architectural boundary, not just a library dependency. - -## ADRs Related To Architecture - -The existing ADR set in `docs/adr/` records several architecture-affecting decisions, including: - -- deep link handling refactors -- calling activity refactors -- conversation list composable refactors -- enterprise login flow support -- UI Automator adoption -- EMM config capabilities -- tablet dialog navigation parity after Compose Destinations upgrade - -These ADRs are useful when the current architecture looks unusual or carries historical constraints. - -## Where To Look - -- Application entry point: [`../app/src/main/kotlin/com/wire/android/WireApplication.kt`](../app/src/main/kotlin/com/wire/android/WireApplication.kt) -- Main activity shell: [`../app/src/main/kotlin/com/wire/android/ui/WireActivity.kt`](../app/src/main/kotlin/com/wire/android/ui/WireActivity.kt) -- Main navigation host: [`../app/src/main/kotlin/com/wire/android/navigation/MainNavHost.kt`](../app/src/main/kotlin/com/wire/android/navigation/MainNavHost.kt) -- Manifest entry points: [`../app/src/main/AndroidManifest.xml`](../app/src/main/AndroidManifest.xml) -- Hilt modules: [`../app/src/main/kotlin/com/wire/android/di/`](../app/src/main/kotlin/com/wire/android/di/) -- Included build substitution: [`../include_builds.gradle.kts`](../include_builds.gradle.kts) -- ADRs: [`./adr/`](./adr/) diff --git a/docs/dependencies.md b/docs/dependencies.md deleted file mode 100644 index dc056a0d6df..00000000000 --- a/docs/dependencies.md +++ /dev/null @@ -1,196 +0,0 @@ -# Dependencies - -This document describes the build stack, first-party module relationships, included-build substitution, and major third-party libraries used in the repository. - -For the module map, see [Project Structure](./project-structure.md). For runtime integration details, see [Architecture](./architecture.md). - -## Purpose - -`wire-android` uses a mixed dependency model: - -- local Gradle modules inside this repository -- included builds for shared build logic and shared Wire logic -- external Android, Kotlin, and tooling libraries -- flavor-dependent dependencies that change by distribution target - -## Build System And Plugin Stack - -### Purpose - -The project uses Gradle Kotlin DSL with central version management and convention plugins. - -### Key Components - -- root `build.gradle.kts` -- root `settings.gradle.kts` -- `gradle/libs.versions.toml` -- included build `build-logic` -- standard Android, Kotlin, KSP, Compose, and CycloneDX plugins - -### How It Connects - -The root build declares shared plugins and repositories, while `build-logic` supplies repository-specific convention plugins such as: - -- `com.wire.android.application` -- `com.wire.android.library` -- `com.wire.android.test.library` -- `com.wire.android.navigation` -- `com.wire.android.kmp.library` -- `com.wire.android.hilt` -- `com.wire.android.kover` -- `com.wire.android.versionizer` - -This keeps individual module build files relatively small and consistent. - -## First-Party Module Dependencies - -### App Module Dependencies - -`app/` depends directly on: - -- `core:ui-common` -- `core:di` -- `core:media` -- `core:notification` -- `features:cells` -- `features:sketch` -- `features:meetings` -- `features:sync` -- `core:analytics-enabled` or `core:analytics-disabled`, selected by flavor -- `com.wire.kalium:*` dependencies such as `kalium-logic`, `kalium-util`, and `kalium-cells` - -### Core Module Patterns - -Core modules provide reusable support libraries. Examples: - -- `core:navigation` depends on `core:ui-common` plus navigation libraries -- `core:notification` depends on `core:media` and selected `kalium` modules -- `core:ui-common` depends on `kalium-logic` and shared Compose/Hilt infrastructure - -### Feature Module Patterns - -Feature modules depend on shared UI and selected `kalium` APIs. Examples: - -- `features:cells` depends on `core:ui-common`, `kalium-common`, `kalium-logic`, and `kalium-cells` -- `features:meetings` depends on `core:ui-common` and `kalium` -- `features:sync` depends on `core:notification`, `core:ui-common`, `core:di`, and `kalium` -- `features:sketch` primarily depends on `core:ui-common` and Compose/UI support - -## Included Builds And Substitution - -### Purpose - -The repository uses included builds to keep local development aligned across shared codebases. - -### Key Components - -- `includeBuild("build-logic")` -- `includeBuild("kalium")` -- dependency substitution in `include_builds.gradle.kts` - -### How It Connects - -When the Android app depends on selected `com.wire.kalium:*` coordinates, the build substitutes them with local `kalium` projects during the included-build workflow. - -This means local development can consume `kalium` source directly instead of only relying on published artifacts. The substitution currently covers modules such as: - -- `com.wire.kalium:kalium-logic` -- `com.wire.kalium:kalium-util` -- `com.wire.kalium:kalium-data` -- `com.wire.kalium:kalium-common` -- `com.wire.kalium:kalium-cells` -- test-facing modules like `kalium-mocks` and `kalium-network` - -From a documentation perspective, this is one of the most important dependency facts in the repo. - -## Major Third-Party Libraries - -### Android And Platform - -- AndroidX core libraries -- AppCompat -- DataStore -- SplashScreen -- Browser -- Biometric -- Startup -- WorkManager - -### UI And Navigation - -- Jetpack Compose BOM and Compose UI libraries -- Material and Material3 -- Navigation Compose -- Compose Destinations -- Accompanist placeholder support -- Coil for image loading - -### Dependency Injection And Code Generation - -- Hilt -- KSP -- JavaPoet - -### Kotlin And Concurrency - -- Kotlinx Coroutines -- Kotlinx Serialization -- Kotlinx Datetime -- Kotlinx Immutable Collections - -### Logging, Analytics, And Reporting - -- DataDog SDK integration paths -- Countly in analytics-enabled builds -- AboutLibraries for license/about screens -- CycloneDX for SBOM generation - -### Testing And Quality - -- JUnit 4 and JUnit 5 -- MockK -- Turbine -- Robolectric -- Espresso -- AndroidX test libraries -- UI Automator -- Allure Kotlin -- Kover -- Detekt - -## Flavor-Specific And Optional Dependencies - -### Google Services - -The root build conditionally includes the Google services Gradle plugin depending on whether the build is targeting F-Droid. - -### Analytics - -The app selects either analytics-enabled or analytics-disabled implementations by flavor using values loaded from `default.json`. - -### FOSS Versus Non-Free Source Sets - -The app module configures flavor-specific source-set additions for: - -- internal versus public logging paths -- FOSS versus non-free code -- F-Droid-specific behavior and resources - -This affects not only runtime features but also which dependencies and source directories participate in the build. - -## Dependency Management Conventions - -Centralized versions live in `gradle/libs.versions.toml`. - -Most module build files use the shared version catalog and convention plugins rather than declaring fully custom dependency-management logic. - -The build also generates a CycloneDX software bill of materials from the root build. - -## Where To Look - -- Root build: [`../build.gradle.kts`](../build.gradle.kts) -- Root settings: [`../settings.gradle.kts`](../settings.gradle.kts) -- Version catalog: [`../gradle/libs.versions.toml`](../gradle/libs.versions.toml) -- Included-build substitution: [`../include_builds.gradle.kts`](../include_builds.gradle.kts) -- App module dependencies: [`../app/build.gradle.kts`](../app/build.gradle.kts) -- Kalium overview: [`../kalium/README.md`](../kalium/README.md) diff --git a/docs/features.md b/docs/features.md deleted file mode 100644 index 887e02afbb1..00000000000 --- a/docs/features.md +++ /dev/null @@ -1,222 +0,0 @@ -# Features - -This document groups the repository's visible capabilities into feature areas and notes where each capability is implemented in the Android repo. - -The descriptions in this document are derived from module names, package structure, manifests, flavor configuration, and app/runtime wiring. For architectural context, see [Architecture](./architecture.md). - -## Purpose - -The repository combines end-user features, platform integration features, and internal tooling features. Not every capability is isolated into its own Gradle module; many live directly in the app module and are supported by `core/*`, `features/*`, and `kalium`. - -## Authentication And Account Access - -### Purpose - -The app supports sign-in, account entry flows, and related account-state transitions. - -### Key Components - -- app packages under `ui/authentication`, `ui/newauthentication`, and `ui/registration` -- login support packages under `feature/login` -- deep-link and SSO-related manifest entries -- session and account use cases provided through Hilt from `kalium` - -### How It Connects - -Authentication UI lives primarily in the app module, while account/session logic is adapted from `kalium`. - -### Where To Look - -- [`../app/src/main/kotlin/com/wire/android/ui/authentication`](../app/src/main/kotlin/com/wire/android/ui/authentication) -- [`../app/src/main/kotlin/com/wire/android/ui/newauthentication`](../app/src/main/kotlin/com/wire/android/ui/newauthentication) -- [`../app/src/main/kotlin/com/wire/android/ui/registration`](../app/src/main/kotlin/com/wire/android/ui/registration) -- [`../app/src/main/kotlin/com/wire/android/feature/login`](../app/src/main/kotlin/com/wire/android/feature/login) - -## Conversations, Messaging, And Home UI - -### Purpose - -The app includes conversation-centric flows for browsing conversations, opening message threads, composing messages, sharing content, and navigating the main logged-in experience. - -### Key Components - -- `ui/home/conversations` -- `ui/home/conversationslist` -- `ui/home/messagecomposer` -- `ui/sharing` -- `ui/joinConversation` -- `ui/home/newconversation` - -### How It Connects - -The app module owns much of the conversation UI shell, while message and conversation logic comes from `kalium` via injected use cases and session scope access. - -### Where To Look - -- [`../app/src/main/kotlin/com/wire/android/ui/home`](../app/src/main/kotlin/com/wire/android/ui/home) -- [`../app/src/main/kotlin/com/wire/android/ui/sharing`](../app/src/main/kotlin/com/wire/android/ui/sharing) -- [`../app/src/main/kotlin/com/wire/android/navigation`](../app/src/main/kotlin/com/wire/android/navigation) - -## Calling And Meetings - -### Purpose - -The repository contains both calling flows and meetings-related UI surfaces. - -### Key Components - -- calling activities in the app manifest -- `ui/calling` packages in the app module -- `features:meetings` -- call-related analytics and lifecycle observation in `WireApplication` - -### How It Connects - -Calling uses dedicated Android activities and app-level coordination, while meetings UI is split into a dedicated feature module. Lower-level calling logic is provided through shared dependencies rather than fully implemented in the UI layer. - -### Where To Look - -- [`../app/src/main/kotlin/com/wire/android/ui/calling`](../app/src/main/kotlin/com/wire/android/ui/calling) -- [`../features/meetings/src/main/java/com/wire/android/feature/meetings`](../features/meetings/src/main/java/com/wire/android/feature/meetings) -- [ADR 0002: Calling Activities Refactor](./adr/0002-calling-activities-refactor.md) - -## Cells And File Management - -### Purpose - -The repository contains a dedicated Cells feature area for file and storage-oriented interactions. - -### Key Components - -- `features:cells` -- Cells UI for create, rename, recycle bin, search, public links, versioning, tags, and downloads -- app packages such as `ui/home/cell` and `ui/home/vault` - -### How It Connects - -The feature module provides a distinct UI/domain surface, while backing logic and data capabilities rely on `kalium` and app-level DI wiring. - -### Where To Look - -- [`../features/cells/src/main/java/com/wire/android/feature/cells`](../features/cells/src/main/java/com/wire/android/feature/cells) -- [`../app/src/main/kotlin/com/wire/android/ui/home/cell`](../app/src/main/kotlin/com/wire/android/ui/home/cell) -- [`../app/src/main/kotlin/com/wire/android/ui/home/vault`](../app/src/main/kotlin/com/wire/android/ui/home/vault) - -## Sync, Background Processing, And Notifications - -### Purpose - -The app includes synchronization flows, background workers, and notification handling. - -### Key Components - -- `features:sync` -- app sync UI packages -- WorkManager workers -- notification packages and notification support modules -- lifecycle-driven observers in `WireApplication` - -### How It Connects - -This feature area mixes UI, background work, and platform services. The Android repo owns worker execution and notification presentation, while underlying state often comes from `kalium`. - -### Where To Look - -- [`../features/sync/src/main`](../features/sync/src/main) -- [`../app/src/main/kotlin/com/wire/android/ui/home/sync`](../app/src/main/kotlin/com/wire/android/ui/home/sync) -- [`../app/src/main/kotlin/com/wire/android/workmanager`](../app/src/main/kotlin/com/wire/android/workmanager) -- [`../core/notification`](../core/notification) - -## Security, Admin, And Compliance Surfaces - -### Purpose - -The app contains several security-oriented and enterprise-oriented capabilities. - -### Key Components - -- E2EI enrollment and certificate-related UI -- legal hold UI -- app lock flows -- biometric support -- EMM and managed configurations support -- screenshot-censoring and other security-related use cases exposed through DI - -### How It Connects - -Some of these capabilities are user-facing screens, while others are policy or compliance surfaces integrated into lifecycle, configuration, and session flows. - -### Where To Look - -- [`../app/src/main/kotlin/com/wire/android/ui/e2eiEnrollment`](../app/src/main/kotlin/com/wire/android/ui/e2eiEnrollment) -- [`../app/src/main/kotlin/com/wire/android/ui/legalhold`](../app/src/main/kotlin/com/wire/android/ui/legalhold) -- [`../app/src/main/kotlin/com/wire/android/ui/home/appLock`](../app/src/main/kotlin/com/wire/android/ui/home/appLock) -- [`../app/src/main/kotlin/com/wire/android/emm`](../app/src/main/kotlin/com/wire/android/emm) -- [ADR 0008: Introducing EMM Config Capabilities](./adr/0008-introducing-emm-config-capabilities.md) - -## Settings, Profile, And Device Management - -### Purpose - -The app includes account settings, device management, profile management, and related support screens. - -### Key Components - -- `ui/settings` -- `ui/userprofile` -- `ui/settings/devices` -- QR/profile-related packages -- self-device and profile destinations referenced in navigation - -### How It Connects - -These flows live primarily in the app module and consume injected session-aware use cases for account and device operations. - -### Where To Look - -- [`../app/src/main/kotlin/com/wire/android/ui/settings`](../app/src/main/kotlin/com/wire/android/ui/settings) -- [`../app/src/main/kotlin/com/wire/android/ui/userprofile`](../app/src/main/kotlin/com/wire/android/ui/userprofile) - -## Developer And Internal Tooling Features - -### Purpose - -The repository includes internal-only or debugging-oriented capabilities that are exposed selectively by flavor. - -### Key Components - -- debug screens -- feature-flag visibility controls -- logging configuration differences -- flavor-specific source sets for public/private and FOSS/non-free behavior - -### How It Connects - -These capabilities are part of the shipped architecture even when they are not enabled in every flavor. They are selected through build configuration and runtime flags rather than existing as a completely separate application. - -### Where To Look - -- [`../app/src/main/kotlin/com/wire/android/ui/debug`](../app/src/main/kotlin/com/wire/android/ui/debug) -- [`../app/src/main/kotlin/com/wire/android/util/debug`](../app/src/main/kotlin/com/wire/android/util/debug) -- [`../default.json`](../default.json) - -## Cross-Platform And Shared UI Experiments - -### Purpose - -The repository also contains limited cross-platform UI work beyond the main Android app. - -### Key Components - -- `core:ui-common-kmp` -- `wireone-kmp` - -### How It Connects - -These modules are not the main app path, but they show that parts of the UI stack are being shared across Android, iOS, and web-facing targets. - -### Where To Look - -- [`../core/ui-common-kmp`](../core/ui-common-kmp) -- [`../wireone-kmp`](../wireone-kmp) -- [`../wireone-kmp/README.md`](../wireone-kmp/README.md) diff --git a/docs/general-project-description.md b/docs/general-project-description.md deleted file mode 100644 index 7b4c8dfbe1d..00000000000 --- a/docs/general-project-description.md +++ /dev/null @@ -1,104 +0,0 @@ -# General Project Description - -This document describes what the `wire-android` repository contains, how it is positioned within the Wire codebase, and which major technical and product concerns shape the project. - -For the module map, see [Project Structure](./project-structure.md). For runtime behavior, see [Architecture](./architecture.md). - -## Purpose - -`wire-android` is the Android client repository for Wire. It contains the Android application, Android support modules, test modules, benchmark code, and a small Kotlin Multiplatform surface used for shared UI experiments and companion targets. - -The repository is not a standalone monolith. It depends heavily on an included build named `kalium`, which provides much of the domain, data, and logic layer consumed by the Android app. - -## What The Repository Includes - -The root Gradle build currently includes these main projects: - -- `:app` -- `:benchmark` -- `:core:*` -- `:features:*` -- `:ksp` -- `:tests:*` -- `:wireone-kmp` - -The root build also includes two separate builds: - -- `build-logic` for convention plugins and shared Gradle setup -- `kalium` for shared Wire logic and supporting modules - -For a module-by-module breakdown, see [Project Structure](./project-structure.md). - -## Build Targets And Outputs - -The primary build target is the Android application in `app/`. - -The repository also contains: - -- Android libraries in `core/` and `features/` -- Android test infrastructure in `tests/` -- Macrobenchmark code in `benchmark/` -- a Kotlin Multiplatform module in `wireone-kmp/` that targets Android, iOS, and WebAssembly browser builds -- a small `ksp/` helper module for symbol-processing-related build support - -## App Flavors And Distribution Modes - -The app is built in multiple flavors defined by configuration in `default.json` and Gradle source-set setup in `app/build.gradle.kts`. - -Documented flavors include: - -- `dev` -- `staging` -- `internal` -- `beta` -- `prod` -- `fdroid` - -At a high level, the flavors separate development, QA, internal dogfooding, production, and F-Droid distribution use cases. They also change behavior such as logging, analytics, backend defaults, developer tooling, and inclusion of non-free integrations. - -The `fdroid` flavor is the FOSS-oriented production variant and excludes non-free pieces that are present in other flavors. - -## Major Technologies - -The repository is primarily built with: - -- Kotlin -- Gradle Kotlin DSL -- Android Gradle Plugin -- Jetpack Compose for UI -- Hilt for dependency injection -- WorkManager for background work -- Compose Destinations for typed navigation -- Kotlin Symbol Processing for generated code -- Kotlin Multiplatform in selected modules - -The Android app also consumes `kalium` artifacts or substituted modules for shared business logic, networking, persistence-facing APIs, and other core capabilities. - -## Relationship To The Wire Ecosystem - -This repository is one part of Wire's broader client and platform ecosystem. - -From the root README and build setup, the practical relationship is: - -- this repo owns the Android application shell and Android-facing UI/features -- `kalium` provides shared logic and lower-level capabilities used by the Android app -- some repository content, such as `wireone-kmp`, extends beyond Android-only concerns and supports iOS or web-facing experiments - -## Open-Source Constraints And Notes - -The repository is open source, but the root README explicitly calls out important limits: - -- some third-party service API keys are not included in the open-source project -- the open-source app differs from the Play Store binary in some integrated calling/audio-video signaling details -- trademark usage is restricted -- connecting custom-built apps to Wire servers is subject to Wire terms described in the root README - -These constraints matter when documenting build behavior, flavor behavior, and dependency choices. They also explain why certain integrations are flavor-specific or absent from open-source builds. - -## Where To Look - -- Root overview: [`../README.md`](../README.md) -- Flavor and backend configuration: [`../default.json`](../default.json) -- Root Gradle build: [`../build.gradle.kts`](../build.gradle.kts) -- Root settings and module inclusion: [`../settings.gradle.kts`](../settings.gradle.kts) -- Included builds: [`../include_builds.gradle.kts`](../include_builds.gradle.kts) diff --git a/docs/project-structure.md b/docs/project-structure.md deleted file mode 100644 index d57fb5700a9..00000000000 --- a/docs/project-structure.md +++ /dev/null @@ -1,216 +0,0 @@ -# Project Structure - -This document maps the top-level layout of the repository and explains the responsibility of each included module family. - -For the repository purpose, see [General Project Description](./general-project-description.md). For runtime relationships between modules, see [Architecture](./architecture.md). - -## Purpose - -The repository is organized as a multi-module Gradle build centered on one Android application module plus supporting Android libraries, test modules, benchmark code, and included builds. - -The authoritative module list comes from `settings.gradle.kts` and `./gradlew -q projects`. - -## Top-Level Directory Map - -### `app/` - -Contains the Android application shell. This module defines the application entry points, manifest, flavor-aware source sets, top-level UI flows, navigation host setup, dependency injection bindings, services, notifications, and Android-specific integrations. - -### `core/` - -Contains reusable Android support libraries shared across the app and feature modules. - -Current included modules are: - -- `core:analytics` -- `core:analytics-disabled` -- `core:analytics-enabled` -- `core:di` -- `core:media` -- `core:navigation` -- `core:notification` -- `core:ui-common` -- `core:ui-common-kmp` - -### `features/` - -Contains feature-focused Android libraries that can be consumed by the app module. - -Current included modules are: - -- `features:cells` -- `features:meetings` -- `features:sketch` -- `features:sync` - -The repository also contains `features/template`, which is intentionally excluded from the root build and acts as scaffolding for future feature modules. - -### `tests/` - -Contains Android test infrastructure. - -Current included modules are: - -- `tests:testsCore` -- `tests:testsSupport` - -These modules support instrumentation, shared test utilities, UI automation helpers, custom runners, and secrets-loading support for test environments. - -### `benchmark/` - -Contains macrobenchmark-oriented code for measuring performance characteristics of the Android app. - -### `wireone-kmp/` - -Contains a Kotlin Multiplatform module with shared WireOne UI for Android, iOS, and browser-based Wasm targets. - -### `ksp/` - -Contains a small JVM/KSP helper module used for symbol-processing-related build support. - -### `build-logic/` - -Contains shared Gradle convention plugins and build configuration used by the root build through `includeBuild("build-logic")`. - -### `kalium/` - -Contains an included build that provides shared Wire logic and supporting lower-level modules. In this repository's architecture, `kalium` is primarily a boundary dependency rather than part of the Android UI layer. - -### `docs/` - -Contains project documentation and ADRs. - -### `scripts/` - -Contains repository scripts for APK wrapping, release notes, QA UI tests, and other development or CI support tasks. - -## Included Gradle Projects - -The root project currently includes these main Gradle projects: - -- `:app` -- `:benchmark` -- `:core` -- `:features` -- `:ksp` -- `:tests` -- `:wireone-kmp` - -Within those groupings, the included leaf modules are: - -- `:core:analytics` -- `:core:analytics-disabled` -- `:core:analytics-enabled` -- `:core:di` -- `:core:media` -- `:core:navigation` -- `:core:notification` -- `:core:ui-common` -- `:core:ui-common-kmp` -- `:features:cells` -- `:features:meetings` -- `:features:sketch` -- `:features:sync` -- `:tests:testsCore` -- `:tests:testsSupport` - -The root build also includes: - -- included build `:build-logic` -- included build `:kalium` - -## Responsibilities By Module Family - -### App Module - -### Purpose - -`app/` owns the Android application process and the composition root for runtime behavior. - -### Key Components - -- `WireApplication` -- `WireActivity` -- Android manifest declarations -- app-scoped and account-scoped Hilt modules -- top-level navigation host setup -- Android services, broadcast receivers, notifications, and WorkManager integration - -### How It Connects - -`app/` depends on `core/*`, `features/*`, and multiple `kalium` artifacts. It is the integration point where Android UI and platform concerns meet shared logic from `kalium`. - -### Core Modules - -### Purpose - -`core/*` provides shared Android libraries and reusable building blocks. - -### Key Components - -- `core:ui-common` for reusable UI infrastructure -- `core:navigation` for shared navigation abstractions and styles -- `core:notification` for notification-related support -- `core:media` and `core:di` for media and shared DI support -- analytics variants for enabling or disabling analytics implementation by flavor -- `core:ui-common-kmp` for limited shared UI code across Android and other targets - -### How It Connects - -Feature modules and the app module depend on these libraries to avoid duplicating common Android-specific code. - -### Feature Modules - -### Purpose - -`features/*` isolates larger feature areas into separate Android libraries. - -### Key Components - -- `features:cells` for Cells and file-management-related UI -- `features:meetings` for meetings-related UI -- `features:sketch` for drawing/sketch interactions -- `features:sync` for sync-related UI and background coordination surfaces - -### How It Connects - -These modules depend on `core/*` and `kalium` APIs, then plug into the app navigation graph and app runtime shell. - -### Test Modules - -### Purpose - -`tests/*` packages shared test support and Android instrumentation setup. - -### Key Components - -- custom test runner setup -- shared Android test dependencies -- UI automation support -- environment secret injection for test runs - -### How It Connects - -These modules support app and module-level verification rather than shipping runtime behavior. - -### Included Builds - -### `build-logic` - -Provides convention plugins and standardized Gradle behavior used across modules. - -### `kalium` - -Provides shared logic/data/domain capabilities and is substituted into the Android build through `include_builds.gradle.kts`. - -For more detail on the `kalium` boundary, see [Architecture](./architecture.md) and [Dependencies](./dependencies.md). - -## Where To Look - -- Root project inclusion logic: [`../settings.gradle.kts`](../settings.gradle.kts) -- Included build substitution: [`../include_builds.gradle.kts`](../include_builds.gradle.kts) -- App module: [`../app/`](../app/) -- Core modules: [`../core/`](../core/) -- Feature modules: [`../features/`](../features/) -- Test modules: [`../tests/`](../tests/) -- WireOne KMP module: [`../wireone-kmp/`](../wireone-kmp/) diff --git a/kalium b/kalium index 55fa7705e72..83f70d55a71 160000 --- a/kalium +++ b/kalium @@ -1 +1 @@ -Subproject commit 55fa7705e721902d8eb92b88337bf01425090753 +Subproject commit 83f70d55a711418a993b8af63d58e438ba3281f3