TopoloMDM

What It Is

TopoloMDM is the device-management cluster for registration, polling, realtime and Firebase wake events, fleet control, operator console workflows, an Android DPC, and an early mobile client scaffold.

Architecture

The repo currently spans a worker/API surface, a browser console, a tenant-scoped realtime event hub, and a mobile scaffold with uneven maturity across those layers.

Runtime Surfaces

Use /systems/topolo-mdm for the current API host and repo inventory.

API Reference

The active route surface centers on device registration, polling, realtime operator events, device command wakeups, Firebase token registration, commands, fleet inspection, admin API-key operations, and operator helper endpoints.

Auth and Permissions

Device registration and polling use public network routes, but enrollment now requires a server-issued one-time enrollment token and continuing device poll/status calls require the issued device credential. Device realtime wakeups and Firebase token registration use the same issued credential and only trigger the existing /poll path. Operator and admin actions rely on Topolo Auth. Protected MDM API bearer-token requests validate through Auth and do not accept locally decoded JWT claims from a Worker secret. Browser console JWTs validate under the console service, while API-key requests remain scoped to the API service. The operator console now uses the shared Topolo cookie-refresh auth client for browser sessions. The operator console browser callback accepts only Auth one-time sso_code handoffs on /auth/callback, delegates exchange to the shared Auth client, and no longer exposes direct-token callback or public SSO debug routes.

Data Ownership

TopoloMDM owns tenant-scoped device state, command queues, realtime fleet-event fanout, operator console state, and related fleet-control records.

Deployments

TopoloMDM deploys as a cluster rather than a single polished product surface: worker API, console, Android DPC, and mobile scaffolding move at different speeds. TopoloProvision QR/R2 APK builds remain the production Android Enterprise enrollment lane. Google Play internal testing builds are available for sales and demo installs, but they run as normal Android demo sessions until a device is enrolled through QR or another Android Enterprise provisioning path. Current Android DPC builds call the live topolo-mdm-api.topolo.app Worker. Firebase Cloud Messaging is a wake channel for enrolled Android devices; commands still come from the authenticated polling endpoint. Installable app catalog metadata is read from the Developers-owned developers.topolo.app/api/apps route, which now includes Topolo Feed, Topolo Provision, and the 22 retained Topolo Mobile Android APKs as R2-backed installable rows served from apk.topolo.app. Topolo Provision and Topolo MDM Mobile are now first-party mobile app records under the Topolo Technology workspace in Developers, while the MDM repo remains the runtime/code owner.

Failure Modes

• mobile or console maturity is overstated compared with the actual repo surface
• Google Play demo installs are mistaken for enrolled device-owner MDM devices
• authenticated control flows are confused with public device registration flows
• realtime command wakeups are treated as command execution instead of a trigger for the authenticated /poll path
• Firebase wake delivery is configured without the matching Android app values or worker service-account secrets
• Developers-owned package-catalog metadata is mistaken for core MDM API ownership
• enrollment QR payloads point at stale TopoloProvision APK URLs, checksums, or expired enrollment tokens
• enrolled devices miss the initial registration call during Android provisioning and only reach the worker through command polling without a valid enrollment token

Debugging

Start with /systems/topolo-mdm, then separate API, console, realtime, Android DPC, Firebase wake, mobile-scaffold, and Developers-owned app-catalog issues before debugging deeper. For QR enrollment failures, verify that the referenced TopoloProvision APK URL returns application/vnd.android.package-archive, that the payload checksum matches the served APK bytes, and that the QR was generated from a fresh authenticated enrollment session. If a Play-installed app is being evaluated, confirm it shows demo mode and do not expect kiosk/device-owner control until QR enrollment. If enrollment completes but the console remains empty, inspect the tenant-scoped TOPOLO_STATE keys and confirm the device either registered through /register or was recovered by the first /poll request with the one-time enrollment token. If command latency is high, verify the worker TENANT_EVENTS binding, operator /events bearer WebSocket, device /device-events X-Device-Secret handshake, and FCM token registration before tuning polling.

Change Log / Verification

• Published TopoloProvision core 1.2.172 to apk.topolo.app and switched MDM enrollment and install-package APK references to that host on 2026-04-23.
• Exposed all 22 retained Topolo Mobile Android APKs to MDM through the Developers-owned /api/apps catalog on 2026-04-23.
• Registered Topolo Provision and Topolo MDM Mobile as first-party Developers mobile app records on 2026-04-23.
• Repointed MDM install-package catalog defaults to the Developers-owned /api/apps catalog on 2026-04-22.
• Hardened MDM enrollment on 2026-04-22 so QR payloads carry server-issued enrollment tokens, registered devices receive per-device credentials, and authenticated debug routes redact device secrets.
• Added Firebase Cloud Messaging wake delivery on 2026-04-22 so enrolled TopoloProvision devices can wake the existing authenticated poll path while backgrounded.
• Migrated MDM API and Android distribution references to TopoloMDM/TopoloProvision naming and the topolo-mdm-api.topolo.app API host on 2026-04-22.
• Added TopoloProvision Google Play internal-testing readiness on 2026-04-22 so sales/demo installs are available without changing the QR enrollment authority.
• Added realtime MDM events on 2026-04-22 so authenticated operator mobile sessions refresh from WebSocket events and enrolled TopoloProvision v1.2.169 devices wake the existing /poll worker as soon as commands are queued.
• Corrected MDM enrollment QR payloads on 2026-04-22 so the console and mobile scaffold reference a live TopoloProvision APK URL with matching file and signature checksums.
• Added first-poll registration recovery on 2026-04-22 so a provisioned device can enter the fleet if Android provisioning interrupted the initial DPC registration call.
• Tightened Android provisioning on 2026-04-22 so the QR waits for DPC policy compliance and the compliance activity registers the device before setup completes.
• Split MDM API validation for browser JWTs and API-service credentials on 2026-04-20 so the authenticated console can load device data without post-login 401 polling.
• Removed the MDM API worker’s residual local JWT_SECRET handoff on 2026-04-18 so protected bearer-token requests validate through Auth.
• Verified on 2026-04-18 that the MDM console browser callback delegates sso_code exchange to the shared Auth client instead of carrying console-local protocol logic
• Verified the MDM console browser callback on 2026-04-17 so it completes sign-in through one-time sso_code exchange and removes public legacy SSO/debug callback routes
• Standardized TopoloMDM console browser auth on the shared Topolo auth client on 2026-03-31
• Added canonical TopoloMDM coverage and retired repo-local MDM docs on 2026-03-30