Initialize Android NTP app framework

2026-07-09 15:44:22 -08:00
commit bfb027fcd2
33 changed files with 1196 additions and 0 deletions
@@ -0,0 +1,17 @@
+# ADR 0001: Native Android local-first app
+
+## Decision
+
+Build v1 as a native Kotlin Android app using Jetpack Compose, Room, and direct UDP NTP probes.
+
+## Rationale
+
+- The app needs low-friction device-side network diagnostics.
+- No backend is required for saved servers, profiles, local history, comparison, or export.
+- Local-only storage avoids telemetry and customer data exposure.
+
+## Consequences
+
+- APKs can be built locally or in Gitea Actions.
+- Gitea runners must have Android build tooling or install it during the workflow.
+- Release builds require signing keys managed through secrets, not committed files.
@@ -0,0 +1,37 @@
+# ADR 0002: Android system time update capability
+
+## Question
+
+Can NTP Check update the Android device system time?
+
+## Finding
+
+For a normal Play/user-installed Android app: **no**. Android protects system clock changes behind privileged APIs/permissions. An app can measure offset and show guidance, but it cannot directly set wall-clock time unless it is installed with elevated trust.
+
+## Practical options
+
+1. **Normal app behavior for v1**
+   - Probe NTP servers.
+   - Show estimated device offset.
+   - Warn when local clock appears wrong.
+   - Provide a button to open Android Date & Time settings.
+   - No special permissions beyond `INTERNET`.
+
+2. **Device-owner / enterprise-managed device**
+   - Some Android management APIs allow a device owner/profile owner to control certain time/timezone policies depending on Android version and ownership mode.
+   - This requires provisioning the app as a device policy controller, not a typical install.
+
+3. **Privileged/system app or custom ROM**
+   - A system-signed or `/system/priv-app` application can use privileged permissions such as `android.permission.SET_TIME`.
+   - This is not available to ordinary APK installs.
+
+4. **Rooted device helper**
+   - A rooted-device mode could call shell commands such as `date`/`toybox date`, but this is out of scope for v1 and has safety/security risks.
+
+## Decision
+
+V1 will not set Android system time. It will remain a diagnostic/comparison tool and may include an "Open Date & Time settings" action. Any future clock-setting mode must be explicitly separate and gated as enterprise/device-owner, privileged-system, or rooted-device functionality.
+
+## Product implication
+
+Market the app as an NTP testing and comparison dashboard, not as a general Android time synchronization daemon.