Where Is the Source of Truth for Billing State? Designing the ad-free Pattern with Antigravity

AdFreeManager: The Single Source

AdFreeManager becomes the sole origin of billing state in the app. Its design reflects a deliberate choice: callers don't need to know whether the user is ad-free because they purchased the product or because they watched a rewarded ad. That distinction is encapsulated inside.

class AdFreeManager private constructor(
    private val billingManager: BillingManager,
    private val rewardManager: RewardedAdManager
) {
    val isAdFree: Boolean
        get() = billingManager.isPurchased() || rewardManager.isAdFreeSession
 
    val isPermanentlyAdFree: Boolean
        get() = billingManager.isPurchased()
 
    val isSessionAdFree: Boolean
        get() = rewardManager.isAdFreeSession && !billingManager.isPurchased()
 
    companion object {
        @Volatile private var instance: AdFreeManager? = null
 
        fun getInstance(
            billingManager: BillingManager,
            rewardManager: RewardedAdManager
        ): AdFreeManager = instance ?: synchronized(this) {
            instance ?: AdFreeManager(billingManager, rewardManager).also {
                instance = it
            }
        }
    }
}

The singleton pattern guarantees consistent state across the entire app. @Volatile combined with synchronized prevents race conditions during instance creation in a multithreaded environment — the double-checked locking pattern, properly implemented in Kotlin.

Exposing three properties rather than one is intentional. Most locations should use isAdFree. But some features want to distinguish between permanent and session-only access — for example, showing a "thank you for your purchase" message only to permanent subscribers, or tracking rewarded ad engagement separately. The three-property design makes those distinctions explicit without pushing the logic back into callers.

BillingManager: Bridging Google Play Billing

BillingManager wraps Google Play Billing Library and handles the asynchronous reality of purchase verification. The design decision that matters most here is using StateFlow for purchase state.

StateFlow is a Kotlin Coroutines construct: it holds a value and automatically notifies collectors when that value changes. For purchase state, StateFlow fits naturally because purchase events — completion, restoration, revocation — arrive asynchronously. A StateFlow-based design means the UI reacts to those events automatically without polling or manual refreshes. Configuration changes (screen rotation) trigger automatic re-emission of the current value, so UI state is never lost.

class BillingManager(private val context: Context) {
 
    private var billingClient: BillingClient? = null
    private val _isPurchasedFlow = MutableStateFlow(false)
    val isPurchasedFlow: StateFlow<Boolean> = _isPurchasedFlow.asStateFlow()
 
    init { setupBillingClient() }
 
    private fun setupBillingClient() {
        billingClient = BillingClient.newBuilder(context)
            .setListener { billingResult, purchases ->
                if (billingResult.responseCode == BillingClient.BillingResponseCode.OK) {
                    handlePurchases(purchases)
                }
            }
            .enablePendingPurchases(
                PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()
            )
            .build()
        connectAndVerify()
    }
 
    private fun connectAndVerify() {
        billingClient?.startConnection(object : BillingClientStateListener {
            override fun onBillingSetupFinished(billingResult: BillingResult) {
                if (billingResult.responseCode == BillingClient.BillingResponseCode.OK) {
                    queryExistingPurchases()
                }
            }
            override fun onBillingServiceDisconnected() { }
        })
    }
 
    private fun queryExistingPurchases() {
        val params = QueryPurchasesParams.newBuilder()
            .setProductType(BillingClient.ProductType.INAPP)
            .build()
        billingClient?.queryPurchasesAsync(params) { billingResult, purchases ->
            if (billingResult.responseCode == BillingClient.BillingResponseCode.OK) {
                handlePurchases(purchases)
            }
        }
    }
 
    private fun handlePurchases(purchases: List<Purchase>?) {
        val hasPurchased = purchases?.any { purchase ->
            purchase.products.contains(PRODUCT_ID_AD_FREE) &&
            purchase.purchaseState == Purchase.PurchaseState.PURCHASED
        } ?: false
        _isPurchasedFlow.value = hasPurchased
    }
 
    fun isPurchased(): Boolean = _isPurchasedFlow.value
 
    companion object {
        const val PRODUCT_ID_AD_FREE = "remove_ads"
    }
}

Notice that handlePurchases is called in two places: through the setListener callback when a purchase completes, and through queryExistingPurchases at connection setup. This ensures the state is accurate both on app launch (for existing purchasers) and immediately after a new purchase completes.

ModalGate: Preventing Dialog Conflicts

The Source of Truth principle extends naturally to dialog management. Beautiful HD Wallpapers has three dialogs that can potentially surface simultaneously:

• PaywallDialog: Ad removal upsell
• ReviewInductionDialog: In-app review prompt
• RewardedInterstitialDialog: Rewarded ad explanation and consent

When these compete, user experience breaks down in ways that are difficult to reproduce but easy to complain about in reviews. A user trying to dismiss the paywall gets the review prompt instead. A user about to watch a rewarded ad gets interrupted by another dialog. These are real scenarios that generated real user complaints.

The underlying problem is that each dialog has no visibility into whether another is already showing. The solution is a centralized gatekeeper — a singleton through which all dialogs attempt to acquire display rights.

object ModalGate {
    private val activeModal = AtomicReference<String?>(null)
 
    fun tryShow(tag: String): Boolean {
        return activeModal.compareAndSet(null, tag)
    }
 
    fun dismiss(tag: String) {
        activeModal.compareAndSet(tag, null)
    }
 
    fun isShowing(): Boolean = activeModal.get() != null
    fun currentTag(): String? = activeModal.get()
}

AtomicReference.compareAndSet(expected, update) swaps the value only when it currently matches expected, returning true on success. This is a lock-free compare-and-swap: thread-safe by construction, no risk of deadlocks. The protocol is simple — try to acquire, show on success, dismiss gracefully on failure.

class PaywallDialog : DialogFragment() {
 
    override fun onStart() {
        super.onStart()
        if (!ModalGate.tryShow(TAG)) {
            dismissAllowingStateLoss()
        }
    }
 
    override fun onDismiss(dialog: DialogInterface) {
        super.onDismiss(dialog)
        ModalGate.dismiss(TAG)
    }
 
    override fun onDestroyView() {
        super.onDestroyView()
        ModalGate.dismiss(TAG)
    }
 
    companion object {
        const val TAG = "PaywallDialog"
    }
}

The onDestroyView dismiss is a safety net for cases where onDismiss is never called — when the app is killed in the background due to memory pressure, for example. The double-dismiss is safe because compareAndSet is idempotent when the value doesn't match.

Three Traps I Walked Into

This design was not born clean. Here are the problems I encountered during implementation.

Trap 1: BillingClient connection timing

BillingClient connects asynchronously. Calling isPurchased() immediately on app launch returns false before connection is established — meaning a legitimate purchaser sees ads for a brief moment at startup. This is surprising and erodes trust.

The fix is to use StateFlow reactively rather than polling. During SplashScreen, initiate the BillingClient connection and wait for queryExistingPurchases to complete before transitioning to the home screen. The added SplashScreen time is a worthwhile tradeoff for correctly hiding ads on launch for every purchaser.

Trap 2: Stale ModalGate state after process death

When an app returns to the foreground after being killed in the background, ModalGate.activeModal can retain a stale tag if the dialog was destroyed without calling onDismiss. The result: subsequent tryShow calls all return false, permanently preventing any dialog from appearing.

The fix: call ModalGate.dismiss(TAG) in both onDismiss and onDestroyView. The compareAndSet semantics make the duplicate call safe — if the tag doesn't match (because another dialog is active), nothing changes.

Trap 3: Singleton state pollution in unit tests

As a Kotlin object, ModalGate is a process-lifetime singleton. Test cases sharing the same singleton instance interfere with each other. A test that acquires the gate but doesn't release it causes all subsequent tests' tryShow calls to fail.

The fix: add a @VisibleForTesting fun reset() method to ModalGate that clears activeModal, and call it in each test's @Before. The annotation documents the intent without restricting access.

Using Antigravity as an Architecture Partner

The designs above came through conversation with Antigravity. I want to be specific about what that means, because "talk to the AI" is vague advice that often produces shallow results.

The interactions that generated useful output looked like this. "Both BillingManager and SharedPreferences hold purchase state. Which should be the Source of Truth? Give me the reasoning, not just the answer." Or: "I want to prevent competing dialogs. Show me two approaches — one with AtomicReference and one without — and explain the tradeoffs." Or: "Here is my implementation. List the potential failure modes, specifically around threading and Fragment lifecycle."

The pattern is: ask for reasoning, not just code. Ask for alternatives, not just recommendations. Ask for failure modes, not just happy paths. When Antigravity explains why before generating the code, that reasoning becomes part of your architecture vocabulary — not just a copied snippet.

My paternal and maternal grandfathers were both temple carpenters. In our family, there was a saying: "Using your hands is its own form of prayer." I've held onto that idea across 12 years of app development. Even with AI-generated code, I read through each line before committing it. The process of verification is where understanding happens.

UI Integration: Reactive Ad Visibility with StateFlow

Here is how the three components come together in practice.

class MyApplication : Application() {
    lateinit var billingManager: BillingManager
        private set
    lateinit var rewardedAdManager: RewardedAdManager
        private set
    lateinit var adFreeManager: AdFreeManager
        private set
 
    override fun onCreate() {
        super.onCreate()
        billingManager = BillingManager(this)
        rewardedAdManager = RewardedAdManager()
        adFreeManager = AdFreeManager.getInstance(billingManager, rewardedAdManager)
    }
}
 
class HomeFragment : Fragment() {
    private val app by lazy { requireActivity().application as MyApplication }
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        viewLifecycleOwner.lifecycleScope.launch {
            app.billingManager.isPurchasedFlow.collect { _ ->
                updateAdVisibility()
            }
        }
    }
 
    private fun updateAdVisibility() {
        binding.bannerAdView.visibility =
            if (app.adFreeManager.isAdFree) View.GONE else View.VISIBLE
    }
}

When a purchase completes, isPurchasedFlow updates. Every Fragment collecting it calls updateAdVisibility() automatically. No manual screen refresh. No "please restart the app to apply your purchase." The design eliminates the friction that the bug was creating.

The Long-Term Return on Architectural Investment

Centralized billing state design pays dividends that compound over time. When adding a new subscription tier, the change lives in AdFreeManager.isAdFree. When adding a new ad format, the change lives in RewardedAdManager. When adding a new dialog, it plugs into ModalGate and inherits conflict prevention automatically.

The alternative is continuing to update scattered conditions spread across a codebase that grows more fragile with each feature. After running apps with tens of millions of downloads across more than a decade, I've learned that the problems most likely to damage user trust are the ones that feel intermittent and hard to reproduce — exactly the class of bugs that distributed billing state creates.

Where to Start Today

Run this against your own codebase:

grep -rn "is_ad_free\|isPurchased\|isAdFree\|isAdRemoved" \
  app/src/main/java/ --include="*.kt" --include="*.java" | wc -l

If you get more than ten results, a Source of Truth refactor is worth planning. Show Antigravity your existing billing state code and ask for help identifying the canonical source. Have the conversation about architecture before asking for code. The design clarity you get from that conversation is more valuable than any individual implementation.

Building this foundation doesn't produce visible features. But it changes what's possible afterward — and how sustainable the development becomes over years.