DEV Community: Peter wang

~40k LOC, Shared 90%: Building a Cross-Platform Shared E-bike Ops App

Peter wang — Tue, 15 Sep 2026 05:32:15 +0000

It's 7 a.m. An ops worker stands by the roadside, facing a row of shared e-bikes parked at odd angles.

The job is concrete: open the app to see which bikes are low on battery, scan to unlock, swap in a fully charged battery, snap a photo to close the task, then move to the next stop. Along the way they might relocate a few illegally parked bikes, handle a user report, or file a repair ticket for a broken unit. Over a full day the app gets opened dozens of times — outdoors, one-handed, sometimes with gloves on.

That's everyday life on the operations side of a shared e-bike business. It isn't glamorous, but it's the ground force that keeps the operation running.

On the engineering side, the question is simpler: do we build all of this twice — once for Android and once for iOS?

Our answer is no. The whole project is roughly 40,000 lines of Kotlin. About 90% lives in a shared layer used by both platforms (measured at 95.8% in source; see §3.5). The rest — roughly 5% per host shell — is what you rewrite when you add another platform. This article walks through how we got there: starting at 81%, pushing through two migration rounds to ~96% shared code, and how each round dismantled the excuses for "this can't move."

Source available: https://github.com/wanghengwen/ebike-go, project under ebike-OpsApp/. Every module and file name in this article maps to the repo. Licensed under Elastic License 2.0 — source-available (self-host, modify, use internally), not OSI open source. The sole restriction: you cannot use it to offer hosted / managed operations services for sale to third parties.

1. First, Understand What Makes This App Hard

When people hear "cross-platform," their first instinct is to pick a framework. But the framework comes last. Step one is weighing the requirements.

We laid out the ~40 screens the ops app needs and counted. The picture turned out cleaner than expected:

Category 1: pure business UI. Login, service-area selection, task lists, task-completion forms, warehouse in/out records, repair-type pickers, permission-driven workbench, my reports… These screens are essentially "forms + lists + state transitions." Interaction patterns are stable and mostly platform-agnostic. This category accounts for more than 80%.

Category 2: must touch native SDKs. Only five areas:

Maps — vehicle pin rendering, clustering, geofences
Bluetooth — near-field vehicle control, BLE radar for finding bikes
Camera / scanning — scan vehicle IDs, scan controller IMEIs
Location — arrival detection, track upload
File upload — completion photos, repair images

That's it. Nothing else.

This "80/20 split" drove every decision afterward. Skip this exercise and you fall into two traps:

Trap 1: build everything natively, twice. Forty form screens on Android, forty again on iOS — double the work, double the bugs, and worst of all business rules diverge. The same "does completion require a photo?" check written twice will eventually disagree. Ops staff can finish a task on Android but not on iOS; debugging that is brutal.

Trap 2: build everything with a cross-platform UI framework. Forms are cheaper, but maps and proprietary BLE SDKs grind you down in interop hell. Proprietary BLE SDKs especially — closed-source, shipped as aar/framework only — can make bridge layers feel endless.

We didn't pick one or the other. We assigned technology by where the hard part actually lives.

2. Choosing a Stack: Four Paths, Why We Took the Fourth

We asked only two questions:

Can business UI be written once?
Can strong platform capabilities be plugged in, instead of being locked to a UI framework?

Running the candidates through those questions:

Approach	Upside	Cost	Verdict
Native UI on each platform	Most direct platform integration	~40 form screens duplicated; business rules fork	❌
Full cross-platform UI (Flutter / RN)	One UI stack	High bridge cost for maps & proprietary BLE; breaks existing Kotlin assets	❌
Shared network layer only, native UI	Easiest to start	Saves the least valuable part; UI still duplicated	❌ Not enough
KMP business core + CMP shared UI + H5 dashboards + platform capabilities as interfaces	Business & UI written once; SDKs swappable; dashboards ship independently	Must draw clear boundaries: shared UI / host / H5	✅

The final split:

What	Owner	Why
Business UI (login, tasks, warehouse, repair, workbench…)	Compose Multiplatform	Stable interaction patterns; Material3 is enough; best ROI, lowest risk
Operations / revenue dashboards	H5 (Vue3)	Different release cadence from field work; needs independent shipping
Maps · Bluetooth · scan · location · upload	Interfaces + expect/actual	Many closed SDKs; permission/compliance differs per platform — define contracts, not implementations
Login, permissions, task state machines, signed requests	KMP shared core	Must not fork; easiest to unit-test

Three sentences:

Share business UI. Interface-ize platform capabilities. Web-ize data dashboards.

The second point deserves expansion. For maps and Bluetooth, the right move isn't "find a cross-platform framework with a built-in map widget." It's define contracts in the shared layer and let hosts fill implementations. An unexpected benefit: without a map key, without a real device, without a proprietary BLE SDK, drop in a simulator — every flow except real vehicle control still runs. Development and demos aren't blocked by hardware. Critical for the open-source drop, since proprietary SDKs can't live in the repo.

3. Final Architecture

3.1 Four Layers, Bottom to Top

Bottom: backend gateway and H5 sites. Network calls hit the business gateway; two dashboard sites are independent Vue3 static deployments.

Third layer: shared, business core, Kotlin Multiplatform. Four areas:

Feature — per-domain state flows and intent functions; exposes state to UI, not repositories
Domain — permission codes, task state machines, vehicle-control policy, validation rules
Data — API definitions, DTOs, mappers, repositories
i18n — string keys and multilingual catalogs

Second layer: sharedUi, main UI, Compose Multiplatform. Login, workbench, tasks, warehouse, repair, report entry screens — all in commonMain, one codebase for both platforms.

Top: two host shells. This layer is easy to misunderstand; worth its own section.

3.2 What the Top "Shell" Actually Is

It is not another UI layer. It's two thin shells — one Android, one iOS. Each does exactly three things:

Job	What it is
Bootstrap	Android `MainActivity` / `OpsApplication`, iOS `OpsAppViewController` — mount shared UI
Implement platform capabilities	Tencent Map view, CameraX preview, foreground location service, permission flows
Inject	Push those implementations into shared-layer contracts via `CompositionLocal`

No business rules and no business UI in the shell. Completion conditions, permission checks, state transitions — not a single line belongs here. That's our hardest line. Android host MainActivity is 62 lines total: the three jobs above, nothing else. Analogy: shared layer is engine and transmission; the shell is bodywork and the ignition key.

3.3 Dependency Direction

Note the cyan dashed line: the shell isn't "calling into" the core. It's filling holes — shared layer defines interfaces; the shell plugs in real SDKs. Reverse that direction and the architecture stops being reusable.

3.4 Module Layout

ebike-OpsApp
├── shared/          # KMP: Feature · Domain · Data · platform contracts · i18n
├── sharedUi/        # Compose Multiplatform: business UI (nav shell, login, 4 tabs, scan screen)
├── androidApp/      # Android host: bootstrap · permissions · SDK adapters (1,639 LOC, no business UI)
├── iosApp/          # iOS host: links SharedUi.framework, 27 lines Swift
├── webH5/           # Vue3: operations dashboard, revenue dashboard
├── config/          # Multi-tenant config (demo only in repo; secrets supplied locally)
└── docs/            # Architecture, migration, i18n, BLE, open-source boundaries

3.5 How We Calculated "Shared ≈ 90%"

No hand-waving — we counted lines (.kt / .swift, excluding tests and blank lines):

Layer	Files	Lines	Shared both platforms
`shared` (business core)	196	22,989	✅
`sharedUi` (CMP UI)	62	14,833	✅
`androidApp` (Android host)	16	1,639	❌
`iosApp` (iOS host, Swift)	2	27	❌
Total	276	39,488	95.8% shared

Also: commonTest 2,571 lines (149 test cases on the shared layer) and webH5 5,070 lines.

Of sharedUi's 14,833 lines, only 246 sit in androidMain / iosMain (WebView body, icon resource mapping, Chinese sorting); the rest is commonMain.

Figures and titles in this article use Shared ≈ 90% / Android ≈ 5% / iOS ≈ 5% as a round illustration: measured shared code is ~95.8%, Android host ~4%. After iOS platform adapters (maps / camera / WebView / HUD) catch up, both host shells should land at similar scale — closer to "90% shared, ~5% thin shell per platform."

3.6 From 81% to 96%: Two Rounds of "Can't Move" Excuses

This section matters on its own — it's the architecture's strongest proof point. The real win isn't two percentage points. It's this: every time we said "this can't move," the blocker wasn't technical. We were missing a contract.

Round 1: 81% → 88%, Map Screens

When we started this article, the Android host had 7,404 lines — far too heavy for a "thin shell." My explanation then: "Any screen embedding a native map view must stay in the host." Sounds reasonable.

We counted file by file. That explanation didn't hold:

Only two files actually embed AndroidView: TencentMapView (321 lines) and ReturnCarScatterMapView (164 lines).
The five "map screens" — task map, relocation map, battery-swap map, vehicle condition distribution, return distribution — had zero Android-specific code: no android.* imports, no Material2, no ui.res.
They lived in the host for one reason: they called those two Composables directly.
More ironic: SimulatorMapView (155 lines) is pure Compose Canvas, using projection and clustering from shared, zero platform deps — it belonged in the shared layer but stayed on Android because it sat in the same folder as Tencent Map.

So the issue wasn't "technically impossible to move." We lacked a cross-platform map container to call.

Filling that gap took a bit over a hundred lines. Same pattern as the repo's proven H5Screen: contract in shared layer, implementation injected by host.

// sharedUi/commonMain — params are all shared-layer types, so the contract lives in commonMain
data class OpsMapSpec(
    val pins: List<MapPin> = emptyList(),
    val selectedCarId: String? = null,
    val fencePolygons: List<FencePolygon> = emptyList(),
    val trackPoints: List<TrackPoint> = emptyList(),
    // Viewport control via incrementing nonce — don't leak SDK camera objects into shared layer
    val fitNonce: Int = 0,
    // …
)

interface OpsMapRenderer {
    @Composable fun Pins(spec: OpsMapSpec, modifier: Modifier)
    // Vendors without scatter support fall back to normal pin map
    @Composable fun Scatter(spec: OpsScatterMapSpec, modifier: Modifier) { /* default impl */ }
}

// Default is pure Compose canvas — runs both sides; host injects real SDK when key is available
val LocalOpsMapRenderer = staticCompositionLocalOf<OpsMapRenderer> { SimulatorMapRenderer }

The host side shrank to 49 lines of glue mapping spec → Tencent Map; we also added LocalOpsToast so UI says "show this message" and the host picks the widget.

After the move:

	Before	After
`sharedUi`	9,779	12,668
`androidApp`	7,404	4,587
Share rate	81.5%	88.5%

Eight screens moved to shared; host slimmed 38%. We also wrote less code: each map screen had duplicated if (isTencent) TencentMapView(…) else SimulatorMapView(…) — six copies gone.

Two details worth noting:

One: after git mv, most files needed no edits. sharedUi and androidApp share the same package prefix. com.luopingtech.ebike.ops.ui.task.ChangeBatteryMapScreen kept its FQN after the move — host imports unchanged. Moving UI across modules that lightly is a dividend from early package planning.

Two: verification is mechanical, not honor-based. After migration, :sharedUi:compileCommonMainKotlinMetadata passing means those eight screens don't sneak platform APIs into commonMain. More reliable than human review saying "looks fine."

Round 2: 88% → 96%, Moving the Nav Shell Too

After round 1 the host still had 4,587 lines; MainActivity alone was 3,108. The excuse: "It's the nav shell — login, four tabs, scan overlay. It needs Activity context; can't move."

Same method, even flimsier excuse. Of 3,108 lines, only these touch the platform:

Platform coupling	Lines	Why in host
`Activity` class itself	27	Truly host-only
Location / notification permission requests	73	`rememberLauncherForActivityResult` is Android
3 camera previews	21	Direct CameraX Composable calls
2× `R.drawable` (torch, manual entry)	4	Direct Android resource IDs
6× `Toast`	12	Direct `android.widget.Toast`

137 lines total. The rest is pure Compose business UI.

We also found 1,063 lines of dead code: 432 lines in MainActivity were old task UI replaced by redesign plus two unused Composables; sharedUi had two old map screens from round 1 that nothing referenced (377 + 254 lines). They compiled but never rendered. Deleted. So the sharedUi delta below is "moved in minus deleted."

Same recipe for new contracts — two this time. Camera preview mirrors OpsMapRenderer:

// sharedUi/commonMain: shared layer only needs "a surface that emits codes"
interface OpsScanPreview {
    @Composable fun Preview(modifier: Modifier, torchOn: Boolean, enabled: Boolean, onCode: (String) -> Unit)
}
// When host has no camera, don't show a black box — say scanning isn't available on this device
val LocalOpsScanPreview = staticCompositionLocalOf<OpsScanPreview> { UnavailableScanPreview }

Permissions were more interesting — they forced a split between business rules and platform flows. Android needs two dialogs (foreground location + notification first, then nudge for "always allow" — combined prompts get rejected); iOS has whenInUse / always tiers — that flow can't be shared. But "once granted, start uploading tracks" is a business rule and must live in shared code. The contract is one question:

// sharedUi/commonMain: null = OK to start upload; String = user-facing denial message
fun interface OpsTrackPermissionGate {
    fun request(onResult: (String?) -> Unit)
}

// Usage in MainShell: who asks for permission doesn't matter; start upload on grant stays in shared layer
LaunchedEffect(homeState.session?.userId) {
    if (homeState.session == null || app.trackUploadFeature.state.value.enabled) return@LaunchedEffect
    trackPermissionGate.request { denied ->
        trackPermissionHint = denied
        if (denied == null) app.trackUploadFeature.setEnabled(true)
    }
}

Then we split MainActivity into seven files under sharedUi/ui/shell/, 2,689 lines total: OpsAppRoot (login / set password / pick service area), MainShell (switching among ~40 full screens), MapTab, TasksTab, AnalysisTab, WorkbenchTab, ScanOverlay.

After the move:

	After round 1	After round 2
`sharedUi`	12,668	14,833
`androidApp`	4,587	1,639
`MainActivity`	3,108	62
Share rate	88.5%	95.8%

The remaining 1,639 host lines are clean: 1,442 lines are platform capability implementations (Tencent Map 534 · camera scan 358 · location & foreground service 262 · permission flow 82 · photo capture 107 · upload 67 · reverse geocode 32), 197 lines bootstrap & injection (OpsApplication 135 + MainActivity 62).

MainActivity now — that's all of it:

setContent {
    OpsTheme(branding = app.config.branding) {
        CompositionLocalProvider(
            LocalOpsMapRenderer provides opsMapRendererFor(app),
            LocalOpsScanPreview provides AndroidScanPreview,
            LocalOpsTrackPermissionGate provides rememberTrackPermissionGate(app),
            LocalOpsToast provides { msg: String -> Toast.makeText(this, msg, Toast.LENGTH_SHORT).show() },
        ) {
            Surface(modifier = Modifier.fillMaxSize()) { OpsAppRoot(app) }   // all UI in shared layer
        }
    }
}

Interestingly, after round 1 we estimated "truly non-movable platform code ~1,400 lines." Actual count: 1,442. That match suggests "what must stay in the host" can be estimated upfront — you don't need gut feel.

What This Round Means for iOS

This is the point. After the move, "what does the iOS host do?" became a ** countable checklist**: one entry function plus four injection points.

// sharedUi/iosMain — same job as Android setContent
fun OpsAppViewController(app: OpsApp): UIViewController = ComposeUIViewController {
    OpsTheme(branding = app.config.branding) {
        Surface(modifier = Modifier.fillMaxSize()) { OpsAppRoot(app) }
    }
}

Swift side: 27 lines, one UIViewControllerRepresentable, done. Not a single screen rewritten in SwiftUI. SharedUi.framework export(project(":shared")), so import SharedUi brings OpsApp along — link one framework.

More important: unfilled holes don't block bootstrapping. No camera → "this host has no camera"; no map → shared Canvas renderer; H5 screen → placeholder. iOS todo went from "rewrite ~40 Android screens" to four concrete items: AVFoundation preview, map renderer, WKWebView, HUD. Those four should land near Android's 1,442-line host scale.

3.7 Interface-ized Capability Inventory

Shared core knows capabilities, not vendors:

Contract	Role	Implemented by
`MapCapability`	Whether map is ready, which vendor	Tenant config + key
`OpsMapRenderer`	Pin / scatter maps	Tencent Map / shared Canvas
`BleTransport`	Near-field control, BLE radar	Proprietary BLE SDK / simulator
`CodeScanner`	Standalone scan page, one code	CameraX + ML Kit
`OpsScanPreview`	In-page camera preview	CameraX / iOS AVFoundation TBD
`LocationTracker`	Arrival check, track upload, vehicle re-location	System location
`OpsTrackPermissionGate`	Ask "can we start uploading now?"	Per-platform permission UI
`MediaUploader`	Completion photos, repair images	Multipart upload / demo stub
`PlatformWebView`	WebView body for H5 screens	Android WebView / iOS `WKWebView` TBD
`LocalOpsToast`	One-shot lightweight toast	Android Toast / iOS HUD

Business layer uses these for "scan once, upload a photo, beep" — UI only binds state: loading, error copy, button enabled.

Pattern: contract parameters must not include vendor types. OpsMapRenderer lives in commonMain because it takes MapPin, FencePolygon, etc. Even "zoom in one level" is an incrementing zoomInNonce, not an SDK camera object. One LatLng in the signature breaks the layer.

Side note on vehicle control: VehicleControlPolicy falls back to network commands when BLE is unavailable. Rule lives in shared — both platforms behave the same. Write it twice and "when to fall back" almost certainly diverges.

3.8 Embedding H5 in CMP

sharedUi has cross-platform H5Screen: common layer handles title, load-failure retry, back stack; PlatformWebView in androidMain / iosMain (back-key semantics differ — implement separately). Dashboard URLs built from tenant config + login session — field app and data dashboards ship independently.

4. i18n: Change Once, Both Platforms Update

Ops apps often serve domestic and overseas tenants — i18n isn't optional.

We didn't scatter strings across strings.xml and Localizable.strings — one new sentence, two files, no compile-time guard for misses. Instead: type-safe keys + multilingual catalogs in the shared layer; UI and network share one resolver.

4.1 End-to-End Chain

Str (enum keys — missing keys caught at compile / in tests)
   │
   ▼
StringCatalogs (ZH_CN / EN maps)
   │
   ▼
OpsI18n.t(key, args…)
   │
   ├── Strings global delegate → Feature / Repository get copy without Compose
   └── LocaleContext.acceptLanguage → HTTP Accept-Language header

Business layer uses the same Strings.t(). Toasts, API error mapping, demo fake data stay language-consistent with UI — no "English UI, Chinese errors." A test guards it: every Str key must exist in both ZH and EN catalogs.

4.2 The Moment Language Switches

User taps English in settings:

OpsI18n.setLanguage(...) updates in-memory language
Write to SecureStore (persist choice)
Update LocaleContext.acceptLanguage (next request carries new language)
Strings.install(this) — process-wide resolver points at new catalog
UI collectAsState(languageFlow) — copy refreshes immediately

No app restart. No re-navigation.

4.3 Default Language: Follow System

First launch follows device language; after manual choice, user wins forever. Two priorities only:

val lang = when {
    !stored.isNullOrBlank() -> OpsLanguage.fromTag(stored)          // user chose — user wins
    else -> OpsLanguage.fromSystemLanguage(systemLanguage ?: platformLanguageTag())
}

Reading device language is itself expect/actual — another "interface-ize platform capability" exercise:

// commonMain
expect fun platformLanguageTag(): String?

// androidMain
actual fun platformLanguageTag(): String? = Locale.getDefault().toLanguageTag()

// iosMain
actual fun platformLanguageTag(): String? = NSLocale.preferredLanguages.firstOrNull() as? String

4.4 Adding a New Language

Add enum entry and acceptLanguage on OpsLanguage
Add full catalog in StringCatalogs
Add option on settings language list
(Optional) Append lang to H5 dashboard URLs

No Android / iOS resource files to touch — UI already consumes shared t(). That's "change once, both platforms update."

Easily overlooked: login country codes. Going overseas means international phone numbers — built-in calling-codes catalog and picker; submit normalized as +{code}-{number}. Independent from UI language, same "going global" bundle.

5. What's Shipped So Far

Architecture done — here's what actually runs on it.

Account & field prep: password / SMS login, multi-tenant branch selection, service-area picker, permission-code-driven workbench entries, EN/ZH switch, international dialing codes.

Find & control vehicles: list and map, ops-state and alarm filters, scan parsing, lock/unlock, ring, battery compartment open/close (network or BLE per policy), battery SN binding, vehicle re-location.

Tasks & work orders: battery swap / relocation / inspection / repair — claim, execute, photo completion, review results; self-service relocation and batch manual relocation; legacy inspection/repair ledgers (list, claim, complete).

Repair & reports: configurable repair types, out-of-service option, photo submit, my report history; user reports with last-order validation, multi-select types, optional photos, pending revoke.

Warehouse & production: coded / codeless in-out scanning and records, vehicle inspection, controller bind/unbind, shelf up/down, unlocked-vehicle checks, BLE radar find, ops track upload.

Data dashboards: one tap from workbench to operations / revenue H5.

Extra win: behavior alignment. Legacy rules hid in details: which status code defines "low battery," whether "all" includes sold-out bikes, offline alarms via alarmState vs connection state, 200 m gate on relocation completion, max repair plate length… We aligned each rule in shared code with tests. Rules exist once — no "Android correct, iOS wrong."

6. Want to Run It?

Repo: https://github.com/wanghengwen/ebike-go, directory ebike-OpsApp/.

cd ebike-OpsApp
# JDK 17 or 21 (25 breaks — current Gradle Kotlin DSL can't parse it)
# Windows / Linux: shared-layer check + tests + Android APK
gradlew.bat :sharedUi:compileCommonMainKotlinMetadata :shared:testAndroidHostTest :androidApp:assembleDebug

# macOS can also link iOS framework (unverified by us — see §6)
# ./gradlew :sharedUi:linkDebugFrameworkIosSimulatorArm64 && cd iosApp && xcodegen generate

Quick start:

Open ebike-OpsApp in Android Studio, run androidApp Debug.
No backend required: empty api.baseUrl → Demo mode — login, tasks, warehouse, repair on local fake data, including simulated BLE ring. For real gateway, copy androidApp/src/main/assets/tenant.json.example, fill URL and secrets (file is gitignored).
Map key in local local.properties, not in VCS.
Multi-tenant config in config/{tenant}_{mode}.json; only demo checked in.

How We Use Go for Device Connectivity and Geofencing in a Shared E-Bike Platform

Peter wang — Mon, 14 Sep 2026 09:30:09 +0000

I’d like to share ebike-go, a source-available collection of Go services for shared e-bike and pedal-assist bike operations:

https://github.com/wanghengwen/ebike-go

The project grew from real operational requirements for city bike-sharing programs and tourist attractions. From a rider’s perspective, the process is simple: scan, unlock, ride, and return. On the backend, however, every trip involves live device connections, location updates, parking validation, helmet checks, pricing, promotions, payments, and operational reporting.

This type of system has turned out to be a good match for Go.

Where Go fits in a shared e-bike system

1. Maintaining connections with a large number of bikes

Each bike has an IoT controller that reports information such as:

GPS location
Battery level and BMS data
Lock and riding status
Faults and alarms
Smart helmet status

The backend also needs to send commands for unlocking, locking, powering the bike, finding a bike, or opening the battery compartment.

In ebike-go, the device gateway is implemented as a separate Go service. Go’s lightweight goroutines and networking support make it practical to manage many long-lived device connections without requiring a complicated threading model.

Device messages can arrive through TCP or MQTT. After protocol decoding, events are passed through Kafka to consumer and worker services. Redis is used for frequently accessed device state, while business events continue to the order and operations services.

The simplified flow looks like this:

Bike / IoT controller
        |
     TCP or MQTT
        |
Go device gateway and protocol decoder
        |
      Kafka
        |
Go consumers and workers
        |
Redis, MySQL, and business services

This separation keeps connection handling and binary protocol decoding away from slower business operations.

2. Processing bursts of device events

Bike traffic is not evenly distributed. Morning commutes, tourist opening hours, promotions, and large return events can create sudden traffic spikes.

Go works well here because the services can process independent messages concurrently while keeping the code relatively straightforward. Device ingestion, command delivery, state updates, and asynchronous tasks are split into independently deployable services, so the busiest part can be scaled without scaling the entire platform.

Kafka provides buffering between live device traffic and downstream processing. This is important when bikes continue reporting data while a database or business service is temporarily slow.

3. Fast geofencing during unlock and return

Parking is one of the hardest operational problems in shared mobility.

Before unlocking or returning a bike, the platform may need to determine whether the current location is:

Inside the service area
Inside an approved parking zone
Inside a no-parking or no-riding area
Close enough to a designated station

These checks happen on the user-facing path, so latency matters. The geofencing service is written in Go and kept separate from general business APIs. This lets us optimize and scale geometry-heavy checks independently.

GPS alone is not always accurate enough. The business flow can also combine geofencing with Bluetooth beacons or RFID tags to confirm that a bike is parked in the correct place.

4. Keeping business domains independent

The repository is organized as multiple Go modules rather than one large application. The main service areas include:

API gateway and authentication
Customer and operator APIs
Device gateway and protocol handling
Device state consumers and background workers
Geofencing
Order, pricing, and promotion integration
Operational analytics
Notifications
Open APIs for external systems

Most HTTP services use Gin. The supporting infrastructure includes Nacos, Redis, Kafka, MySQL, Docker, and Kubernetes.

Using multiple services does add deployment and observability work, so this structure is not intended as a recommendation for every Go project. In this case, the boundaries follow workloads that behave differently: long-lived connections, CPU-heavy geofencing, user-facing APIs, and asynchronous event processing.

5. Building small deployment units

Go’s static binaries and relatively fast startup are useful for containerized deployment. Each service can be built, deployed, restarted, and scaled independently.

This is particularly helpful for shared mobility, where traffic varies by region and time of day. A device gateway may need more capacity during a fleet rollout, while customer-facing APIs may peak during commuting hours.

Business capabilities built on top

The Go services support more than bike connectivity. The platform also covers:

The complete scan, unlock, ride, and return process
GPS geofences, Bluetooth parking beacons, and RFID parking points
Smart helmet pairing, status checks, and return rules
Configurable fares for different regions and vehicle types
Ride passes, coupons, memberships, referrals, and promotional campaigns
Multi-tenant operations
Merchant accounts, revenue-sharing records, refunds, and revenue reports

The goal is to provide a practical foundation for organizations operating their own shared e-bike service, while keeping device communication and operational rules under their control.

What I’d like feedback on

I’m especially interested in hearing from Go developers who have worked on IoT, mobility, or real-time systems:

How do you structure connection ownership and command delivery across multiple gateway instances?
Which approaches have worked well for high-frequency geospatial checks in Go?
Where would you draw service boundaries in a system that combines IoT traffic and transactional business flows?
Which parts of this project would be most useful to document or provide as standalone examples?

Issues and pull requests are welcome, especially for bug fixes, documentation, observability, and clean example configurations.

Repository: https://github.com/wanghengwen/ebike-go