# friedjof/jev-mobile architecture

> Architecture diagram of the GitHub repository friedjof/jev-mobile, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/friedjof/jev-mobile
- Repository: https://github.com/friedjof/jev-mobile

## Overview

jev-mobile is a durable Android sub-agent: clients submit high-level tasks, which are persisted and claimed by a single worker. The worker delegates execution to the mobile agent, whose documented loop observes and normalizes UI state, evaluates task requirements, asks a decision provider to choose from valid actions, journals and executes mutations, then verifies observable results. The graph also preserves durable task operations, information and clarification paths, safety recovery, tracing, and the documented Android backends. Evidence is limited to the README and the supplied source excerpts/index; uncertain internal wiring is omitted.

Main entry points: [`src/jev_mobile/agent/mobile_agent.py`](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/agent/mobile_agent.py) (Mobile agent), [`src/jev_mobile/task_store.py`](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/task_store.py) (SQLite task store), [`src/jev_mobile/runtime/worker.py`](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/runtime/worker.py) (Durable worker), [`src/jev_mobile/actions/mutation_engine.py`](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/actions/mutation_engine.py) (Mutation transaction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_delegation["Task delegation"]
  node_cli["CLI and task API<br/>[cli.py]"]
  node_mcp["MCP delegation<br/>[mcp_server.py]"]
  node_task_model["Task semantics<br/>[tasks.py]"]
end

subgraph group_execution["Agent execution"]
  node_agent["Mobile agent<br/>[mobile_agent.py]"]
  node_normalizer["UI normalization<br/>[normalize.py]"]
  node_state["Semantic UI state<br/>[models.py]"]
  node_mutations["Mutation transaction<br/>[mutation_engine.py]"]
  node_verify["Persistence verification<br/>[mobile_agent.py]"]
  node_escalation["Risk escalation<br/>[handler.py]"]
end

subgraph group_decision["Requirements and decisions"]
  node_requirements["Requirements evaluation<br/>[evaluator.py]"]
  node_generators["Requirement generation<br/>[generators.py]"]
  node_actions["Valid action catalog<br/>[builder.py]"]
  node_provider["Jev decision provider<br/>[jev.py]"]
  node_information["Information tasks<br/>[information.py]"]
end

subgraph group_device["Device integration"]
  node_device_adapter["Device adapter<br/>[adapter.py]"]
  node_portal["Portal ADB backend<br/>[portal_adb.py]"]
  node_bridge["Android accessibility bridge"]
end

subgraph group_operations["Durability and operations"]
  node_task_store[("SQLite task store<br/>[task_store.py]")]
  node_worker["Durable worker<br/>[worker.py]"]
  node_journal[("Mutation journal")]
  node_trace["JSONL traces<br/>[trace.py]"]
  node_readiness["Worker readiness<br/>[readiness.py]"]
end

node_operator(("Task requester"))

node_operator -->|"submits task"| node_cli
node_operator -->|"delegates task"| node_mcp
node_cli -->|"persists request"| node_task_store
node_mcp -->|"delegates tasks"| node_task_store
node_task_model -->|"defines task data"| node_task_store
node_worker -->|"claims task"| node_task_store
node_worker -->|"runs task"| node_agent
node_worker -->|"checks readiness"| node_readiness
node_agent -->|"normalizes snapshots"| node_normalizer
node_normalizer -->|"produces state"| node_state
node_agent -->|"evaluates progress"| node_requirements
node_generators -->|"interprets goal"| node_task_model
node_agent -->|"builds candidates"| node_actions
node_agent -->|"requests decision"| node_provider
node_provider -->|"reads semantics"| node_state
node_agent -->|"executes action"| node_mutations
node_mutations -->|"journals intent"| node_journal
node_mutations -->|"dispatches mutation"| node_device_adapter
node_agent -->|"verifies result"| node_verify
node_device_adapter -.->|"selects backend"| node_portal
node_device_adapter -.->|"uses USB tunnel"| node_bridge
node_agent -.->|"handles risk"| node_escalation
node_agent -.->|"supports read tasks"| node_information
node_agent -->|"records progress"| node_task_store
node_agent -->|"writes trace"| node_trace

click node_cli "https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/cli.py"
click node_mcp "https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/mcp_server.py"
click node_task_model "https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/tasks.py"
click node_task_store "https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/task_store.py"
click node_worker "https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/runtime/worker.py"
click node_agent "https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/agent/mobile_agent.py"
click node_normalizer "https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/state/normalize.py"
click node_state "https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/state/models.py"
click node_requirements "https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/requirements/evaluator.py"
click node_generators "https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/requirements/generators.py"
click node_actions "https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/actions/builder.py"
click node_provider "https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/providers/jev.py"
click node_mutations "https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/actions/mutation_engine.py"
click node_journal "https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/actions/mutation_journal.py"
click node_verify "https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/agent/mobile_agent.py"
click node_device_adapter "https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/device/adapter.py"
click node_portal "https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/device/portal_adb.py"
click node_bridge "https://github.com/friedjof/jev-mobile/blob/main/android/jev-mobile-bridge/app/src/main/java/io/jev/mobile/bridge/JevAccessibilityService.kt"
click node_escalation "https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/escalation/handler.py"
click node_information "https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/requirements/information.py"
click node_trace "https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/tracing/trace.py"
click node_readiness "https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/runtime/readiness.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_mcp,node_task_model toneBlue
class node_agent,node_normalizer,node_state,node_mutations,node_verify,node_escalation toneAmber
class node_requirements,node_generators,node_actions,node_provider,node_information toneMint
class node_device_adapter,node_portal,node_bridge,node_operator toneRose
class node_task_store,node_worker,node_journal,node_trace,node_readiness toneIndigo
```

## Components

### Task delegation

- [CLI and task API](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/cli.py): `src/jev_mobile/cli.py`
- [MCP delegation](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/mcp_server.py): `src/jev_mobile/mcp_server.py`
- [Task semantics](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/tasks.py): `src/jev_mobile/tasks.py`

### Agent execution

- [Mobile agent](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/agent/mobile_agent.py): `src/jev_mobile/agent/mobile_agent.py`
- [UI normalization](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/state/normalize.py): `src/jev_mobile/state/normalize.py`
- [Semantic UI state](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/state/models.py): `src/jev_mobile/state/models.py`
- [Mutation transaction](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/actions/mutation_engine.py): `src/jev_mobile/actions/mutation_engine.py`
- [Persistence verification](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/agent/mobile_agent.py): `src/jev_mobile/agent/mobile_agent.py`
- [Risk escalation](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/escalation/handler.py): `src/jev_mobile/escalation/handler.py`

### Requirements and decisions

- [Requirements evaluation](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/requirements/evaluator.py): `src/jev_mobile/requirements/evaluator.py`
- [Requirement generation](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/requirements/generators.py): `src/jev_mobile/requirements/generators.py`
- [Valid action catalog](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/actions/builder.py): `src/jev_mobile/actions/builder.py`
- [Jev decision provider](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/providers/jev.py): `src/jev_mobile/providers/jev.py`
- [Information tasks](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/requirements/information.py): `src/jev_mobile/requirements/information.py`

### Device integration

- [Device adapter](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/device/adapter.py): `src/jev_mobile/device/adapter.py`
- [Portal ADB backend](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/device/portal_adb.py): `src/jev_mobile/device/portal_adb.py`
- [Android accessibility bridge](https://github.com/friedjof/jev-mobile/blob/main/android/jev-mobile-bridge/app/src/main/java/io/jev/mobile/bridge/JevAccessibilityService.kt): `android/jev-mobile-bridge/app/src/main/java/io/jev/mobile/bridge/JevAccessibilityService.kt`

### Durability and operations

- [SQLite task store](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/task_store.py): `src/jev_mobile/task_store.py`
- [Durable worker](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/runtime/worker.py): `src/jev_mobile/runtime/worker.py`
- [Mutation journal](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/actions/mutation_journal.py): `src/jev_mobile/actions/mutation_journal.py`
- [JSONL traces](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/tracing/trace.py): `src/jev_mobile/tracing/trace.py`
- [Worker readiness](https://github.com/friedjof/jev-mobile/blob/main/src/jev_mobile/runtime/readiness.py): `src/jev_mobile/runtime/readiness.py`

### Other components

- **Task requester**

## Connections

- Task requester → CLI and task API: submits task (evidence: `README.md`)
- Task requester → MCP delegation: delegates task (evidence: `README.md`)
- CLI and task API → SQLite task store: persists request (evidence: `README.md`)
- MCP delegation → SQLite task store: delegates tasks (evidence: `src/jev_mobile/mcp_server.py`)
- Task semantics → SQLite task store: defines task data (evidence: `src/jev_mobile/task_store.py`)
- Durable worker → SQLite task store: claims task (evidence: `src/jev_mobile/runtime/worker.py`)
- Durable worker → Mobile agent: runs task (evidence: `src/jev_mobile/runtime/worker.py`)
- Durable worker → Worker readiness: checks readiness (evidence: `README.md`)
- Mobile agent → UI normalization: normalizes snapshots (evidence: `src/jev_mobile/agent/mobile_agent.py`)
- UI normalization → Semantic UI state: produces state (evidence: `src/jev_mobile/state/normalize.py`)
- Mobile agent → Requirements evaluation: evaluates progress (evidence: `src/jev_mobile/agent/mobile_agent.py`)
- Requirement generation → Task semantics: interprets goal (evidence: `src/jev_mobile/requirements/generators.py`)
- Mobile agent → Valid action catalog: builds candidates (evidence: `src/jev_mobile/agent/mobile_agent.py`)
- Mobile agent → Jev decision provider: requests decision (evidence: `README.md`)
- Jev decision provider → Semantic UI state: reads semantics (evidence: `src/jev_mobile/providers/jev.py`)
- Mobile agent → Mutation transaction: executes action (evidence: `src/jev_mobile/agent/mobile_agent.py`)
- Mutation transaction → Mutation journal: journals intent (evidence: `src/jev_mobile/actions/mutation_engine.py`)
- Mutation transaction → Device adapter: dispatches mutation (evidence: `src/jev_mobile/actions/mutation_engine.py`)
- Mobile agent → Persistence verification: verifies result (evidence: `README.md`)
- Device adapter → Portal ADB backend: selects backend
- Device adapter → Android accessibility bridge: uses USB tunnel (evidence: `README.md`)
- Mobile agent → Risk escalation: handles risk (evidence: `README.md`)
- Mobile agent → Information tasks: supports read tasks (evidence: `README.md`)
- Mobile agent → SQLite task store: records progress (evidence: `src/jev_mobile/agent/mobile_agent.py`)
- Mobile agent → JSONL traces: writes trace (evidence: `src/jev_mobile/agent/mobile_agent.py`)