arch: introduce 'Destination' pattern

[david-allison]

Split into:

• refactor(card-browser): BrowserDestination #21027

Note

Assisted-by: Claude Opus 4.7

Purpose / Description

When we move to feature modules, we need a way to navigate between features without introducing cross-module dependencies (as these will nullify the build time/parallelism goals we hope to coomplish). This PR introduces a Destination class and navigate(Destination)

Sample usage in an Activity/Fragment

// the object should be produced in the ViewModel
navigate(BrowserDestination.ScrollToCard(deckId = 1, cardId = 1))

Fixes

• Part of Abstract browser access with BrowserDestinations #20558
• See Architecture Discussion: Module Extraction #20737

Approach

• chore(architecture): add anki-common module skeleton #21028
  • Introduced for this PR
• I implemented navigate in a similar style to Refactor: extract CrashReportService interface to :common #20739
• I did some refactoring to move non-navigation concerns outside BrowserDestination
• I moved BrowserDestination to the new module and applied the pattern
• I did not fully apply the pattern to close the issue, as the PR was already long

How Has This Been Tested?

Unit tested

Checklist

• You have a descriptive commit message with a short title (first line, max 50 chars).
• You have commented your code, particularly in hard-to-understand areas
• You have performed a self-review of your own code
• UI changes: include screenshots of all affected screens (in particular showing any new or changed strings)
• UI Changes: You have tested your change using the Google Accessibility Scanner

[BrayanDSO]

I suggest splitting the anki-common part from the destination part on different PRs

Currently, I'm still trying to understand the purpose/goal/usefulness of the destination module

[david-allison]

I've done some digging and (surprisingly) I don't believe we have cycles in our navigation graph. I'll self-assign and clean up the README.

EDIT: README was clean; I may want a note in com.ichi2.anki.destinations - open to suggestions

---

When we move to feature modules [for build speed + architecture], we should aim to have no dependencies between feature modules.

• Cyclic dependencies are not possible. Allowing cross-feature dependencies quickly leads to cycles and build errors
• Cross-module dependencies slow the build:
  • Transitive dependencies define an ordering, which can't be compiled in parallel

'Destination/navigate' acts as a 'mediator' in Google's terminology, as this is the one place where there would need to be dependencies between features: https://developer.android.com/topic/modularization/patterns#communication

Once we've removed the bulk of cross-feature dependencies via destinations, we can pick higher yield modules to extract, rather than needing to work from the leaf nodes in the nav graph

Also see: https://github.com/android/nowinandroid/blob/main/docs/ModularizationLearningJourney.md#feature-modules

---

Just to note: a lot of what's in the two linked pages above is far too 'enterprise' for us. End goals:

• Measurably faster compile + test times due to incremental builds + smaller modules
• internal reduces public API surface area
• Better architecture: no cycles, more obvious impact of changes, 'stable core'
• jvm-library split - no Robolectric overhead
• 'modules as milestones' to use [for a Compose migration]

[criticalAY]

I am not a big fan of this, where we have to explicity handle the import, maybe rename the old one and mark that as deprecated?
i.e.

interface Destination {
    fun toIntent(context: Context): Intent
}

to

@Deprecated(
    "Use com.ichi2.anki.destinations.Destination + navigate(). See #20558.",
    ReplaceWith("com.ichi2.anki.destinations.Destination"),
)
interface IntentDestination {
    fun toIntent(context: Context): Intent
}

or anything better?

[david-allison]

I'd rather handle this in a follow up. I've kept the original issue open, and "doing it right" in the next PR is better than a temporary rename

[david-allison]

I added a TODO, but not the rename, would rather churn the code once