# ADR-MOB-001 — Mobile is a first-class port, Android first, in this repository **Status:** Accepted (2026-08-07) · design only, no code yet **Deciders:** Mohsen Seyedkazemi Ardebili **Context links:** [[adr-011]] (zero telemetry, offline-default), [[adr-mob-002]] (native stack), [[adr-mob-008]] (cross-platform contract), [[adr-mob-010]] (Apple second wave), program docs: `docs/mobile/` --- ## Context YazSes is a desktop daemon (Linux/macOS/Windows). Both the README and `docs/roadmap.md` state plainly: *"Desktop-only. There is no mobile or web version."* That is the single most-requested missing platform, and it is also where the project's thesis — **dictation that never leaves the device** — has its sharpest competitive edge: on a phone, the default dictation path is Google's or Apple's cloud/on-device service that the user cannot audit, and the confidential-meeting / regulated-profession users YazSes targets (lawyers, clinicians, journalists) carry a phone into exactly the rooms where a desktop never goes. Three structural facts shape the decision: 1. **Android can reproduce the desktop interaction model faithfully; iOS cannot.** Android's `InputMethodService` lets a third-party keyboard hold the microphone and commit text into *any* app via `InputConnection`, with no root and no accessibility grant. On iOS, **no app extension — including a custom keyboard — may access the microphone**; this has been a hard Apple restriction since iOS 8, which is why every iOS competitor (Wispr Flow, Spokenly, Willow) routes through an app switch. So "Android first" is a technical ordering, not a preference. (See [[adr-mob-010]].) 2. **macOS is already shipped.** The user-facing ask "…and Mac" is satisfied today by the desktop app; the Apple work that remains is *iOS/iPadOS*, and it is a different product shape, not a port of this one. 3. **None of the desktop runtime is reusable.** faster-whisper depends on CTranslate2, which has no Android build; the daemon model (long-lived process + Unix socket) fights Android's lifecycle; a Python-on-Android runtime cannot implement an IME. The port shares *behaviour*, not code — which is precisely why the behaviour must be written down as a testable contract before anyone writes Kotlin ([[adr-mob-008]]). The community question is equally structural. A mobile port is a 6–12 month effort that the maintainer cannot execute alone alongside the desktop line. It only happens if it is **contributor-shaped from day one**: parallelisable modules, a machine-checkable definition of "correct", and tasks that a new contributor can finish in a weekend. ## Decision 1. **Mobile is a first-class, ADR-governed port**, not an experiment. It is governed by the `adr-mob-*` series, and it inherits every v1/v2 invariant unchanged — most importantly [[adr-011]] (zero telemetry, offline by default, no cloud fallback) and the project rule that **new features ship off by default**. 2. **Android is wave 1. Apple (iOS/iPadOS) is wave 2**, and wave 2 starts only after Android reaches M2 (see `docs/mobile/index.md` for the milestone ladder), so the shared contract has been proven by a second implementation before a third begins. 3. **The Android app lives in this repository**, under a top-level `android/` directory with its own Gradle build and its own CI workflow — *not* in a separate `yazses-android` repo. 4. **The desktop Python tree and the Android tree are peers**, both conforming to a language-neutral contract in a new top-level `contract/` directory ([[adr-mob-008]]). Neither imports the other; neither is "the reference implementation" informally — the contract is the reference. 5. **Scope of wave 1 is dictation, not the whole desktop feature set.** The Android app ships when hold-to-talk dictation into any app is reliable; file transcription and Meeting Mode are M3+; the v2 cognitive layer (gaze, EMG, LSP context, remote injection) is explicitly out of scope for wave 1. ## Consequences **Monorepo, positive:** - One community, one star count, one issue tracker, one CONTRIBUTING — critical for a project whose current bottleneck is contributor supply, not code. - The contract and its golden vectors sit beside *both* implementations, so a CI job can fail a desktop PR that silently changes behaviour the Android port depends on. In two repos that guarantee degrades to a version-pinned copy that drifts. - Cross-platform issues ("disfluency filter drops a word") are one issue, not two. - F-Droid and Play both build fine from a subdirectory of a larger repo. **Monorepo, negative / mitigations:** - Python contributors see Kotlin they don't care about, and vice versa → mitigated by path-filtered CI (`android/**` triggers the Gradle workflow only), separate module stewards, and a `mobile` label on every mobile issue. - A `git clone` gets bigger → the Android tree carries no model weights and no prebuilt binaries ([[adr-mob-006]]), so the growth is source only. - Release tagging must not imply that a `v2.x` desktop tag ships an APK → Android uses its own tag prefix `android-v*` with its own workflow ([[adr-mob-009]]). **Programme-level:** - Wave 1 will not have feature parity with the desktop, and saying so plainly is a requirement, not a caveat: the README's honesty rules apply to the Android page too (nothing is listed as working until it is wired and tested). - The maintainer's role on mobile is architecture, review and contract ownership; module implementation is delegated to the Mobile Working Group (`docs/mobile/contributing.md`). ## Rejected - **A separate `MSKazemi/yazses-android` repository.** Splits an already-small community across two trackers, duplicates CONTRIBUTING/CI/labels, and makes the contract a cross-repo dependency that will drift. Revisit only if the Android tree grows its own distinct maintainer team. - **Waiting for the desktop v2 line to stabilise first.** The v2 line is a permanent research frontier; "later" means never. The contract work ([[adr-mob-008]]) also pays the desktop back immediately by pinning post-processing behaviour that is currently only implicitly specified by its tests. - **iOS first, or both at once.** The microphone restriction on iOS app extensions means an iOS wave-1 would ship a different, worse interaction model (app-switch dictation) and would teach the project nothing transferable about the IME-centred design. - **A thin "remote control" app** (phone as a microphone for the desktop) *as the mobile product.* It is a good feature and is kept as a deferred item in `docs/mobile/portability.md`, but it requires a desktop on the same LAN and so does not serve the phone-only user who is the reason to do this at all.