# schwabe/ics-openvpn architecture

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

- Interactive diagram: https://gitdiagram.com/schwabe/ics-openvpn
- Repository: https://github.com/schwabe/ics-openvpn

## Overview

##### Project Type and Purpose
- This is a full-stack Android application: an open-source OpenVPN client for Android (API level 14+).
- It combines a native VPN engine (C/C++), a Java core service layer exposing AIDL APIs, and a rich Android UI.
- Additional modules include sample apps (remoteExample) demonstrating AIDL control and a TLS external certificate provider (tlsexternalcertprovider).

##### File-Structure Analysis
- Top-level folders:
- main/ – the main OpenVPN Android app
- remoteExample/ – sample app showing external control via AIDL
- tlsexternalcertprovider/ – sample app implementing ExternalCertificateProvider AIDL
- Inside main/:
- src/main/cpp/ – native engine and third-party libs (openvpn3, lzo, lz4, mbedtls, openssl, jniglue, ovpnutil)
- src/main/java/de/blinkt/openvpn/core/ – Java VPN service, config parser, thread management, JNI wrappers
- src/main/java/de/blinkt/openvpn/api/ – AIDL interface definitions and API entry points
- src/main/java/de/blinkt/openvpn/activities & fragments – UI screens and user workflows
- src/main/aidl/ – AIDL files defining the external service contracts
- src/skeleton/ – plugin skeleton for extensibility
- src/test/ & src/testui/ – unit and UI tests
- Build & config:
- Gradle (Kotlin DSL) scripts, CMakeLists.txt, NDK configuration, AndroidManifest.xml, ProGuard rules.

##### Key Technologies
- Android SDK & APIs (VpnService, Notification, Intent system, UI toolkit)
- Java/Kotlin for core service and UI
- JNI bridge (jniglue.c/.h) connecting Java to native C/C++
- Native engine: OpenVPN core, LZO/LZ4 compression, mbedtls/OpenSSL crypto
- AIDL for cross-process control (ConnectVPN, DisconnectVPN, PauseVPN, ResumeVPN)
- Gradle, CMake, NDK for multi-platform native builds

##### Main Components
a. Android OS Framework
- VPNService API (platform)
- Notification manager, Intent dispatcher
b. Application Layers
1. UI Layer
– Activities/Fragments (MainActivity, Settings*, LogWindow, FileSelect, TileService)
– Interacts with the Java core via Intents and bound service calls
2. Java Core Service Layer
– OpenVPNService & OpenVPNStatusService (extends VpnService)
– AIDL API implementation (de.blinkt.openvpn.api.*)
– ConfigParser, ProfileManager, TrafficHistory, LogFileHandler
– JNI wrappers to native engine (NativeUtils, OpenVPNThread)
3. JNI Bridge
– jniglue.c / osslutil.cpp
– Marshals data and control commands between Java and C++
4. Native VPN Engine
– openvpn3 code, openvpn-config parser, ovpnutil
– Compression libs: lzo, lz4
– Crypto libs: mbedtls, OpenSSL
5. Storage & Assets
– .ovpn profile files (private storage), SharedPreferences, SQLite or file-based storage
c. External Modules (Show as separate but connected)
– remoteExample app (binds to AIDL API)
– tlsexternalcertprovider service (implements ExternalCertificateProvider AIDL)

##### Relationships & Data Flows
- UI <→ binds to → Java Core Service (via Context.bindService / AIDL)
- UI ↔ Intents → Core Service (start/pause/resume via Broadcast receivers)
- Java Core Service ↔ JNI → Native Engine (start/stop VPN tunnels)
- Native Engine ↔ Android VPNService → Kernel TUN interface (packet I/O)
- Java Core Service ↔ Storage (load/save profiles and logs)
- External Apps ↔ AIDL → Java Core Service (remote control)
- External Certificate Provider ↔ AIDL → Java Core Service (on-demand cert selection)

##### Architectural Patterns & Principles
- Layered architecture: UI → Service → Native engine
- Adapter pattern: JNI glue adapts Java calls to C APIs
- Observer pattern: StatusListener callbacks in Java for UI updates
- Modularization: separate native libs, Java core, UI, sample extensions
- Dependency inversion: high-level modules (UI, API) depend on abstractions (AIDL, interfaces)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Android Framework
    subgraph "Android Framework"
        VPNServiceAPI["VPNService API"]:::framework
        NotificationManager["NotificationManager"]:::framework
        IntentDispatcher["Intent Dispatcher"]:::framework
        Kernel["Kernel TUN Interface"]:::framework
    end

    %% UI Layer
    subgraph "UI Layer"
        Activities["Activities"]:::ui
        Fragments["Fragments"]:::ui
        TileService["OpenVPNTileService"]:::ui
    end

    %% Java Core Service Layer
    subgraph "Java Core Service Layer"
        OpenVPNService["OpenVPNService"]:::service
        OpenVPNStatusService["OpenVPNStatusService"]:::service
        ConfigParser["ConfigParser"]:::service
        ProfileManager["ProfileManager"]:::service
        TrafficHistory["TrafficHistory"]:::service
        LogFileHandler["LogFileHandler"]:::service
        APIVpnProfile["APIVpnProfile"]:::service
        IOpenVPNAPIService["IOpenVPNAPIService"]:::service
        IOpenVPNStatusCallback["IOpenVPNStatusCallback"]:::service
        ExternalCertAIDL["ExternalCertificateProvider AIDL"]:::service
    end

    %% JNI Bridge
    subgraph "JNI Bridge"
        JNIGlue["jniglue.c/.h"]:::jni
        OsslUtil["osslutil.cpp"]:::jni
    end

    %% Native VPN Engine
    subgraph "Native VPN Engine"
        OpenVPN3["openvpn3 core"]:::native
        ConfigParserNative["openvpn-config parser"]:::native
        OvpnUtil["ovpnutil"]:::native
        LZ4["LZ4 lib"]:::native
        LZO["LZO lib"]:::native
        MbedTLS["mbed TLS"]:::native
        OpenSSL["OpenSSL"]:::native
    end

    %% Storage & Assets
    subgraph "Storage & Assets"
        Assets["assets"]:::storage
        Res["res"]:::storage
    end

    %% External Modules
    subgraph "External Modules"
        RemoteApp["remoteExample App"]:::external
        TLSProvider["TLS ExternalCertProvider"]:::external
    end

    %% Connections
    Activities -->|bind/AIDL| OpenVPNService
    Fragments -->|bind/AIDL| OpenVPNService
    TileService -->|bind/AIDL| OpenVPNService
    Activities -->|Intents| OpenVPNService
    OpenVPNService -->|implements| IOpenVPNAPIService
    OpenVPNService -->|uses| IOpenVPNStatusCallback
    OpenVPNService -->|uses| ConfigParser
    OpenVPNService -->|uses| ProfileManager
    OpenVPNService -->|uses| TrafficHistory
    OpenVPNService -->|uses| LogFileHandler
    OpenVPNService -->|uses| APIVpnProfile
    OpenVPNService -->|AIDL| ExternalCertAIDL
    OpenVPNService -->|calls JNI| JNIGlue
    JNIGlue -->|calls| OpenVPN3
    JNIGlue -->|calls| ConfigParserNative
    JNIGlue -->|calls| OvpnUtil
    JNIGlue -->|uses| OsslUtil
    OpenVPN3 -->|packet I/O| Kernel
    OpenVPNService -->|file I/O| Assets
    OpenVPNService -->|file I/O| Res
    RemoteApp -->|AIDL| IOpenVPNAPIService
    TLSProvider -->|AIDL| ExternalCertAIDL

    VPNServiceAPI -->|provides| OpenVPNService
    NotificationManager -->|notifies| Activities
    IntentDispatcher -->|dispatches| OpenVPNService

    %% Click Events
    click Activities "https://github.com/schwabe/ics-openvpn/tree/master/main/src/main/java/de/blinkt/openvpn/activities/"
    click Fragments "https://github.com/schwabe/ics-openvpn/tree/master/main/src/main/java/de/blinkt/openvpn/fragments/"
    click TileService "https://github.com/schwabe/ics-openvpn/blob/master/main/src/ui/java/de/blinkt/openvpn/OpenVPNTileService.java"
    click ConfigParser "https://github.com/schwabe/ics-openvpn/blob/master/main/src/main/java/de/blinkt/openvpn/core/ConfigParser.java"
    click ProfileManager "https://github.com/schwabe/ics-openvpn/blob/master/main/src/main/java/de/blinkt/openvpn/core/ProfileManager.java"
    click TrafficHistory "https://github.com/schwabe/ics-openvpn/blob/master/main/src/main/java/de/blinkt/openvpn/core/TrafficHistory.java"
    click LogFileHandler "https://github.com/schwabe/ics-openvpn/blob/master/main/src/main/java/de/blinkt/openvpn/core/LogFileHandler.java"
    click OpenVPNService "https://github.com/schwabe/ics-openvpn/blob/master/main/src/main/java/de/blinkt/openvpn/core/OpenVPNService.java"
    click OpenVPNStatusService "https://github.com/schwabe/ics-openvpn/blob/master/main/src/main/java/de/blinkt/openvpn/core/OpenVPNStatusService.java"
    click APIVpnProfile "https://github.com/schwabe/ics-openvpn/blob/master/main/src/main/java/de/blinkt/openvpn/api/APIVpnProfile.java"
    click IOpenVPNAPIService "https://github.com/schwabe/ics-openvpn/blob/master/main/src/main/java/de/blinkt/openvpn/api/IOpenVPNAPIService.aidl"
    click IOpenVPNStatusCallback "https://github.com/schwabe/ics-openvpn/blob/master/main/src/main/java/de/blinkt/openvpn/api/IOpenVPNStatusCallback.aidl"
    click ExternalCertAIDL "https://github.com/schwabe/ics-openvpn/blob/master/main/src/main/aidl/de/blinkt/openvpn/api/ExternalCertificateProvider.aidl"
    click JNIGlue "https://github.com/schwabe/ics-openvpn/blob/master/main/src/main/cpp/ovpnutil/jniglue.c"
    click OsslUtil "https://github.com/schwabe/ics-openvpn/blob/master/main/src/main/cpp/ovpnutil/osslutil.cpp"
    click OpenVPN3 "https://github.com/schwabe/ics-openvpn/tree/master/main/src/main/cpp/openvpn3/"
    click ConfigParserNative "https://github.com/schwabe/ics-openvpn/tree/master/main/src/main/cpp/openvpn-config/"
    click OvpnUtil "https://github.com/schwabe/ics-openvpn/tree/master/main/src/main/cpp/ovpnutil/"
    click LZ4 "https://github.com/schwabe/ics-openvpn/tree/master/main/src/main/cpp/lz4/"
    click LZO "https://github.com/schwabe/ics-openvpn/tree/master/main/src/main/cpp/lzo/"
    click MbedTLS "https://github.com/schwabe/ics-openvpn/tree/master/main/src/main/cpp/mbedtls/"
    click OpenSSL "https://github.com/schwabe/ics-openvpn/tree/master/main/src/main/cpp/openssl/"
    click Assets "https://github.com/schwabe/ics-openvpn/tree/master/main/src/main/assets/"
    click Res "https://github.com/schwabe/ics-openvpn/tree/master/main/src/main/res/"
    click RemoteApp "https://github.com/schwabe/ics-openvpn/blob/master/remoteExample/src/main/java/de/blinkt/openvpn/remote/MainActivity.java"
    click TLSProvider "https://github.com/schwabe/ics-openvpn/blob/master/tlsexternalcertprovider/src/main/java/de/blinkt/externalcertprovider/ExternalCertService.java"

    %% Styles
    classDef framework fill:#d3d3d3,stroke:#333,stroke-width:1px;
    classDef ui fill:#b7e4c7,stroke:#333,stroke-width:1px;
    classDef service fill:#a0c4ff,stroke:#333,stroke-width:1px;
    classDef jni fill:#ffb703,stroke:#333,stroke-width:1px;
    classDef native fill:#ffadad,stroke:#333,stroke-width:1px;
    classDef storage fill:#fdffb6,stroke:#333,stroke-width:1px;
    classDef external fill:#cdb4db,stroke:#333,stroke-width:1px;
```
