# dougsong/jev-android architecture

> Architecture diagram of the GitHub repository dougsong/jev-android, 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/dougsong/jev-android
- Repository: https://github.com/dougsong/jev-android

## Overview

jev-android is an Android UI-agent SDK: a host supplies a task and provider, the agent observes accessible controls, requests a decision, applies policy and freshness guards, executes an allowed action, then observes its effect. Jev and DeepSeek are alternative decision backends; Android accessibility performs the UI work. The sample provides provider/scenario selection and a local test screen. Some sample and runtime details are documented but not excerpted, so those links rely on the README; unsampled internals are not inferred.

Main entry points: [`core/src/main/kotlin/io/github/jevandroid/core/JevAgent.kt`](https://github.com/dougsong/jev-android/blob/main/core/src/main/kotlin/io/github/jevandroid/core/JevAgent.kt) (Execution loop), [`sample/src/main/kotlin/io/github/jevandroid/sample/MainActivity.kt`](https://github.com/dougsong/jev-android/blob/main/sample/src/main/kotlin/io/github/jevandroid/sample/MainActivity.kt) (Sample interface), [`sdk/src/main/kotlin/io/github/jevandroid/AccessibilityRuntime.kt`](https://github.com/dougsong/jev-android/blob/main/sdk/src/main/kotlin/io/github/jevandroid/AccessibilityRuntime.kt) (UI observation and actions), [`sdk/src/main/kotlin/io/github/jevandroid/DeepSeekProvider.kt`](https://github.com/dougsong/jev-android/blob/main/sdk/src/main/kotlin/io/github/jevandroid/DeepSeekProvider.kt) (DeepSeek provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sample["Sample app"]
  node_main["Sample interface<br/>[MainActivity.kt]"]
  node_selection["Provider selection"]
  node_scenarios["Task scenarios<br/>[TaskScenarios.kt]"]
  node_formatter["Event formatter"]
  node_policy["Bilibili policy"]
  node_fixture["Local test screen<br/>[FixtureActivity.kt]"]
end

subgraph group_core["Agent core"]
  node_models["Task and event models<br/>[Models.kt]"]
  node_agent["Execution loop<br/>[JevAgent.kt]"]
  node_progress["Progress tracking<br/>[ProgressTracker.kt]"]
  node_verifier["Outcome verifier<br/>[Models.kt]"]
end

subgraph group_runtime["Accessibility runtime"]
  node_service["Accessibility service"]
  node_accessibility["UI observation and actions"]
  node_fingerprints["Snapshot fingerprints"]
  node_press["Long-press geometry<br/>[LongPressTarget.kt]"]
end

subgraph group_providers["Decision providers"]
  node_jev["Jev provider<br/>[JevProvider.kt]"]
  node_deepseek["DeepSeek provider"]
  node_choices["Action catalog<br/>[DeepSeekChoices.kt]"]
  node_providerprogress["Provider progress context"]
  node_transport["HTTP transport"]
end

node_user(("User"))
node_host["Host Android app"]
node_jevservice["Jev API"]
node_deepseekapi["DeepSeek API"]
node_android["Android accessibility"]

node_user -->|"configures task"| node_main
node_main -->|"selects provider"| node_selection
node_main -->|"chooses scenario"| node_scenarios
node_main -->|"opens test screen"| node_fixture
node_main -->|"formats result logs"| node_formatter
node_main -.->|"uses optional policy"| node_policy
node_host -->|"starts task"| node_service
node_service -->|"runs"| node_agent
node_service -->|"constructs runtime"| node_accessibility
node_agent -->|"observes and executes"| node_accessibility
node_agent -->|"requests decision"| node_jev
node_agent -->|"requests decision"| node_deepseek
node_agent -->|"tracks effects"| node_progress
node_agent -->|"checks completion"| node_verifier
node_agent -->|"uses task and decisions"| node_models
node_agent -->|"dispatches actions"| node_android
node_accessibility -->|"checks freshness"| node_fingerprints
node_accessibility -->|"computes press target"| node_press
node_jev -->|"sends request"| node_transport
node_transport -->|"sends HTTP request"| node_jevservice
node_deepseek -->|"builds action choices"| node_choices
node_deepseek -->|"encodes progress"| node_providerprogress
node_deepseek -->|"sends request"| node_transport
node_transport -->|"sends HTTP request"| node_deepseekapi
node_jev -->|"encodes progress"| node_providerprogress
node_accessibility -->|"uses accessibility APIs"| node_android

click node_main "https://github.com/dougsong/jev-android/blob/main/sample/src/main/kotlin/io/github/jevandroid/sample/MainActivity.kt"
click node_selection "https://github.com/dougsong/jev-android/blob/main/sample/src/main/kotlin/io/github/jevandroid/sample/ProviderSelection.kt"
click node_scenarios "https://github.com/dougsong/jev-android/blob/main/sample/src/main/kotlin/io/github/jevandroid/sample/TaskScenarios.kt"
click node_formatter "https://github.com/dougsong/jev-android/blob/main/sample/src/main/kotlin/io/github/jevandroid/sample/AgentEventFormatter.kt"
click node_policy "https://github.com/dougsong/jev-android/blob/main/sample/src/main/kotlin/io/github/jevandroid/sample/BilibiliTriplePolicy.kt"
click node_fixture "https://github.com/dougsong/jev-android/blob/main/sample/src/main/kotlin/io/github/jevandroid/sample/FixtureActivity.kt"
click node_models "https://github.com/dougsong/jev-android/blob/main/core/src/main/kotlin/io/github/jevandroid/core/Models.kt"
click node_agent "https://github.com/dougsong/jev-android/blob/main/core/src/main/kotlin/io/github/jevandroid/core/JevAgent.kt"
click node_progress "https://github.com/dougsong/jev-android/blob/main/core/src/main/kotlin/io/github/jevandroid/core/ProgressTracker.kt"
click node_verifier "https://github.com/dougsong/jev-android/blob/main/core/src/main/kotlin/io/github/jevandroid/core/Models.kt"
click node_service "https://github.com/dougsong/jev-android/blob/main/sdk/src/main/kotlin/io/github/jevandroid/JevAccessibilityService.kt"
click node_accessibility "https://github.com/dougsong/jev-android/blob/main/sdk/src/main/kotlin/io/github/jevandroid/AccessibilityRuntime.kt"
click node_fingerprints "https://github.com/dougsong/jev-android/blob/main/sdk/src/main/kotlin/io/github/jevandroid/SnapshotFingerprints.kt"
click node_press "https://github.com/dougsong/jev-android/blob/main/sdk/src/main/kotlin/io/github/jevandroid/LongPressTarget.kt"
click node_jev "https://github.com/dougsong/jev-android/blob/main/sdk/src/main/kotlin/io/github/jevandroid/JevProvider.kt"
click node_deepseek "https://github.com/dougsong/jev-android/blob/main/sdk/src/main/kotlin/io/github/jevandroid/DeepSeekProvider.kt"
click node_choices "https://github.com/dougsong/jev-android/blob/main/sdk/src/main/kotlin/io/github/jevandroid/DeepSeekChoices.kt"
click node_providerprogress "https://github.com/dougsong/jev-android/blob/main/sdk/src/main/kotlin/io/github/jevandroid/ProviderProgress.kt"
click node_transport "https://github.com/dougsong/jev-android/blob/main/sdk/src/main/kotlin/io/github/jevandroid/ProviderTransport.kt"

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_main,node_selection,node_scenarios,node_formatter,node_policy,node_fixture,node_user toneBlue
class node_models,node_agent,node_progress,node_verifier toneAmber
class node_service,node_accessibility,node_fingerprints,node_press,node_jevservice,node_deepseekapi toneMint
class node_jev,node_deepseek,node_choices,node_providerprogress,node_transport toneRose
class node_host,node_android toneIndigo
```

## Components

### Sample app

- [Sample interface](https://github.com/dougsong/jev-android/blob/main/sample/src/main/kotlin/io/github/jevandroid/sample/MainActivity.kt): `sample/src/main/kotlin/io/github/jevandroid/sample/MainActivity.kt`
- [Provider selection](https://github.com/dougsong/jev-android/blob/main/sample/src/main/kotlin/io/github/jevandroid/sample/ProviderSelection.kt): `sample/src/main/kotlin/io/github/jevandroid/sample/ProviderSelection.kt`
- [Task scenarios](https://github.com/dougsong/jev-android/blob/main/sample/src/main/kotlin/io/github/jevandroid/sample/TaskScenarios.kt): `sample/src/main/kotlin/io/github/jevandroid/sample/TaskScenarios.kt`
- [Event formatter](https://github.com/dougsong/jev-android/blob/main/sample/src/main/kotlin/io/github/jevandroid/sample/AgentEventFormatter.kt): `sample/src/main/kotlin/io/github/jevandroid/sample/AgentEventFormatter.kt`
- [Bilibili policy](https://github.com/dougsong/jev-android/blob/main/sample/src/main/kotlin/io/github/jevandroid/sample/BilibiliTriplePolicy.kt): `sample/src/main/kotlin/io/github/jevandroid/sample/BilibiliTriplePolicy.kt`
- [Local test screen](https://github.com/dougsong/jev-android/blob/main/sample/src/main/kotlin/io/github/jevandroid/sample/FixtureActivity.kt): `sample/src/main/kotlin/io/github/jevandroid/sample/FixtureActivity.kt`

### Agent core

- [Task and event models](https://github.com/dougsong/jev-android/blob/main/core/src/main/kotlin/io/github/jevandroid/core/Models.kt): `core/src/main/kotlin/io/github/jevandroid/core/Models.kt`
- [Execution loop](https://github.com/dougsong/jev-android/blob/main/core/src/main/kotlin/io/github/jevandroid/core/JevAgent.kt): `core/src/main/kotlin/io/github/jevandroid/core/JevAgent.kt`
- [Progress tracking](https://github.com/dougsong/jev-android/blob/main/core/src/main/kotlin/io/github/jevandroid/core/ProgressTracker.kt): `core/src/main/kotlin/io/github/jevandroid/core/ProgressTracker.kt`
- [Outcome verifier](https://github.com/dougsong/jev-android/blob/main/core/src/main/kotlin/io/github/jevandroid/core/Models.kt): `core/src/main/kotlin/io/github/jevandroid/core/Models.kt`

### Accessibility runtime

- [Accessibility service](https://github.com/dougsong/jev-android/blob/main/sdk/src/main/kotlin/io/github/jevandroid/JevAccessibilityService.kt): `sdk/src/main/kotlin/io/github/jevandroid/JevAccessibilityService.kt`
- [UI observation and actions](https://github.com/dougsong/jev-android/blob/main/sdk/src/main/kotlin/io/github/jevandroid/AccessibilityRuntime.kt): `sdk/src/main/kotlin/io/github/jevandroid/AccessibilityRuntime.kt`
- [Snapshot fingerprints](https://github.com/dougsong/jev-android/blob/main/sdk/src/main/kotlin/io/github/jevandroid/SnapshotFingerprints.kt): `sdk/src/main/kotlin/io/github/jevandroid/SnapshotFingerprints.kt`
- [Long-press geometry](https://github.com/dougsong/jev-android/blob/main/sdk/src/main/kotlin/io/github/jevandroid/LongPressTarget.kt): `sdk/src/main/kotlin/io/github/jevandroid/LongPressTarget.kt`

### Decision providers

- [Jev provider](https://github.com/dougsong/jev-android/blob/main/sdk/src/main/kotlin/io/github/jevandroid/JevProvider.kt): `sdk/src/main/kotlin/io/github/jevandroid/JevProvider.kt`
- [DeepSeek provider](https://github.com/dougsong/jev-android/blob/main/sdk/src/main/kotlin/io/github/jevandroid/DeepSeekProvider.kt): `sdk/src/main/kotlin/io/github/jevandroid/DeepSeekProvider.kt`
- [Action catalog](https://github.com/dougsong/jev-android/blob/main/sdk/src/main/kotlin/io/github/jevandroid/DeepSeekChoices.kt): `sdk/src/main/kotlin/io/github/jevandroid/DeepSeekChoices.kt`
- [Provider progress context](https://github.com/dougsong/jev-android/blob/main/sdk/src/main/kotlin/io/github/jevandroid/ProviderProgress.kt): `sdk/src/main/kotlin/io/github/jevandroid/ProviderProgress.kt`
- [HTTP transport](https://github.com/dougsong/jev-android/blob/main/sdk/src/main/kotlin/io/github/jevandroid/ProviderTransport.kt): `sdk/src/main/kotlin/io/github/jevandroid/ProviderTransport.kt`

### Other components

- **User**
- **Host Android app**
- **Jev API**
- **DeepSeek API**
- **Android accessibility**

## Connections

- User → Sample interface: configures task (evidence: `README.md`)
- Sample interface → Provider selection: selects provider (evidence: `README.md`)
- Sample interface → Task scenarios: chooses scenario (evidence: `README.md`)
- Sample interface → Local test screen: opens test screen (evidence: `README.md`)
- Sample interface → Event formatter: formats result logs (evidence: `README.md`)
- Sample interface → Bilibili policy: uses optional policy (evidence: `README.md`)
- Host Android app → Accessibility service: starts task (evidence: `sdk/src/main/kotlin/io/github/jevandroid/JevAccessibilityService.kt`)
- Accessibility service → Execution loop: runs (evidence: `sdk/src/main/kotlin/io/github/jevandroid/JevAccessibilityService.kt`)
- Accessibility service → UI observation and actions: constructs runtime (evidence: `sdk/src/main/kotlin/io/github/jevandroid/JevAccessibilityService.kt`)
- Execution loop → UI observation and actions: observes and executes (evidence: `README.md`)
- Execution loop → Jev provider: requests decision (evidence: `core/src/main/kotlin/io/github/jevandroid/core/JevAgent.kt`)
- Execution loop → DeepSeek provider: requests decision (evidence: `core/src/main/kotlin/io/github/jevandroid/core/JevAgent.kt`)
- Execution loop → Progress tracking: tracks effects (evidence: `core/src/main/kotlin/io/github/jevandroid/core/JevAgent.kt`)
- Execution loop → Outcome verifier: checks completion (evidence: `core/src/main/kotlin/io/github/jevandroid/core/JevAgent.kt`)
- Execution loop → Task and event models: uses task and decisions (evidence: `core/src/main/kotlin/io/github/jevandroid/core/JevAgent.kt`)
- Execution loop → Android accessibility: dispatches actions (evidence: `README.md`)
- UI observation and actions → Snapshot fingerprints: checks freshness (evidence: `sdk/src/main/kotlin/io/github/jevandroid/AccessibilityRuntime.kt`)
- UI observation and actions → Long-press geometry: computes press target (evidence: `sdk/src/main/kotlin/io/github/jevandroid/AccessibilityRuntime.kt`)
- Jev provider → HTTP transport: sends request (evidence: `sdk/src/main/kotlin/io/github/jevandroid/JevProvider.kt`)
- HTTP transport → Jev API: sends HTTP request
- DeepSeek provider → Action catalog: builds action choices (evidence: `sdk/src/main/kotlin/io/github/jevandroid/DeepSeekProvider.kt`)
- DeepSeek provider → Provider progress context: encodes progress (evidence: `sdk/src/main/kotlin/io/github/jevandroid/DeepSeekProvider.kt`)
- DeepSeek provider → HTTP transport: sends request (evidence: `sdk/src/main/kotlin/io/github/jevandroid/DeepSeekProvider.kt`)
- HTTP transport → DeepSeek API: sends HTTP request
- Jev provider → Provider progress context: encodes progress (evidence: `sdk/src/main/kotlin/io/github/jevandroid/JevProvider.kt`)
- UI observation and actions → Android accessibility: uses accessibility APIs (evidence: `README.md`)