From f7f8ea442fb82d097d88717329adc1decd988662 Mon Sep 17 00:00:00 2001 From: "Luis Guzman (AppDevForAll)" Date: Wed, 19 Aug 2026 04:52:07 -0600 Subject: [PATCH] ADFA-5192 docs(legacy): removal plan for the legacy tabbed UI --- controller/docs/retire-legacy-ui-plan.md | 117 +++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 controller/docs/retire-legacy-ui-plan.md diff --git a/controller/docs/retire-legacy-ui-plan.md b/controller/docs/retire-legacy-ui-plan.md new file mode 100644 index 00000000..54c7509d --- /dev/null +++ b/controller/docs/retire-legacy-ui-plan.md @@ -0,0 +1,117 @@ +# Retire the legacy tabbed UI — removal plan + +ADFA-5192 (under Epic ADFA-1028). Design / removal plan. 2026-08-19. + +## Why + +The app's live UI is the redesign: the launcher is `SplashActivity`, which routes +**only** to `redesign.LibraryActivity` (`SplashActivity.java:67`). `MainActivity` has +no launcher and no intent-filter (`AndroidManifest.xml`) — nothing opens its tabbed UI +as a screen. The legacy Status / Use / Install / Send pager +(`DashboardFragment`, `UsageFragment`, `DeployFragment`, `SyncFragment`) and the five +presentation controllers `DeployFragment` carved out are dead UI: reachable by no one. + +`MainActivity` survives for one live reason only — it hosts the Debian **terminal** — +plus it is the declared home of two terminal `EXTRA_*` constants. This plan removes the +dead legacy UI and re-homes the terminal so `MainActivity` can go with it. + +This is **pure dead-code removal**, not a behaviour change. The redesign install / +backup / content flows do not touch any of the deleted classes. + +## Verified state (the facts this plan rests on) + +- **Launcher.** `SplashActivity` (`AndroidManifest.xml`, `` with + `LAUNCHER`) → `redesign.LibraryActivity` only (`SplashActivity.java:67`). + `MainActivity` has no `LAUNCHER` / intent-filter. +- **Only two launches of `MainActivity`, both terminal-only.** Both pass + `EXTRA_TERMINAL_ONLY = true`: + - `TerminalSessionService.java:98-101` + - `redesign/SettingsSubFragment.java:210-213` + There is **no leak**. (An earlier roadmap note assumed a `TerminalSessionService` + launch reached the full tabbed UI by omitting the terminal-only extra — verified + false; both launches set it.) +- **The four fragments are legacy-only.** Their only constructor site is + `MainPagerAdapter`. No redesign class references them. +- **The five controllers + five Hosts are legacy-only.** `InstallController`/`InstallHost`, + `PlannerController`/`PlannerHost`, `ResetDeleteController`/`ResetDeleteHost`, + `AdbShareController`/`AdbShareHost`, `BackupController`/`BackupHost` — all hosted by + `DeployFragment`; no redesign reference. +- **The redesign reads no `MainActivity` instance state.** The only cross-boundary + coupling is the two terminal `EXTRA_*` constants + `MainActivity.class` (for the + terminal launch). `iiab_queue_prefs` / `is_module_state_trusted` is co-owned by + `InstallService` (no migration needed). `WatchdogService` already points at + `LibraryActivity`, not `MainActivity`. +- **The domain/service/repository layer stays.** The redesign install/backup path uses + `InstallService`, `InstallProgressRepository`, `ModuleQueueRepository`, `InstallState`, + `DownloadStateViewModel`, `BackupEngine`. None of these are legacy UI. **Keep them.** + +## The 5144 connection + +The companion install leg — `InstallService.startCompanionData()` (`:685`) → +`downloadAndIndexKiwix()` (`:707`) — fires only when `companion = true` +(`InstallService.java:318`, from `EXTRA_COMPANION`). That extra is set in exactly one +place: the legacy `InstallController.java:164`. This is the leg ADFA-5144 was opened to +fix (a failed ZIM download/index there routed to `finishSuccess()`, i.e. a false +SUCCESS). + +Because the modern wizard already banks content honestly through the live path +(`addZimViaLiveChannel`, whose `onError` calls `fail(...)`), the dishonest leg is +reachable **only** through the legacy `InstallController`. Deleting the legacy UI +removes the only caller, so `startCompanionData` / `downloadAndIndexKiwix` / +`EXTRA_COMPANION` become dead code and are removed here. **ADFA-5144 is resolved by this +retirement** — there is no live dishonest terminal left to fix. + +## Blockers + +- **B1 — `MainActivity` builds the tabs unconditionally.** `MainActivity.onCreate` + inflates `R.layout.main` (`:296`) and builds `MainPagerAdapter` (`:290`) even in + terminal-only mode (the tabs are just hidden behind a black sheet at `:605-608`). So + the fragments + controllers are still instantiated while `MainActivity` lives — they + **cannot** be deleted until `MainActivity` stops referencing them. The terminal + re-home and the deletion therefore ship **together** (see Phases). +- **B2 — the terminal is `MainActivity`'s only live use.** It must be re-homed before + `MainActivity` can be deleted, without regressing how the terminal opens today + (from redesign Settings and from the terminal notification). + +## Plan + +Two phases; ship them together (B1) or as a tightly-coupled pair. + +### Phase B — re-home the terminal to a thin `TerminalActivity` + +Extract the terminal into its own activity so nothing depends on `MainActivity`: + +- New `TerminalActivity` implementing the terminal `Host` (only `addToLog` + + `vibrateDevice` are used by the terminal path). +- Move into it: the terminal bottom-sheet + extra-keys subtree of `R.layout.main`, the + `System.loadLibrary("termux")` block, and the two `EXTRA_*` terminal constants. +- Repoint the two callers at `TerminalActivity`: + `TerminalSessionService.java:98-101` and `redesign/SettingsSubFragment.java:210-213`. + +### Phase A — delete the legacy UI + +- `MainPagerAdapter`; `DashboardFragment`, `UsageFragment`, `SyncFragment`, + `DeployFragment`. +- The five controllers + five Hosts (listed above). +- `MainActivity` + its manifest `` entry (`AndroidManifest.xml`) + + `R.layout.main`. +- The orphaned `tab_*` strings and any layouts left unreferenced after the fragments go. +- The dead companion install leg: `startCompanionData`, `downloadAndIndexKiwix`, + `EXTRA_COMPANION` (and any now-unreferenced helpers they alone used). + +**Keep:** `InstallService` and the install/backup domain + service + repository layer. + +## Acceptance + +- The terminal opens from redesign Settings and from the terminal notification exactly + as before, hosted outside `MainActivity`. +- `MainActivity`, `MainPagerAdapter`, the four fragments, the five controllers + Hosts, + the companion install leg, `R.layout.main` and the `tab_*` strings are gone. +- The build is green (no dangling references, no `MissingTranslation` from removed + strings). +- No behaviour change to the redesign install / backup / content flows. + +## Out of scope + +- Any redesign refactor. This is deletion + one terminal re-home, nothing more. +- The install/backup domain layer (kept).