secondly-com/openphone

1. What this repo is

OpenPhone is not a standalone app repo; it is the OpenPhone-owned control plane for an Android-based phone OS. It contains the Android overlay, privileged assistant app, framework patches, build/release tooling, schemas, and a reference model-broker service. The actual Android source tree is not vendored here; this repo is applied on top of LineageOS 23.2 / Android 16.

2. Top-level architecture

The system is split into four main layers: OpenPhone UI/surface, the privileged assistant runtime, OS-level services/patches, and external model infrastructure. The user interacts with the OpenPhone surface; the assistant turns that into mediated actions; framework services expose device state and execution capabilities; model services provide reasoning, transcription, and realtime voice.

3. Android integration boundary

The overlay/ directory holds the packaged OpenPhone app, resources, and prebuilts that get copied into the Android tree. The patches/ directory modifies upstream AOSP/LineageOS components such as frameworks_base, SystemUI, Settings, system_sepolicy, and build tooling. This is where OpenPhone becomes a system product rather than an app layered on top of stock Android.

4. Privileged assistant runtime

overlay/packages/apps/OpenPhoneAssistant/ is the core app. It is a privileged system component with Compose-based UI (MainActivity, AssistantComposeHost, chat and advanced screens), an AIDL interface, and both Java/Kotlin services. It owns the orchestrator, model adapters, tool execution, policy checks, memory, commitments, watchers, jobs, and audit/export logic.

5. User-facing surfaces

The assistant is exposed through several OS entry points rather than only a launcher icon: an always-available system surface, a Quick Settings tile, a boot receiver, a trigger receiver, a notification listener, and an accessibility service. There is also a pointer overlay/controller for mediated interaction on top of other apps. These surfaces are how the assistant can stay present, be re-entered, and act while the user remains in the phone context.

6. Action execution and OS mediation

Actions are not executed directly against apps from the model layer. They pass through OpenPhone’s action registry/catalog, task registry, framework tool executor, and OS-owned services introduced by platform patches. The framework side includes services such as openphone_agent, openphone_context, and openphone_assistant_data, plus mediated input, screenshot, UI-tree, clipboard, and URL/opening flows. This is the main trust boundary between the assistant and the device.

7. Model and voice layer

The model abstraction is centralized under src/.../model/. It supports multiple backends: Gemini Live voice sessions, OpenAI Realtime voice sessions, OpenAI Responses agent mode, speech transcription, and a local heuristic adapter for fallback or validation. A separate reference Python service in services/model-broker/ brokers model connectivity and deployment, so the assistant can talk to external providers without hardcoding provider-specific access into the app.

8. Context, memory, and proactive automation

The runtime keeps state across turns through several stores: context events/index, memory records, commitments, jobs, watchers, and trajectories. The orchestrator and job scheduler enable background runs, heartbeats, and exact scheduled workflows. Watchers monitor phone state such as notifications, calls, app foreground state, visible screen state, battery, connectivity, and commitments so the assistant can react proactively, not just conversationally.

9. Policy, approvals, and auditability

OpenPhone’s safety model is a first-class subsystem. The policy engine evaluates capabilities and risk, confirmations gate sensitive actions, and audit logging records decisions and evidence. The app also exports trajectories and audit evidence, and the repo includes schemas for action requests/results, audit logs, trajectory events, screen context, and model tools. This makes the system inspectable and reviewable after the fact.

10. Device and platform scope

The first supported target is Pixel 9a (tegu), with generic ARM64 builds used mainly for graph validation. Device notes, bootchain docs, and support matrices live under docs/devices/ and docs/TEGU_BOOTCHAIN.md. The repo also contains Android product manifests for the OpenPhone target and scripts for flashing, device checks, and hardware validation.

11. Build, sync, and release pipeline

scripts/ drives the lifecycle: syncing the Android tree, applying patches, building products, pushing the assistant APK, flashing devices, and running validation/evals. GitHub Actions cover CI, eval, and release workflows. Release artifacts, OTA feeds, and manifests are generated and validated by dedicated scripts and JSON schemas, which indicates a controlled, reproducible release process rather than ad hoc builds.

12. What to draw in an architecture diagram

The key diagram boundaries are: user inputs → OpenPhone surface; surface → privileged assistant; assistant ↔ model broker/external models; assistant ↔ OS services/framework patches; OS services ↔ device context/apps; and assistant/policy ↔ audit/trajectory exports. A separate box should represent the repo’s build/release/tooling plane, because it assembles and validates the system but is not part of runtime execution.