Welcome to the
stc pay Android App

Welcome aboard — and take a breath.

stc pay is a big app, and nobody expects you to hold all of it in your head this week. Think of this guide as your map, not a test: skim what you need now, and come back to the rest when a real ticket pulls you there. By the end of §04 you’ll have the whole app in one mental picture — everything after that just fills it in.

Pace yourself like this

Along the way: monospace means a real file, class or command; coloured callouts flag things worth noticing; and a “To complete” callout marks a spot only the team can fill in.

First stop: a 60-second picture of what you’re actually building.

The whole map on one page — jump in wherever you need.

• A · Start Here
• §01Welcome & How to Read This
• §03What You’re Building
• §04The Whole App in One Picture
• B · The Codebase Map
• §05Where Everything Lives — the Modules
• §06Tech Stack & Key Libraries
• §07Conventions You’ll See Everywhere
• C · Getting It Running
• §08Before You Start — Access & Tools
• §09Clone, Configure & Build
• §10Variants, Flavors & Environments
• §11Run It & Fix Common Snags
• D · How the App Works
• §12From Launch to First Screen
• §13Navigation & Deep Links
• §14The MVVM Pattern (the backbone)
• §15Talking to the Backend & Storing Data
• §16The Things Every Screen Relies On
• E · Walkthroughs
• §17Onboarding, Login & Registration
• §18eKYC — Verifying Identity
• §19Send Money, Start to Finish
• §20The Payment Rails
• F · Working Here
• §21Branches, Versions & Releases
• §22Reviews, People & Getting Help
• §23Glossary
• §24Cheat-Sheet & Your First Week

stc pay is a digital wallet — a “super-app” that puts a lot of money services behind one login. This repo is the customer-facing Android app for Bahrain, now stretching to Kuwait too (the Gradle project is even named stcPayBH-KW).

In plain terms, a user can hold a balance, top it up, send / request / split money, pay bills and merchants, order a card, remit money abroad, and earn cashback — all in one place. Two themes follow from handling real money, and you’ll feel them throughout the code: regulation (identity checks, OTPs, limits, account statuses) and security (encryption, tamper/root detection, secrets kept out of source).

One app, two app stores: it ships as GMS (Google Play) and HMS (Huawei AppGallery) builds, so it runs with or without Google services.

So that’s the what. Here’s the how, in one picture.

If you remember one sentence from this guide, make it this one:

Hold that, and every feature reads the same way. Here is what actually happens when a user taps something — load a balance, confirm a payment, anything:

1. A Composable screen grabs its ViewModel with hiltViewModel() and shows whatever state the VM exposes.
2. The tap calls a function on the ViewModel (which extends NavigationBaseVM).
3. The VM asks a repository for data; the repository calls the backend via Retrofit.
4. The reply comes back as a NetworkResponse — loading, success, or error — and the screen’s dialogs react to it automatically.
5. To change screen, the VM drops a request to the navigator, and one place turns that into real navigation.

That last step is the one surprise worth flagging early:

That’s the entire app. The rest of this guide just zooms into each part — starting with where all that code actually lives.

~40 modules sounds like a lot, but they fall into four easy buckets — and day to day you mostly live in the one feature you’re working on. Module names matter when you’re navigating the code, so here is every one, with its package root.

Core & infrastructure — the foundation

Common — the shared hub every feature uses

eKYC — identity verification

Features — one module per area

Security & vendored SDKs

How the layers fit together

Dependencies run top-down and never loop: features sit on top of :common, which sits on the foundation. The foundation never reaches up into a feature.

:app  ─►  features:*   +   :notification   +   :biometric_view
                  │
                  ▼
              :common   ( commonui + navigator + repository )
                  │
                  ▼
            :network  ─►  :dto  ─►  :util  ─►  :common:keys  ─►  :securityNDK

The upshot: features never depend on each other’s internals — anything shared lives in :common or :payment. Now, what those modules are built from.

You don’t need to memorise versions — they all live in one file, gradle/libs.versions.toml. Just know the headline numbers and roughly why each library is here.

(minSdk 23 reaches back to Android 6, but core-library desugaring is on, so modern Java APIs still work.)

What each part of the stack is for

One more piece of the map, then we build: the patterns that repeat across every module.

A handful of patterns repeat across the whole codebase. Learn these five and the code stops surprising you.

1 · Two package prefixes

com.stcpay.customer.kuwait is the app and some newer features; com.vivacash.* is everything else (an old brand name). Same project — just history.

2 · Tiny build files, thanks to convention plugins

A feature’s build.gradle.kts is only a few lines because all the real Gradle config lives once in build-logic/convention/ as reusable stcpay.* plugins. A module just applies one or two:

plugins {
    alias(libs.plugins.stcpay.android.library.compose)  // Android + Compose
    alias(libs.plugins.stcpay.hilt)                      // + dependency injection
}
dependencies { implementation(projects.common) }

3 · Predictable names

4 & 5 · Two golden rules

• Share code through :common (or :payment) — never feature-to-feature.
• Navigate through AppNavigator — never give a ViewModel a NavController.

That’s the whole map — what the app is, where the code lives, and how it’s shaped. Let’s get it running on your machine.

Two things to line up: the tools on your machine (quick), and the access only the team can grant (ask early, it can take a day or two).

On your machine

• Android Studio (latest stable), with its Gradle JDK set to 17.
• Git over SSH for the stcpaybh GitHub org.
• The Android NDK + CMake, if you’ll build the native security module.

Ask the team for

Got those? Let’s build it.

The happy path is short:

1. Clone both repos — the app and the UI Kit (stcpay-bh-android-ui-kit). Open the app root in Android Studio.
2. Check the Gradle JDK is 17.
3. Place the secrets & keystore files from the team — debug.properties, release.properties, debug.keystore — at both the repo root and inside util/.
4. Link the UI Kit composite build (set stcPayUiKitProjectPath, below) — this is required.
5. Sync, then build the dev variant: ./gradlew :app:assembleGmsUat.

Required: link the UI Kit (local.properties)

The app depends on the in-house stcpay-ui-kit, supplied from source as a composite build — without it the project won’t sync. Point local.properties at your local clone of the UI Kit repo:

Before you hit Run, one quick word on which build you’re making.

A build variant is just a flavor × a build type — e.g. gmsUat. Both are defined once in build-logic/ and shared everywhere.

Flavor is the app store: gms (Google) or hms (Huawei), each pulling in its own services and a src/gms / src/hms source set. Build type is the environment — and note they’re named after environments, not debug/release:

# this is the one you'll use most
$ ./gradlew :app:assembleGmsUat

$ ./gradlew :app:assembleHmsUat    # Huawei build
$ ./gradlew :app:bundleGmsProd     # release AAB

In Android Studio’s Build Variants panel, pick gmsUat. (Production signing is gated by an IS_PRODUCTION flag — [ to complete: how it’s set in CI ].)

1. Select gmsUat and a device or emulator (Android 6+).
2. Run :app — you’ll land on the splash, then Welcome / Login.
3. Log in with a UAT test account to confirm you’re hitting the UAT backend.

If the build fights you, it’s almost always one of these:

It’s running. Now let’s peek under the hood — what happens from launch to that first screen.

Getting to the first screen is three quick handoffs: the Application, the one Activity, then Compose.

1 · StcApplication wakes up the SDKs

The Hilt application root (@HiltAndroidApp). Its onCreate starts what the whole app leans on — Timber logging (non-prod), the security SDK (prod only), Firebase (skipped on Huawei), the preferences store and device ID, then Adjust, Intercom, OneSignal and the locale engine. Secret keys come from KeysProviderImpl (the native NDK in production).

2 · MainActivity — the only Activity

It draws edge-to-edge, clamps the font scale (so huge system fonts can’t break layouts), sets up the deep-link gate, fetches remote config, then hands everything to Compose with setContent { AppRoot() }.

3 · AppRoot → AppContent — Compose takes over

AppRoot picks light/dark and wraps the app in StcPayTheme. AppContent wires up the navigator and declares the single NavHost where every feature plugs in its screens:

NavHost(navController, startDestination = StcRoute.OnBoarding) {
    onBoardingNavigation(navController)
    onLoginNavigation(navController, prevRepo, onSuccessfulLogin = { session.setLoggedIn(true) })
    onHomeNavigation(navController, prevRepo)
    // … ~20 feature graphs, one line each …
}

That NavHost is the spine of the app — so let’s see how navigation actually works.

One rule sums it up: ViewModels don’t navigate — they post a request, and one place carries it out.

How a screen change happens

AppNavigator holds a channel of navigation requests (go back, go to a route, session-expired, logout…). A ViewModel writes to it; a single Composable, NavigationEffects, reads from it and drives the real NavController. In practice your VM extends NavigationBaseVM, gets AppNavigator injected, and calls a helper like moveBack() / moveToHome() — or appNavigator.navigateTyped(SomeScreen) for anything custom.

Routes — and how to add a screen

StcRoute names the top-level graphs (OnBoarding, Home, Login…); StcScreens names individual screens. Each feature exposes an onXxxNavigation() that the one NavHost calls — and that’s exactly where you register a new screen:

fun NavGraphBuilder.onHomeNavigation(navController, prevRepo) {
    navigation(startDestination = StcScreens.HomeScreen.name, route = StcRoute.Home.name) {
        composable(StcScreens.HomeScreen.name) { HomeScreen2() }
        composable<StcScreens.ProfileScreen> { ProfileScreen() }
    }
}

Deep links & notifications

A tapped notification or an external URL flows through input → parse → gate → dispatch. The interesting part is the gate: it’s a login check. If a link needs you logged in and you aren’t, it parks the link, sends you to Login, and replays it the instant you’re in — which is how a payment push can drop you straight onto the right screen after login.

Every screen those routes lead to is an MVVM ViewModel. That pattern is the real backbone — next.

If there’s one section to actually learn, it’s this one — every screen follows the same loop, so once it clicks you can read any feature in the app.

The loop: a Composable gets its ViewModel with hiltViewModel(), shows the VM’s state, and calls VM functions on taps. The VM extends NavigationBaseVM, runs each API call through a RemoteServiceHandler, and navigates via AppNavigator.

NavigationBaseVM — the base 120+ ViewModels extend

It’s deliberately thin: a ViewModel with the navigator injected and a few navigation helpers. (Loading and error state aren’t here — they live per API call, below.)

@HiltViewModel
open class NavigationBaseVM @Inject constructor(app, val appNavigator: AppNavigator) : AndroidViewModel(app) {
    fun moveBack() = appNavigator.tryNavigateBack()
    fun moveToHome() = appNavigator.tryNavigateBack(StcScreens.HomeScreen.name)
}

RemoteServiceHandler — one API call, automatic UI state

You declare one handler per endpoint, with an apiCall lambda and callbacks. setRequest(req) fires it; the handler flips loading/error flags as the result comes back, and a matching RemoteServiceListener in the screen renders the loading and error dialogs straight off those flags — so you never wire that UI by hand.

val fetchUserRSH = RemoteServiceHandler(
    vm = this,
    remoteServiceCallbacks = object : RemoteServiceCallbacks<BaseRequest, UserResponseBody>() {
        override fun onSuccess(code, body, title, msg) { user.value = body }
    },
    apiCall = { dashboardRepository.userAccount(it) },
)

Adding a screen + ViewModel

1. Add a route to StcScreens.kt.
2. Write a @HiltViewModel VM that extends NavigationBaseVM, exposes state, and declares its API calls as handlers.
3. Write the Composable: hiltViewModel(), show the state, drop in a RemoteServiceListener.
4. Register it in the feature’s onXxxNavigation() (§13).

See step 2, where the VM calls a repository? That’s how the app talks to the backend — let’s open that up.

Good news: every backend call has the same shape — VM → repository → Retrofit → a NetworkResponse — so once you’ve seen one, you’ve seen them all.

Hilt provides one shared OkHttp + Retrofit client (the base URL is set per environment). Service methods hand back LiveData<NetworkResponse<T>>, and request logging is on only in non-prod builds.

From call to result

NetworkResponse is a sealed result type — Loading, Success, the various errors, SessionExpired, NoInternet. A repository wraps a single Retrofit call in a NetworkBoundResource (which unwraps the BaseResponse envelope) and exposes it as LiveData. The shape is always:

override fun getCardServiceDetails(body) =
    object : NetworkBoundResource<Service, …>(Service::class) {
        override fun createCall() = cardApiService.getCardServiceDetails(body)
    }.asLiveData()

Where data lives

SharedPreferences is the main local store (sensitive values like the session id and PIN are hand-encrypted with CryptoHelper). Room appears in exactly one place — the contacts cache. Models are Gson DTOs, each wrapped in a BaseResponse envelope (response-code / -message / data).

A few shared services hum behind all of this. That’s the last piece of “how it works”.

Five pieces of shared machinery you’ll lean on without thinking about them much.

Dependency injection

Hilt, all app-wide (the SingletonComponent). StcApplication is @HiltAndroidApp, MainActivity is @AndroidEntryPoint, and providers live in modules like AppModule, HttpModule and RepositoryModule.

Session & auto-logout

SimpleSessionProvider is the single source of truth (isLoggedInFlow). A 10-minute idle timer logs the user out — but every API call resets it, so active users stay in. On expiry the app shows the session-expired dialog.

Security

Production secrets live in the native :securityNDK. Hardening (root / emulator / tamper checks via SecureUtility) runs only in production and behind a remote-config flag; any hit routes to a SecurityInfoDialog.

Language — English & Arabic

LocaleManager + LocaleWrapper handle language and right-to-left layout; strings are per-module (res/values/ + res/values-ar/). Country (Bahrain vs Kuwait) is a runtime setting (CountrySetup), not a build flavor.

Analytics & push

StcEvents.logEvent() is the one place events fan out to Firebase, Adjust and OneSignal. Push is owned by OneSignal; the native Firebase/Huawei services just forward the token.

That’s the engine. Now let’s watch it run — three real flows, start to finish.

The way in chains three features — onboarding → login → registration — all inside the one NavHost (which starts at OnBoarding).

Onboarding

SplashScreen plays a Lottie animation while SplashScreenVM checks or creates a session (a Firebase flag can act as a kill-switch). When both finish, it routes on to Login.

Login

WelcomeScreen shows a returning user (from the saved number) or a sign-up path. PinScreen takes the MPIN — or a biometric prompt — and fires loginUser() with the encrypted PIN. On success, getRouteBasedOnStatus(...) reads the account status and sends the user wherever they need to be (Home, or back into an eKYC step). The session itself flips in the NavHost wiring: onSuccessfulLogin = { setLoggedIn(true) }.

Registration → eKYC

Sign-up is a short funnel:

1. Mobile number → OTP.
2. Create a password / PIN.
3. Email → verify.
4. Verify identity — pick eKey or Jumio, which hands off to eKYC.

That last step hands off to identity verification — the part unique to a regulated wallet.

A wallet is a regulated product, so the user’s identity must be verified (KYC) before an account or card is issued. The ekyc:* modules do this digitally — ekyc:base (shared logic + the Bahrain eKey flow), ekyc:verification (the screens), and ekyc:location (a GCC location check).

The flow

1. Details — personal & financial info (employment, source of funds, expected spending).
2. Document + liveness — via Jumio (with iProov liveness inside its SDK), or the eKey web flow.
3. Approval — the app polls the backend (~every 5s), showing progress, until the account is approved or declined.

Once verified, the user’s in. Here’s what they do most — move money.

This is the flagship money flow — trace it once and you understand every money feature, because they all share this skeleton.

The home dashboard

On entry, HomeScreen2 fans out several loads at once — balance, cards, the services grid, a two-row recent-activity preview. The balance is cached so other screens can read it instantly, and the services grid is server-driven (the backend decides which tiles appear).

Sending, step by step

1. Pick recipient & amount — to a mobile number or an IBAN; the phonebook icon opens the shared contacts picker.
2. Validate the recipient (an account inquiry call).
3. Review — a confirmation screen carrying the assembled payment details.
4. Pay — pay() fires the payment handler → repository → the pay endpoint.
5. OTP / done — if the server asks for an OTP, a sheet appears and re-submits; on success a receipt sheet shows and the balance refreshes.

Two supporting modules round it out: requestandsplitmoney, and contactsView — in fact the send-money VM extends the contacts list VM to reuse the picker. Send money is just one rail, though. The app plugs into many.

stc pay connects to a lot of payment networks — but they all share the same plumbing (repository → handler → a shared review flow), so this is really just a tour of what each one is.

And a few smaller pieces: cashback (rewards, also usable to pay), Gulf Air MilesPlus, invite-a-friend, home-screen widgets, and the unified transaction history.

That’s the app, end to end. Last stop — how we work on it together.

How code travels from your branch to the app stores.

Branching (Gitflow-style)

You’ll see a big feature/kuwait* cluster too — that’s the Kuwait rollout (adding KW rails, removing some Bahrain-only ones).

Versioning

Semantic MAJOR.MINOR.PATCH, git-tagged each release (currently 8.7.8). It’s defined in exactly one place:

projectVersionName = "8.7.8"
projectVersionCode = "422"

Releasing

The human side. The defaults below are a sensible starting point — confirm and complete them with your lead.

Code review

Branch from develop, open a focused PR back into develop, and link the ticket. [ to complete: required approvals, code owners, the CI checks that must pass ]

Who’s who

Where to get help

The words and acronyms you’ll bump into most — keep this open in a tab for your first week.

Where to look first

Commands you’ll reach for

$ ./gradlew :app:assembleGmsUat   # build the dev variant
$ ./gradlew :app:installGmsUat    # build + install on a device
$ ./gradlew projects              # list every module

Your first week

1. Get access (§08), build & run gmsUat, and log in on UAT.
2. Read just two sections closely: §04 (the one picture) and §14 (MVVM). They unlock the rest.
3. Open Send Money (§19) in the code and follow it: screen → VM → handler → repository.
4. Find the module you’ll work in (§05) and skim its onXxxNavigation().
5. Say hi in the team channels (§22) and grab a small starter ticket.