# hyperb1iss/droidmind architecture

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

- Interactive diagram: https://gitdiagram.com/hyperb1iss/droidmind
- Repository: https://github.com/hyperb1iss/droidmind

## Overview

##### Project type and purpose
- DroidMind is an open-source Python tool (library + server/CLI) that acts as a bridge between AI assistants (via the Model Context Protocol, MCP) and Android devices (via ADB). Its purpose is to expose device-management and automation capabilities over a network interface (SSE, CLI).

##### File structure
- Top-level module `droidmind/` contains:
- `server.py` – MCP server entrypoint
- `console.py` – CLI interactive shell
- `adb.py` – low-level ADB wrapper
- `devices.py` – represents and manages device connections
- `filesystem.py`, `packages.py`, `prompts.py`, `security.py`, `log.py`, `context.py` – core services (FS access, package inspection, prompt templates, security validation, logging, shared context)
- `tools/` – plugin-style modules (app_management, device_management, diagnostics, file_operations, logs, media, shell, ui)
- `tests/` covers unit tests by component.
- `docs/`, CI/CD config, `pyproject.toml` for build and dependencies, `LICENSE`, `README.md`.

##### README
- Describes the MCP resources and tool commands.
- Shows how to start the SSE server (`droidmind --transport sse`).
- Lists features (device control, system analysis, file system, UI automation, security, MCP integration).
- No front-end or database; purely network protocol + device interface.

##### Main components and relationships
a. Client Layer
- AI Assistant (external) – speaks MCP over SSE or STDIO
- CLI/Console – human interactive shell (falls back to same internals)
b. Protocol Layer
- `server.py` – HTTP/SSE server hosting MCP endpoint
- MCP request/response dispatcher
c. Core Services
- `context.py` – request context, authentication, session state
- `security.py` – command risk assessment & validation
- `log.py` – audit logging of commands and risk levels
d. Device Interface
- `adb.py` – invokes ADB subprocess (USB / TCP)
- `devices.py` – tracks connected device objects and metadata
e. Feature Plugins (Tools)
- `tools/*.py` – high-level operations built on ADB + core services (app management, UI automation, file ops, logs, media, diagnostics)
f. External Systems
- ADB daemon (on host)
- Android device(s)
- Optional: UV package manager (for dev workflow)
- GitHub Actions (CI/CD)

##### Architectural patterns & design principles
- Modular “plugin” architecture: new tool modules drop into `tools/`.
- Layered design: Protocol → Core Services → Device Interface → External devices.
- Single responsibility: each module focuses on one domain.
- Security by design: all commands flow through `security.py` and `log.py`.
- Context propagation: `context.py` carries session data across calls.

4. Core Services – cluster of rectangles: Context, Security, Logging
- AI Assistant → (MCP/SSE) → MCP Server
- CLI → internal API → MCP Server
- MCP Server → Core Services (Context, Security, Logging)
- MCP Server → Tool Plugins → ADB Wrapper → ADB Daemon → Android Device(s)
- Responses flow back up: Device → ADB → Tools → Server → Client.
- “SSE / HTTP” between client and server
- “run_adb_command(cmd)” between plugins and ADB wrapper

##### Key focus
- Every core package (`context`, `security`, `log`, `adb`, each `tools/*`) appears once.
- Flow from AI assistant → server → device and back.
- Security validation path and logging path for audit.
- Do not over-complicate: keep layers distinct and minimal.
- Extensibility by marking the plugin boundary.
- External dependencies (ADB, Android devices, UV, GitHub Actions) to complete the picture.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    AI["AI Assistant"]:::external
    CLI["CLI/Console"]:::cli

    %% Protocol Layer
    MCPServer["MCP Server"]:::server

    %% Core Services
    subgraph "Core Services"
        Context["Context Service"]:::core
        Security["Security Service"]:::core
        Logging["Logging Service"]:::core
    end

    %% Feature Plugins
    subgraph "Feature Plugins"
        AppMgmt["App Mgmt"]:::plugin
        DevMgmtPlugin["Device Mgmt"]:::plugin
        Diagnostics["Diagnostics"]:::plugin
        FileOps["File Ops"]:::plugin
        LogsP["Logs"]:::plugin
        Media["Media"]:::plugin
        Shell["Shell"]:::plugin
        UI["UI Automation"]:::plugin
    end

    %% Device Interface
    subgraph "Device Interface"
        DeviceMgr["Device Manager"]:::device
        ADBWrapper["ADB Wrapper"]:::adb
    end

    %% External Systems
    ADBDaemon["ADB Daemon"]:::infra
    AndroidDevice["Android Device(s)"]:::device_ext

    %% Flows
    AI -->|"SSE/HTTP"| MCPServer
    CLI -->|"internal API"| MCPServer
    MCPServer -->|"create_ctx()"| Context
    MCPServer -->|"validate()"| Security
    MCPServer -->|"log_command()"| Logging
    MCPServer -->|"dispatch()"| AppMgmt
    MCPServer -->|"dispatch()"| DevMgmtPlugin
    MCPServer -->|"dispatch()"| Diagnostics
    MCPServer -->|"dispatch()"| FileOps
    MCPServer -->|"dispatch()"| LogsP
    MCPServer -->|"dispatch()"| Media
    MCPServer -->|"dispatch()"| Shell
    MCPServer -->|"dispatch()"| UI

    AppMgmt -->|"run_adb_command(cmd)"| ADBWrapper
    DevMgmtPlugin -->|"run_adb_command(cmd)"| ADBWrapper
    Diagnostics -->|"run_adb_command(cmd)"| ADBWrapper
    FileOps -->|"run_adb_command(cmd)"| ADBWrapper
    LogsP -->|"run_adb_command(cmd)"| ADBWrapper
    Media -->|"run_adb_command(cmd)"| ADBWrapper
    Shell -->|"run_adb_command(cmd)"| ADBWrapper
    UI -->|"run_adb_command(cmd)"| ADBWrapper

    ADBWrapper -->|"invoke ADB"| ADBDaemon
    ADBDaemon -->|"USB/TCP"| AndroidDevice

    %% Click Events
    click MCPServer "https://github.com/hyperb1iss/droidmind/blob/main/droidmind/server.py"
    click CLI "https://github.com/hyperb1iss/droidmind/blob/main/droidmind/console.py"
    click ADBWrapper "https://github.com/hyperb1iss/droidmind/blob/main/droidmind/adb.py"
    click DeviceMgr "https://github.com/hyperb1iss/droidmind/blob/main/droidmind/devices.py"
    click Context "https://github.com/hyperb1iss/droidmind/blob/main/droidmind/context.py"
    click Security "https://github.com/hyperb1iss/droidmind/blob/main/droidmind/security.py"
    click Logging "https://github.com/hyperb1iss/droidmind/blob/main/droidmind/log.py"
    click FileOps "https://github.com/hyperb1iss/droidmind/blob/main/droidmind/filesystem.py"
    click LogsP "https://github.com/hyperb1iss/droidmind/blob/main/droidmind/packages.py"
    click Diagnostics "https://github.com/hyperb1iss/droidmind/blob/main/droidmind/diagnostics.py"
    click AppMgmt "https://github.com/hyperb1iss/droidmind/blob/main/droidmind/tools/app_management.py"
    click DevMgmtPlugin "https://github.com/hyperb1iss/droidmind/blob/main/droidmind/tools/device_management.py"
    click Diagnostics "https://github.com/hyperb1iss/droidmind/blob/main/droidmind/tools/diagnostics.py"
    click FileOps "https://github.com/hyperb1iss/droidmind/blob/main/droidmind/tools/file_operations.py"
    click LogsP "https://github.com/hyperb1iss/droidmind/blob/main/droidmind/tools/logs.py"
    click Media "https://github.com/hyperb1iss/droidmind/blob/main/droidmind/tools/media.py"
    click Shell "https://github.com/hyperb1iss/droidmind/blob/main/droidmind/tools/shell.py"
    click UI "https://github.com/hyperb1iss/droidmind/blob/main/droidmind/tools/ui.py"
    click tests "https://github.com/hyperb1iss/droidmind/tree/main/tests/"
    click cicd "https://github.com/hyperb1iss/droidmind/blob/main/.github/workflows/ci-cd.yml"
    click build "https://github.com/hyperb1iss/droidmind/blob/main/pyproject.toml"
    click docs "https://github.com/hyperb1iss/droidmind/tree/main/docs/"

    %% Styles
    classDef external fill:#D0E6F8,stroke:#6EA8FE;
    classDef cli fill:#B3D4FC,stroke:#3A8DFF;
    classDef server fill:#C8E6C9,stroke:#66BB6A;
    classDef core fill:#FFF9C4,stroke:#FDD835;
    classDef plugin fill:#FFE0B2,stroke:#FB8C00;
    classDef adb fill:#FFCC80,stroke:#FB8C00;
    classDef device fill:#E1BEE7,stroke:#AB47BC;
    classDef infra fill:#FFF59D,stroke:#FDD835,stroke-dasharray: 5 5;
    classDef device_ext fill:#ECEFF1,stroke:#90A4AE;
```
