# droidrun/droidrun-portal architecture

> Architecture diagram of the GitHub repository droidrun/droidrun-portal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/droidrun/droidrun-portal
- Repository: https://github.com/droidrun/droidrun-portal

## Overview

##### Project type and purpose
- Droidrun Portal is a single‐module Android application implementing an AccessibilityService.

##### File structure
- Top‐level directories:
- app/ – Android application module (build.gradle.kts, source code, resources)
- scripts/ – shell helpers (dump_view.sh)
- static/ – images used in README display
- .github/workflows/build-and-release.yml – CI/CD pipeline for building and releasing the APK
- app/src/main/java/com/droidrun/portal:
- DroidrunPortalService.kt – your AccessibilityService entry point
- MainActivity.kt – settings UI (to enable service, permissions)
- OverlayManager.kt – handles WindowManager overlay drawing
- ElementNode.kt – data model for UI element properties
- app/src/main/res/xml: config files (accessibility_service_config, data_extraction_rules, backup_rules)
- scripts/dump_view.sh – wraps ADB commands to trigger broadcasts and capture JSON

##### README for additional insights
- The service listens for broadcast intents (EXIT, GET_ELEMENTS, TOGGLE_OVERLAY, etc.).
- JSON export happens via ADB logs and external storage.
- Key technologies: Kotlin, Android AccessibilityService API, WindowManager overlays, GitHub Actions CI.

##### Elements
- OS → AccessibilityService (AccessibilityEvents)
- Host → Service (broadcast intents)
- Service → Host (logcat, file writes)
- GitHub Actions → Apk artifact → Device
- Host/CI in another

##### Final advice
- Be meticulous: label every broadcast action, config file, and data flow.
- Don’t omit the ADB command channel—this is the primary integration point for users.
- Overlay pipeline distinctly from the data export pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CI Side"
        GA["GitHub Actions (CI/CD)"]:::ci
        GA -->|"build APK"| APK["APK Artifact"]
    end

    subgraph "Host Side"
        HostDev["Developer Workstation"]:::host
        DumpScript["dump_view.sh"]:::host
        HostDev --> DumpScript
        DumpScript -->|"ADB broadcast"| ADB["ADB shell am broadcast"]:::host
    end

    subgraph "Device Side"
        OS["Android OS (API 24+)"]:::device
        OS -->|"AccessibilityEvents"| Service["DroidrunPortalService"]:::device
        Service -->|"draw overlay calls"| Overlay["OverlayManager"]:::device
        Service -->|"detect elements"| Detector["ElementNode Model"]:::device
        Service -->|"receive intents"| IntentAPI["BroadcastReceiver/Intent API"]:::device
        IntentAPI --> Service
        Service -->|"serialize JSON"| JSONExp["JSON Exporter"]:::device
        JSONExp --> Logcat["Logcat"]:::storage
        JSONExp --> Storage["External Storage"]:::storage

        subgraph "UI Components"
            Activity["MainActivity"]:::device
        end
        Activity --> Service

        Configuration1["AndroidManifest.xml"]:::device
        Configuration2["accessibility_service_config.xml"]:::device
        Configuration3["data_extraction_rules.xml"]:::device
        Configuration4["backup_rules.xml"]:::device
    end

    DumpScript --> ADB --> IntentAPI
    APK -->|"installed on"| OS

    click Service "https://github.com/droidrun/droidrun-portal/blob/main/app/src/main/java/com/droidrun/portal/DroidrunPortalService.kt"
    click Overlay "https://github.com/droidrun/droidrun-portal/blob/main/app/src/main/java/com/droidrun/portal/OverlayManager.kt"
    click Detector "https://github.com/droidrun/droidrun-portal/blob/main/app/src/main/java/com/droidrun/portal/ElementNode.kt"
    click Activity "https://github.com/droidrun/droidrun-portal/blob/main/app/src/main/java/com/droidrun/portal/MainActivity.kt"
    click Configuration1 "https://github.com/droidrun/droidrun-portal/blob/main/app/src/main/AndroidManifest.xml"
    click Configuration2 "https://github.com/droidrun/droidrun-portal/blob/main/app/src/main/res/xml/accessibility_service_config.xml"
    click Configuration3 "https://github.com/droidrun/droidrun-portal/blob/main/app/src/main/res/xml/data_extraction_rules.xml"
    click Configuration4 "https://github.com/droidrun/droidrun-portal/blob/main/app/src/main/res/xml/backup_rules.xml"
    click DumpScript "https://github.com/droidrun/droidrun-portal/blob/main/scripts/dump_view.sh"
    click GA "https://github.com/droidrun/droidrun-portal/blob/main/.github/workflows/build-and-release.yml"
    click README "https://github.com/droidrun/droidrun-portal/blob/main/README.md"

    classDef device fill:#f9f,stroke:#333,stroke-width:1px
    classDef host fill:#ff9,stroke:#333,stroke-width:1px
    classDef ci fill:#9f9,stroke:#333,stroke-width:1px
    classDef storage fill:#9ff,stroke:#333,stroke-width:1px
```
