# niedev/neuralnetworkdemo architecture

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

- Interactive diagram: https://gitdiagram.com/niedev/neuralnetworkdemo
- Repository: https://github.com/niedev/neuralnetworkdemo

## Overview

##### Project Type and Purpose
- This is an Android demo application (“communicatorExample”) that integrates a native C++ translation engine (SentencePiece) via JNI.
- The Java UI handles Bluetooth pairing and messaging; the Translator.java class loads an offline translation model and runs inference natively.

##### High-Level File Structure Analysis
– Top-level:
- app/           ← Android Studio module
- gradle/, build.gradle, settings.gradle ← build system
– app/src/main:
- java/         ← Android UI, Bluetooth services, Translator.java
- cpp/          ← Native code: SentencePiece implementation, tests, docs, CMakeLists.txt
- res/          ← Android layouts, drawables, values
- AndroidManifest.xml
– app/src/main/cpp/third_party:
- absl, darts_clone, esaxx, protobuf-lite ← bundled native dependencies
– app/src/main/cpp/python:
- packaging scripts & examples for Python module (out-of-band)

##### Key Insights from README
- Translator.java instantiates the native model by name from /Download/models.

##### Main Components and Their Interactions
A. Android UI Layer (Java)
– Activities & Fragments (MainActivity, ConversationFragment, PairingFragment)
– Bluetooth Manager classes for discovery, connection, and message transport
– UI Adapters (MessagesAdapter, PeerListAdapter)
– Translator.java & Tokenizer classes
B. JNI Bridge
– sentencepiece.i SWIG interface
– Generated Wrapper (sentencepiece_wrap.cxx)
C. Native C++ Translation Engine
– Core modules: SentencePieceProcessorInterface, model_factory, tokenizer modules, trainers (for completeness)
– Third-party libraries: absl (flags, containers, strings), protobuf-lite, darts_clone, esaxx
D. Runtime Resources
– Translation model files (download/models/<model_name>.model) on device storage
E. Android System Services
– Bluetooth APIs for peer-to-peer messaging
– Local file system access for loading models

##### Architectural Patterns & Design Principles
- Separation of concerns: UI vs translation logic vs Bluetooth transport vs native inference.
- Layered architecture: clear Java↔native boundary via JNI.
- Offline translation: model files decoupled from code.
- Dependency management: Gradle for Java, CMake/NDK for C++.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layer 1: Android OS & Hardware
    subgraph "Android OS & Hardware"
        direction TB
        BluetoothStack["Bluetooth Stack"]:::os
        FileSystem["File System"]:::os
    end

    %% Layer 2: Android App
    subgraph "Android App"
        direction TB
        subgraph "UI Components"
            direction TB
            MainActivity["MainActivity"]:::ui
            ConversationFragment["ConversationFragment"]:::ui
            PairingFragment["PairingFragment"]:::ui
            MessagesAdapter["MessagesAdapter"]:::ui
            PeerListAdapter["PeerListAdapter"]:::ui
        end
        subgraph "Business Logic"
            direction TB
            Translator["Translator.java"]:::business
            Tokenizer["Tokenizer.java"]:::business
        end
        AndroidBluetoothAPI["Android Bluetooth API"]:::business
        Toast["Toast Notifications"]:::business
    end

    %% Layer 3: JNI Bridge
    subgraph "JNI Bridge"
        direction TB
        CMake["CMakeLists.txt"]:::jni
        ConfigHeader["config.h.in"]:::jni
        SWIGInterface["sentencepiece.i"]:::jni
        Wrapper["sentencepiece_wrap.cxx"]:::jni
    end

    %% Layer 4: Native C++ Library
    subgraph "Native C++ Library"
        direction TB
        subgraph "Core Engine"
            direction TB
            Processor["SentencePieceProcessorInterface"]:::native
            ModelFactory["model_factory"]:::native
            ModelInterface["model_interface"]:::native
        end
        subgraph "Trainer Modules"
            direction TB
            BPETrainer["bpe_model_trainer"]:::native
            CharTrainer["char_model_trainer"]:::native
            UnigramTrainer["unigram_model_trainer"]:::native
            TrainerFactory["trainer_factory"]:::native
            TrainerInterface["trainer_interface"]:::native
        end
        subgraph "Third-Party Libraries"
            direction TB
            Absl["absl"]:::native
            DartsClone["darts_clone"]:::native
            Esaxx["esaxx"]:::native
            ProtobufLite["protobuf-lite"]:::native
        end
        ModelFiles["Model Files"]:::ext
    end

    %% Flows: UI to Translator to JNI to Native to FS and back
    MainActivity -->|"send message"| Translator
    ConversationFragment --> Translator
    Translator --> Tokenizer
    Tokenizer -->|JNI Call| SWIGInterface
    SWIGInterface --> Wrapper
    Wrapper --> Processor
    Processor --> ModelFactory
    ModelFactory --> ModelInterface
    ModelInterface -->|load model| FileSystem
    FileSystem -->|model data| Processor
    Processor -->|result| Wrapper
    Wrapper --> Translator
    Translator --> Toast
    %% Bluetooth flow
    MainActivity -->|pair/connect| AndroidBluetoothAPI
    AndroidBluetoothAPI --> BluetoothStack
    BluetoothStack -->|remote peer| AndroidBluetoothAPI
    AndroidBluetoothAPI --> ConversationFragment

    %% JNI build dependencies
    CMake --> ConfigHeader

    %% Click events
    click MainActivity "https://github.com/niedev/neuralnetworkdemo/blob/master/app/src/main/java/com/bluetooth/communicatorexample/MainActivity.java"
    click ConversationFragment "https://github.com/niedev/neuralnetworkdemo/blob/master/app/src/main/java/com/bluetooth/communicatorexample/fragments/ConversationFragment.java"
    click PairingFragment "https://github.com/niedev/neuralnetworkdemo/blob/master/app/src/main/java/com/bluetooth/communicatorexample/fragments/PairingFragment.java"
    click MessagesAdapter "https://github.com/niedev/neuralnetworkdemo/blob/master/app/src/main/java/com/bluetooth/communicatorexample/gui/MessagesAdapter.java"
    click PeerListAdapter "https://github.com/niedev/neuralnetworkdemo/blob/master/app/src/main/java/com/bluetooth/communicatorexample/gui/PeerListAdapter.java"
    click Translator "https://github.com/niedev/neuralnetworkdemo/blob/master/app/src/main/java/com/bluetooth/communicatorexample/translation/Translator.java"
    click Tokenizer "https://github.com/niedev/neuralnetworkdemo/blob/master/app/src/main/java/com/bluetooth/communicatorexample/translation/Tokenizer.java"
    click CMake "https://github.com/niedev/neuralnetworkdemo/blob/master/app/src/main/cpp/CMakeLists.txt"
    click ConfigHeader "https://github.com/niedev/neuralnetworkdemo/blob/master/app/src/main/cpp/config.h.in"
    click Processor "https://github.com/niedev/neuralnetworkdemo/blob/master/app/src/main/cpp/src/SentencePieceProcessorInterface.cpp"
    click ModelFactory "https://github.com/niedev/neuralnetworkdemo/blob/master/app/src/main/cpp/src/model_factory.cc"
    click ModelInterface "https://github.com/niedev/neuralnetworkdemo/blob/master/app/src/main/cpp/src/model_interface.cc"
    click BPETrainer "https://github.com/niedev/neuralnetworkdemo/blob/master/app/src/main/cpp/src/bpe_model_trainer.cc"
    click CharTrainer "https://github.com/niedev/neuralnetworkdemo/blob/master/app/src/main/cpp/src/char_model_trainer.cc"
    click UnigramTrainer "https://github.com/niedev/neuralnetworkdemo/blob/master/app/src/main/cpp/src/unigram_model_trainer.cc"
    click TrainerFactory "https://github.com/niedev/neuralnetworkdemo/blob/master/app/src/main/cpp/src/trainer_factory.cc"
    click TrainerInterface "https://github.com/niedev/neuralnetworkdemo/blob/master/app/src/main/cpp/src/trainer_interface.cc"
    click Absl "https://github.com/niedev/neuralnetworkdemo/tree/master/app/src/main/cpp/third_party/absl"
    click DartsClone "https://github.com/niedev/neuralnetworkdemo/tree/master/app/src/main/cpp/third_party/darts_clone"
    click Esaxx "https://github.com/niedev/neuralnetworkdemo/tree/master/app/src/main/cpp/third_party/esaxx"
    click ProtobufLite "https://github.com/niedev/neuralnetworkdemo/tree/master/app/src/main/cpp/third_party/protobuf-lite"
    click SWIGInterface "https://github.com/niedev/neuralnetworkdemo/blob/master/app/src/main/cpp/python/src/sentencepiece/sentencepiece.i"
    click Wrapper "https://github.com/niedev/neuralnetworkdemo/blob/master/app/src/main/cpp/python/src/sentencepiece/sentencepiece_wrap.cxx"

    %% Styles
    classDef ui fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef business fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20
    classDef native fill:#FFE0B2,stroke:#E65100,color:#E65100
    classDef ext fill:#FFF9C4,stroke:#F57F17,color:#F57F17
    classDef os fill:#CFD8DC,stroke:#455A64,color:#455A64
    classDef jni fill:#F8BBD0,stroke:#880E4F,color:#880E4F
```
