# akylas/oss-documentscanner architecture

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

- Interactive diagram: https://gitdiagram.com/akylas/oss-documentscanner
- Repository: https://github.com/akylas/oss-documentscanner

## Overview

##### Project type and purpose
- This is a cross-platform mobile application repository hosting two apps (“OSS DocumentScanner” and “OSS CardWallet”) built with NativeScript+Svelte.
- It also contains a native image-processing plugin (plugin-nativeprocessor) leveraging OpenCV, Tesseract and ZXing, a core C++ library (cpp folder), a web PDF viewer SPA (webpdfviewer), end-to-end tests, and CI/CD scripts (fastlane, GitHub Actions).

##### Top-level components
- App Layer (app/): Svelte UI components, application bootstrap (bootstrap.ts), themes, i18n, models, helpers.
- Services Layer (app/services/): business logic for backend API, OCR, PDF export, QR code, security, shortcuts, sync (WebDAV/local).
- Native Bridge (shims/ + Nativescript runtime): platform shims for Android/iOS to bind JS → native calls.
- Native Processor Plugin (plugin-nativeprocessor/):
- Android submodule: Java/Kotlin bridge, JNI + C++ wrappers, OpenCV and Tesseract libs.
- iOS submodule: Swift/ObjC bridge, modulemap, OpenCV2.xcframework, Tesseract.
- Core C++ Library (cpp/): image-processing algorithms (document detection, OCR wrappers, QRCode, transforms) and JSONcons.
- Web PDF Viewer (webpdfviewer/): standalone Svelte+TypeScript SPA for viewing exported PDFs.
- Testing & CI (e2e/, fastlane/, .github/workflows/): Appium-Mocha tests, Fastlane metadata and release pipelines, GitHub Actions release build.
- Build & Config (webpack.config.js, tsconfig.json, svelte.config.js, env files, scripts/): compile, bundle, environment management.

##### Key interactions and data flows
- At runtime, the Svelte app uses NativeScript to render UI in a WebView-style or native UI layer.
- User actions → UI Components → invoke Services (OCRService, OCRDataView) → call into Native Bridge → plugin-nativeprocessor → native libs (OpenCV/Tesseract) → return processed image/text.
- PDF export triggers PDFExporter → PDFCanvas (platform-specific implementations) → may spawn PDFExportWorker for background rendering.
- Sync services (BaseDataSyncService, WebdavDataSyncService, LocalFolderPDFSyncService) read/write files from the device file system, manage metadata, and communicate over HTTP/WebDAV with external file servers or remote drives.
- QR code generation is handled via services/qrcode.ts and plugin code (ZXing).
- Preferences and security (passcode, storage encryption) are managed locally via services/preferences.ts and services/security.ts.
- The webpdfviewer is a separate static SPA that consumes exported PDF assets, unrelated to mobile runtime but sharing some transformer logic where feasible.

##### Architectural patterns and design principles
- Modular layered architecture: UI → Services → Native Bridge → Native Modules → External libs.
- Plugin pattern: plugin-nativeprocessor acts as an extensibility point for performance-critical image processing.
- Worker threads: heavy operations (PDF rendering, sync) offloaded to WebWorker‐style workers (SyncWorker, PDFExportWorker).
- Environment-based configuration: uses APP_ID, APP_RESOURCES to toggle between the two apps.
- Cross-platform abstraction: shims and ts “.common/.android/.ios” files implement platform differences.
- CI/CD integration: fastlane for store publishing, GitHub Actions for releases, environment files for signing credentials.

- Clear component labels with folder path hints (e.g., “app/services/ocr.ts”).
- A note on environment‐driven app selection (APP_ID → App_Resources).

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Presentation/UI"
        direction TB
        BS["bootstrap.ts"]:::frontend
        COMPS["app/components/…"]:::frontend
        ASSETS["app/assets/…"]:::frontend
        THEMES["app/themes/…"]:::frontend
        I18N["app/i18n/…"]:::frontend
        MODELS["app/models/…"]:::frontend
        HELPERS["app/helpers/…"]:::frontend
    end

    subgraph "Business Logic/Services"
        direction TB
        API["api.ts"]:::services
        BACKEND["BackendService.ts"]:::services
        OCR_SVC["ocr.ts"]:::services
        PDFExp["PDFExporter.ts"]:::services
        PDFCanvas["PDFCanvas*.ts"]:::services
        QR["qrcode.ts"]:::services
        PREF["preferences.ts"]:::services
        SEC["security.ts"]:::services
        SHRT_ADR["shortcuts.android.ts"]:::services
        SHRT_IOS["shortcuts.ios.ts"]:::services
        subgraph "Sync Services"
            direction TB
            BASESYNC["BaseDataSyncService.ts"]:::services
            WEBDAV["WebdavDataSyncService.ts"]:::services
            LOCALPDF["LocalFolderPDFSyncService.ts"]:::services
        end
        WORKER1["PDFExportWorker"]:::services
        WORKER2["SyncWorker"]:::services
    end

    subgraph "Native Bridge/Shims"
        direction TB
        SHIMS["app/shims/*.ts"]:::native
    end

    subgraph "Native Processor Plugin"
        direction TB
        subgraph Android
            direction TB
            JNI["platforms/android/ (Java/Kotlin + JNI)"]:::native
        end
        subgraph iOS
            direction TB
            SWIFT["platforms/ios/ (Swift/ObjC)"]:::native
        end
        JSI["index.android.ts / index.ios.ts"]:::native
        CROP["CropView.ts"]:::native
    end

    subgraph "Core C++ Library"
        direction TB
        CPP_SRC["cpp/src/*.cpp"]:::native
        CPP_INC["cpp/src/include/*.h"]:::native
        JSONCONS["cpp/src/include/jsoncons/…"]:::native
    end

    subgraph "Web PDF Viewer SPA"
        direction TB
        WP_SRC["webpdfviewer/src/…"]:::frontend
        WP_BUILD["webpack.config.js / tsconfig.json"]:::frontend
    end

    subgraph "Testing & CI/CD"
        direction TB
        E2E["e2e/…"]:::external
        FASTLANE["fastlane/…"]:::external
        GHA[".github/workflows/release.yml"]:::external
    end

    subgraph "Build & Config"
        direction TB
        WEBPACK["webpack.config.js"]:::external
        TSCONFIG["tsconfig.json"]:::external
        SVELTECFG["svelte.config.js"]:::external
        SCRIPTS["scripts/…"]:::external
        ENV[".env.ci*"]:::external
    end

    subgraph "External Systems"
        direction TB
        WEBDAVEXT["WebDAV Server"]:::external
        APPSTORE["App Stores"]:::external
    end

    BS -->|"renders"| COMPS
    COMPS -->|"invoke"| OCR_SVC
    OCR_SVC -->|"calls"| SHIMS
    SHIMS -->|"forwards"| JNI
    SHIMS -->|"forwards"| SWIFT
    JNI -->|"calls Native libs"| CPP_SRC
    SWIFT -->|"calls Native libs"| CPP_SRC
    CPP_SRC -->|"uses"| JSONCONS
    OCR_SVC -->|"returns data"| COMPS

    PDFExp -->|"offloads"| WORKER1
    WORKER1 -->|"background render"| PDFCanvas

    subgraph SyncFlow
        direction TB
        BASESYNC -->|"spawns"| WORKER2
        WEBDAV -->|"HTTP/WebDAV"| WEBDAVEXT
        LOCALPDF -->|"filesystem"| HELPERS
    end

    QR -->|"ZXing binding"| JNI
    PREF -->|"local storage"| HELPERS
    SEC -->|"encryption"| HELPERS

    WP_SRC -->|"loads exported PDFs"| WP_BUILD

    FASTLANE -->|"publishes"| APPSTORE
    GHA -->|"triggers"| FASTLANE

    ENV -->|"toggles APP_ID"| BS

    classDef frontend fill:#add8e6,stroke:#333,stroke-width:1px
    classDef services fill:#90ee90,stroke:#333,stroke-width:1px
    classDef native fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px

    click BS "https://github.com/akylas/oss-documentscanner/blob/master/app/bootstrap.ts"
    click COMPS "https://github.com/akylas/oss-documentscanner/tree/master/app/components/"
    click ASSETS "https://github.com/akylas/oss-documentscanner/tree/master/app/assets/"
    click THEMES "https://github.com/akylas/oss-documentscanner/tree/master/app/themes/"
    click I18N "https://github.com/akylas/oss-documentscanner/tree/master/app/i18n/"
    click MODELS "https://github.com/akylas/oss-documentscanner/tree/master/app/models/"
    click HELPERS "https://github.com/akylas/oss-documentscanner/tree/master/app/helpers/"
    click API "https://github.com/akylas/oss-documentscanner/blob/master/app/services/api.ts"
    click BACKEND "https://github.com/akylas/oss-documentscanner/blob/master/app/services/BackendService.ts"
    click OCR_SVC "https://github.com/akylas/oss-documentscanner/blob/master/app/services/ocr.ts"
    click PDFExp "https://github.com/akylas/oss-documentscanner/blob/master/app/services/pdf/PDFExporter.ts"
    click PDFCanvas "https://github.com/akylas/oss-documentscanner/blob/master/app/services/pdf/PDFCanvas*.ts"
    click QR "https://github.com/akylas/oss-documentscanner/blob/master/app/services/qrcode.ts"
    click PREF "https://github.com/akylas/oss-documentscanner/blob/master/app/services/preferences.ts"
    click SEC "https://github.com/akylas/oss-documentscanner/blob/master/app/services/security.ts"
    click SHRT_ADR "https://github.com/akylas/oss-documentscanner/blob/master/app/services/shortcuts.android.ts"
    click SHRT_IOS "https://github.com/akylas/oss-documentscanner/blob/master/app/services/shortcuts.ios.ts"
    click BASESYNC "https://github.com/akylas/oss-documentscanner/blob/master/app/services/sync/BaseDataSyncService.ts"
    click WEBDAV "https://github.com/akylas/oss-documentscanner/blob/master/app/services/sync/WebdavDataSyncService.ts"
    click LOCALPDF "https://github.com/akylas/oss-documentscanner/blob/master/app/services/sync/LocalFolderPDFSyncService.ts"
    click SHIMS "https://github.com/akylas/oss-documentscanner/tree/master/app/shims/"
    click JNI "https://github.com/akylas/oss-documentscanner/tree/master/plugin-nativeprocessor/platforms/android/"
    click SWIFT "https://github.com/akylas/oss-documentscanner/tree/master/plugin-nativeprocessor/platforms/ios/"
    click JSI "https://github.com/akylas/oss-documentscanner/blob/master/plugin-nativeprocessor/index.android.ts"
    click CROP "https://github.com/akylas/oss-documentscanner/blob/master/plugin-nativeprocessor/CropView.ts"
    click CPP_SRC "https://github.com/akylas/oss-documentscanner/tree/master/cpp/src/"
    click CPP_INC "https://github.com/akylas/oss-documentscanner/tree/master/cpp/src/include/"
    click JSONCONS "https://github.com/akylas/oss-documentscanner/tree/master/cpp/src/include/jsoncons/"
    click WP_SRC "https://github.com/akylas/oss-documentscanner/tree/master/webpdfviewer/src/"
    click WP_BUILD "https://github.com/akylas/oss-documentscanner/blob/master/webpdfviewer/webpack.config.js"
    click E2E "https://github.com/akylas/oss-documentscanner/tree/master/e2e/"
    click FASTLANE "https://github.com/akylas/oss-documentscanner/tree/master/fastlane/"
    click GHA "https://github.com/akylas/oss-documentscanner/blob/master/.github/workflows/release.yml"
    click WEBPACK "https://github.com/akylas/oss-documentscanner/blob/master/webpack.config.js"
    click TSCONFIG "https://github.com/akylas/oss-documentscanner/blob/master/tsconfig.json"
    click SVELTECFG "https://github.com/akylas/oss-documentscanner/blob/master/svelte.config.js"
    click SCRIPTS "https://github.com/akylas/oss-documentscanner/tree/master/scripts/"
    click ENV "https://github.com/akylas/oss-documentscanner/blob/master/.env.ci*"
```
