Architecture Discussion: Module Extraction

[criticalAY]

Architecture: Multi-module structure for AnkiDroid

Context

We want AnkiDroid to move to a multi-module structure. :widgets is our first feature module extraction target.

Current module layout:

:AnkiDroid (app) → :common, :compat, :libanki, :vbpd, :api, :widgets
:widgets → :common, :libanki
:compat → :common
:libanki → :common

Current :widgets progress:

• 18 files moved to :widgets (infrastructure, preferences, bridge interfaces, business logic)
• 7 files remain in :AnkiDroid (4 widget providers blocked by R resources, 2 config activities + 1 adapter blocked by AnkiActivity/dialogs/databinding)
• 7 bridge interfaces in :widgets to abstract :AnkiDroid dependencies

Problem: Bridge interfaces per feature module don't scale

To break circular dependencies between :widgets and :AnkiDroid, we created 7 bridge interfaces inside the :widgets module:

Bridge in :widgets	Wraps dependency in :AnkiDroid
WidgetAnalytics	UsageAnalytics.sendAnalyticsEvent()
WidgetCrashReporter	CrashReportService.sendExceptionReport()
WidgetCollectionAccess	CollectionManager.withCol {}
WidgetIntentFactory	IntentHandler, NoteEditorLauncher, DeckOptionsDestination
WidgetAppState	AnkiDroidApp (scope, sdcard, instance)
WidgetMetaStorage	MetaDB widget operations
WidgetPreferences	sharedPrefs(), Prefs

Each bridge requires an interface in :widgets + an implementation class in :AnkiDroid + wiring in AnkiDroidApp.onCreate().

If every feature module does this, we'd get:

:widgets  → WidgetAnalytics, WidgetCrashReporter, WidgetCollectionAccess...
:browser  → BrowserAnalytics, BrowserCrashReporter, BrowserCollectionAccess...
:reviewer → ReviewerAnalytics, ReviewerCrashReporter, ReviewerCollectionAccess...

Duplicated interfaces with different prefixes, each needing its own XImpl in :AnkiDroid. This doesn't scale.

Proposed approach: Extract dependencies to lower modules

Instead of creating per-feature bridge interfaces, move the dependencies themselves (or their interfaces) to :common or :libanki. Feature modules then use them directly — no bridges, no per-module boilerplate.

Example — Analytics (already extracted to :common):

// :common — interface defined once
interface UsageAnalytics {
    fun sendAnalyticsEvent(category: String, action: String, value: Int? = null, label: String? = null)
    fun sendAnalyticsScreenView(screenName: String)
}

// :common — short accessor object
object Analytics {
    fun setAnalytics(analytics: UsageAnalytics) { ... }
    fun sendAnalyticsEvent(...) = instance.sendAnalyticsEvent(...)
}

// :AnkiDroid — implementation (internal, invisible to other modules)
internal object AnkiDroidUsageAnalytics : UsageAnalytics { ... }

// AnkiDroidApp.onCreate()
Analytics.setAnalytics(AnkiDroidUsageAnalytics)

// :widgets or any module — just use it
Analytics.sendAnalyticsEvent("CardAnalysisWidget", "enabled")

One interface. One implementation. Used by every module. No WidgetAnalytics, no BrowserAnalytics.

This replaces WidgetAnalytics bridge and its WidgetAnalyticsImpl — we can delete both.

Per-dependency analysis

Dependencies that should be extracted (used across the entire app)

These are used by 6 out of 7 bridge interfaces. Extracting them benefits all future feature modules, not just :widgets.

Dependency	Current location	Used by (files)	Proposed home	Approach
UsageAnalytics	:AnkiDroid	~15	:common	Done — interface in :common, internal impl in :AnkiDroid
CrashReportService	:AnkiDroid	49	:common	Same pattern — CrashReporter interface in :common
sharedPrefs()	:AnkiDroid	51	:common	Done — moved function to :common(locally)
AnkiDroidApp.applicationScope	:AnkiDroid	~20	:common	Provide AppScope object in :common with a settable CoroutineScope
AnkiDroidApp.isSdCardMounted	:AnkiDroid	~5	:common	One-line utility, move to :common

After extracting these, the WidgetAnalytics, WidgetCrashReporter, WidgetPreferences, and WidgetAppState bridges can be deleted.

Dependencies that need further discussion (separate issues)

Dependency	Why it's complex	Replaces bridge
CollectionManager / withCol	Core architectural component. Depends on :libanki backend. Candidate for :libanki:ext[:android]. Needs its own design discussion.	WidgetCollectionAccess
String resources (R.string.*, R.layout.*)	Widget providers need RemoteViews with layout/string resources at runtime. Options: move widget resources to :widgets, shared :resources module, or keep widget providers in :AnkiDroid. Intersects with Crowdin localization pipeline.	N/A (blocks file moves, not a bridge)

Dependencies where a bridge interface is appropriate

Dependency	Why bridge is OK	Bridge
MetaDB (widget status storage)	Only used by widgets. Other feature modules won't need storeSmallWidgetStatus(). A widget-specific interface is fine here.	WidgetMetaStorage
IntentHandler (navigation intents)	Creates Intents to specific Activities (IntentHandler::class.java, DeckOptionsDestination). Navigation is inherently app-level. Could evolve into a shared navigation component later, but a bridge is pragmatic for now.	WidgetIntentFactory

Impact on :widgets after extractions

After extracting...	Bridges we can delete	Files unblocked
CrashReportService → :common	WidgetCrashReporter + impl	—
applicationScope → :common	WidgetAppState (partially)	—
CollectionManager → :libanki:ext	WidgetCollectionAccess + impl	—
String resources → :widgets or :resources	—	AddNoteWidget, AnkiDroidWidgetSmall, CardAnalysisWidget, DeckPickerWidget (4 files)
All of the above	5 of 7 bridges deleted	All widget files movable

Open questions for the team

1. What should :common be?
   Proposal: the core of the system. All cross-module concerns live here — analytics, crash reporting, preferences, scopes, shared utilities. No Anki-specific business logic.

2. Should :common sit below :libanki?
   Current: :libanki → :common. Proposal: cross-module concerns that depend on :libanki (e.g., CollectionManager) go in :libanki:ext[:android], not in :common.

3. How does a new developer know where to put a file?

   You're writing...	Put it in...
   UI (Activity, Fragment, layout)	:AnkiDroid or feature module
   Cross-module service interface	:common
   Cross-module service implementation	:AnkiDroid (mark internal)
   Shared utility with no Anki knowledge	:common
   Anki collection/backend operation	:libanki or :libanki:ext

4. How do we prevent coupling to concrete implementations?
   Proposal: implementations are internal to their module. Only interfaces + accessor objects from :common are public. This is compile-enforced — internal classes are invisible to other modules.

Out of scope (separate issues)

• CollectionManager extraction — moving to :libanki:ext[:android]. Large scope, needs its own design. Currently abstracted via WidgetCollectionAccess bridge.
• String resource strategy — shared :resources module vs per-feature resources vs keeping in :AnkiDroid. Impacts Crowdin pipeline. Blocks moving 4 widget provider files.
• Navigation architecture — how feature modules create Intents to Activities in other modules. Currently handled by WidgetIntentFactory bridge.
• Testing infrastructure — RobolectricTest base class is in :AnkiDroid, but feature module tests need it. Blocks moving test files.

[criticalAY]

Current State of :widgets

Already in :widgets : Infrastructure, preferences, bridge interfaces, and business logic that had no :AnkiDroid dependencies (or were decoupled via bridge interfaces).

• https://github.com/ankidroid/Anki-Android/pull/20733/changes

Still in :AnkiDroid (7 files I guess): Widget providers (AddNoteWidget, AnkiDroidWidgetSmall, CardAnalysisWidget, DeckPickerWidget) and config activities all blocked by com.ichi2.anki.R and/or AnkiActivity.

[david-allison]

Referencing my comment in the linked PR

The aim with modularisation is to work through the dependency chain so:

• We start with the easy modules
• Each module makes the remainder of the modules easier to deal with, by establishing scalable patterns

This move should be more incremental. Likely in PRs for each big dependency, so we're not adding much (if any) boilerplate to break circular dependencies when we make the move

Every module is going to depend on a Crash report service, so it should be in a lower module (common) and either wired up there, or if this is not possible/desired, defined in common as an interface and configured in an upper module

We also want strings inside or below the module, which is a larger topic for discussion

My common refractor today was after thinking about how to move CollectionManager down the dependency chain, into :libAnki:ext[:android].

This is probably a great way to start the discussion:

• Make an issue to discuss the architecture concerns for :widgets

  • I'm running with the belief that common should be where all our common code goes, libanki depends on this as a jvm-library and libanki:ext[:android] exposes non-pylib Anki-dependent functionality

• [Module]Refactor: widget module #20733 (review)

---

I feel the concerns listed are all going to be used heavily cross-module, so these are candidates to be moved into a base module.

Trivial to implement, requiring consensus

1. ❓ Move these to common[:android] arch: split :common:android from :common #20731
2. ❓ Does the implementation live in common, or AnkiDroid

• Analytics
  • feat: analytics interface in :common #20736
• Destinations
  • Expose Destination classes, with a navigate(destination: Destination) method
  • Abstract browser access with BrowserDestinations #20558
  • arch: introduce 'Destination' pattern #21023
• Crash Reporting
  • See Refactor: extract CrashReportService interface to :common #20739 for the agreed pattern
• SD Card
  • refactor: extract isSdCardMounted from AnkiDroidApp to :common:android #20925

For further discussion, probably as a sub-issue

• Preferences: difficult to find a good seam
• WidgetAppStateImpl: this will be difficult
  • Silver lining: some of these look like they don't belong here
• Strings

Module specific

• MetaDB: might be an excuse to recode this one, maybe DataStore/Room is better here.
  • Maybe a Widget-specific interface with an injected implementation in the app (although this could make testing difficult)

[BrayanDSO]

The plan looks good to me.

• MetaDB: the new study screen won't use it, so only the widget functionality will use it. That's another excuse to recode it
• Strings: split them. Widget strings should be on the widget module.

[david-allison]

Strings: move all into :common:android.

This unblocks us simply/quickly and allows a future discussion about the CrowdIn sync/file architecture.

---

Medium-term: I think :widgets containing strings will be a "Won't fix" for a while

Architecturally, strings should live in their modules, but I think moving strings up into :widgets would:

• Mildly improve R.string via namespacing
• Produce minimal performance gains (the resources would still need to be bundled inside the app).
• Not improve discoverability (developers know where the strings are)
• Add disruption/infra complexity in the case that a string needs to be pulled up/down from :widgets into common:android
  • Also with lint & cross-module duplication checks
• Not have any tangible benefit to translators

I don't see the upsides being worth the time to update our translation infra for this.

[BrayanDSO]

I agree. The main difference is keeping things "organized" and on the "ideal state" architecturally, but the pratical differences are minimal.

[Giyutomioka-SS]

I’d like to help with this. I’ve gone through the issue and linked PRs.

I’m thinking of moving the widget-specific MetaDB methods behind a WidgetStatusStorage interface while keeping the current implementation as-is for now. Migration to DataStore/Room can be a follow-up.

Would this approach be okay?

[david-allison]

Sure! WidgetRepository would work as a name.

• See [Module]Refactor: widget module #20733
  • General concept, I feel the interface could be tightened up
• See arch: introduce 'Destination' pattern #21023
  • For how Context may be removed as a parameter

this should work:

 interface WidgetRepository {
     fun storeSmallWidgetStatus(status: SmallWidgetStatus)
     fun getWidgetSmallStatus(): SmallWidgetStatus
     // TODO: name this better - dueCardsCount?
     fun getNotificationStatus(): Int
 }

I wouldn't use anything suspend here for such a small amount of data.

---

For future (out of scope) optimizations. Claude mentioned https://github.com/tencent/mmkv when I last thought about MetaDB - I haven't dug in deep, but it looks ridiculously fast

[Giyutomioka-SS]

The widget only stores two cached values (due count and eta), and they are recalculated on every update, so migration does not seem necessary.

Options considered:

Option	Pros	Cons
MMKV	Synchronous API (fits the current interface), very fast, simple API	Adds a native dependency (~50KB per architecture), not Jetpack
DataStore	Jetpack-supported, no native code	Async-first API adds extra complexity for storing just 2 values
Room	Jetpack-supported, type-safe	Feels too heavy for a single cached row
SharedPreferences	No new dependency, synchronous	Older API, less type-safe, generally replaced by DataStore

I'm leaning toward MMKV since it was mentioned in the issue.
The synchronous API matches the current non-suspending interface nicely, and it is well tested.

Which option would you prefer?

[david-allison]

I don't think we need to take this on yet. Let's leave it as a TODO and defer it until the interface needs to be expanded.

MetaDB is OK for now, it's fast, doesn't require suspend and is battle-tested.

An improved architecture is a goal which we should strive for as it benefits all developers. MetaDB is stable and won't pay off unless we have development capacity.

[Giyutomioka-SS]

I don't think we need to take this on yet. Let's leave it as a TODO and defer it until the interface needs to be expanded.

MetaDB is OK for now, it's fast, doesn't require suspend and is battle-tested.

An improved architecture is a goal which we should strive for as it benefits all developers. MetaDB is stable and won't pay off unless we have development capacity.

Makes sense, I’ll leave that as a TODO for now.

Is there anything else in scope for #20737 I could pick up next, or should I wait for the other dependencies to land first?

[david-allison]

I'd check with @criticalAY - potentially moving the AnkiDroidApp 'application' context down to common:android

• EDIT: refactor: extract AnkiDroidApp.instance to :common:android #21164

[criticalAY]

@Giyutomioka-SS I am ready with widget extraction at a very high level where there is no dependency on other things and you can follow what David suggested as that is something that I would have done next