# sumon-98/nntrainer architecture

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

- Interactive diagram: https://gitdiagram.com/sumon-98/nntrainer
- Repository: https://github.com/sumon-98/nntrainer

## Overview

##### Project Type and Purpose
- Project Type: A cross-platform, embedded-focused machine-learning training framework (native C++ core with C/C++ APIs, JNI wrappers, and example Android/Tizen applications).
- Purpose: Provide on-device neural-network training and fine-tuning, exposing functionality via C and C++ APIs (and JNI for Java), supporting multiple backends (CPU/ARM/OpenCL/GGML), and integrating with NNStreamer.

##### File Structure to Extract Architectural Layers
Top-level directories:
- api/      → C API (capi) and C++ API (ccapi) layers
- nntrainer/→ Core library: compiler, graph, engine, layers, optimizers, tensor, utils, opencl delegate
- nnstreamer/ → Plugin integration for NNStreamer
- jni/       → JNI build scripts for Android
- Applications/ → Example clients on Android/PC/Tizen
- subprojects/ → Third-party dependencies (OpenBLAS, CLBlast, ONNXConverter, ggml, ruy)
- packaging/ → Deployment manifests and tarballs
- test/      → Unit and integration tests
- benchmarks/→ Performance benchmarks

##### README for Additional Insights
- Core functionality: model definition via INI, realizer/compiler interpreters for .ini, ONNX, TFLite
- Execution: Engine drives forward/backward passes, using tensor backends and memory managers
- Extensibility: plugin-style layers and optimizers, delegate interfaces for hardware acceleration
- APIs:
– C API (Tizen focus)
– C++ ccapi
– JNI wrappers enable Java/Android clients

##### Main Components & Their Relationships
a. User/Application Layer
– Example apps (Applications/) or custom clients
– On Android: Java/Kotlin → JNI → native C/C++ API
b. API Layer
– C API (api/capi) and C++ API (api/ccapi)
– Exposes model setup, training loops, callbacks
c. Core Library (nntrainer/)
– Compiler/Model Loader: parse .ini or import ONNX/TFLite → build graph
– Graph Module: network_graph, connection, graph_core
– Engine: orchestrates forward/backprop, uses delegate to select backend
– Layers: collection of built-in and plugin layers
– Optimizers: SGD, Adam, AdamW + LR schedulers
– Dataset: data producers, iterators, buffers
– Tensor Module: tensor abstraction + multiple backends (CPU, ARM neon, CBLAS, fallback, GGML, OpenCL via cl_interface)
– Memory Manager: planners and pools
– Utils: profiling, threading, ini parsing, dynamic loader
d. Delegate/Backend Layer
– CPU backends (x86, ARM)
– OpenCL delegate (nntrainer/opencl)
– External libs: OpenBLAS, CLBlast, ggml, ruy
– ONNX/TFLite interpreters
e. Plugin Integration
– nnstreamer plugin (nnstreamer/tensor_filter, tensor_trainer)
f. Build & Packaging
– Meson build definitions throughout
– JNI build scripts (Android.mk, Application.mk)
– CI/CD workflows (.github/)
– Packaging manifests for Tizen, Ubuntu, Android

##### Architectural Patterns & Design Principles
- Modular layered architecture: separation of API, core engine, and hardware delegates.
- Plugin-style extensibility: layers, optimizers, backends plug into core via common interfaces.
- Data-flow graph pattern: model represented as a computational graph, executed by Engine.
- Strategy pattern for tensor backends and optimizers.
- Factory patterns in dataset and layer creation.

##### Elements
– From Application down to API
– From API to Core (Compiler/Graph/Engine)
– From Engine to Tensor/Memory Manager to Delegate/Backend
– API layer (e.g., blue)
– Core engine (e.g., green)
– Hardware delegates/external libraries (e.g., orange)
– JNI/Android path (e.g., purple)
- Annotations or callouts for plugin/extensibility points

##### Final Advice
- Plugin interfaces for layers, optimizers, and tensor backends.
- Don’t over-optimize—break down the monolith into cohesive modules.
- Use a layered, top-down view:
1. Client/Application
2. API layer
3. Core engine (with submodules)
4. Delegate/backends & external dependencies
5. Build/CI/Packaging

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client/Application Layer"
        App["Applications"]:::app
    end

    subgraph "Android JNI Path"
        JNI["JNI Wrappers"]:::jni
    end

    subgraph "API Layer"
        CAPI["C API"]:::api
        CCAPI["C++ API"]:::api
    end

    subgraph "Core Library"
        Compiler["Compiler / Model Loader"]:::core
        MI["Models Interface"]:::core
        Graph["Graph Module"]:::core
        Engine["Engine"]:::core
        Layers["Layers Module"]:::core
        Opt["Optimizers Module"]:::core
        DataSet["Dataset Module"]:::core
        Tensor["Tensor Module"]:::core
        Mem["Memory Manager"]:::core
        Utils["Utilities"]:::core
    end

    subgraph "Delegate/Backends"
        CPU["CPU Backends"]:::backend
        OpenCL["OpenCL Delegate"]:::backend
        ExtLib["External Libs"]:::backend
    end

    subgraph "NNStreamer Plugin"
        TF["tensor_filter"]:::plugin
        TT["tensor_trainer"]:::plugin
    end

    subgraph "Build & Packaging"
        SP["Subprojects"]:::build
        PKG["Packaging"]:::build
        CI["Build & CI Definitions"]:::build
        Tests["Unit & Integration Tests"]:::build
        Bench["Benchmarks"]:::build
    end

    App -->|"calls"| CAPI
    App -->|"calls"| CCAPI
    JNI -->|"native API calls"| CAPI
    JNI -->|"native API calls"| CCAPI
    CAPI -->|"model setup"| Compiler
    CCAPI -->|"model setup"| Compiler
    Compiler -->|"uses model defs"| MI
    MI -->|"builds graph"| Graph
    Graph -->|"executes graph"| Engine
    Engine -->|"manages layers"| Layers
    Engine -->|"manages optimizers"| Opt
    Engine -->|"manages data"| DataSet
    Engine -->|"processes tensors"| Tensor
    Tensor -->|"allocates memory"| Mem
    Tensor -->|"runs on CPU"| CPU
    Tensor -->|"runs on OpenCL"| OpenCL
    Tensor -->|"uses external libs"| ExtLib
    Engine -->|"integrates plugin"| TF
    Engine -->|"integrates plugin"| TT
    SP -->|"provides libs"| ExtLib
    PKG -->|"packages builds"| CI
    CI -->|"runs tests"| Tests
    CI -->|"runs benchmarks"| Bench

    classDef api fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef core fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef backend fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef jni fill:#DA70D6,stroke:#000,stroke-width:1px;
    classDef app fill:#D3D3D3,stroke:#000,stroke-width:1px;
    classDef plugin fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef build fill:#F08080,stroke:#000,stroke-width:1px;

    click App "https://github.com/sumon-98/nntrainer/tree/main/Applications/"
    click JNI "https://github.com/sumon-98/nntrainer/tree/main/jni/"
    click CAPI "https://github.com/sumon-98/nntrainer/tree/main/api/capi/"
    click CCAPI "https://github.com/sumon-98/nntrainer/tree/main/api/ccapi/"
    click Compiler "https://github.com/sumon-98/nntrainer/tree/main/nntrainer/compiler/"
    click MI "https://github.com/sumon-98/nntrainer/tree/main/nntrainer/models/"
    click Graph "https://github.com/sumon-98/nntrainer/tree/main/nntrainer/graph/"
    click Engine "https://github.com/sumon-98/nntrainer/blob/main/nntrainer/engine.cpp"
    click Engine "https://github.com/sumon-98/nntrainer/blob/main/nntrainer/engine.h"
    click Layers "https://github.com/sumon-98/nntrainer/tree/main/nntrainer/layers/"
    click Opt "https://github.com/sumon-98/nntrainer/tree/main/nntrainer/optimizers/"
    click DataSet "https://github.com/sumon-98/nntrainer/tree/main/nntrainer/dataset/"
    click Tensor "https://github.com/sumon-98/nntrainer/tree/main/nntrainer/tensor/"
    click Mem "https://github.com/sumon-98/nntrainer/blob/main/nntrainer/mem_allocator.cpp"
    click Mem "https://github.com/sumon-98/nntrainer/blob/main/nntrainer/mem_allocator.h"
    click Utils "https://github.com/sumon-98/nntrainer/tree/main/nntrainer/utils/"
    click OpenCL "https://github.com/sumon-98/nntrainer/tree/main/nntrainer/opencl/"
    click TF "https://github.com/sumon-98/nntrainer/tree/main/nnstreamer/tensor_filter/"
    click TT "https://github.com/sumon-98/nntrainer/tree/main/nnstreamer/tensor_trainer/"
    click SP "https://github.com/sumon-98/nntrainer/tree/main/subprojects/"
    click PKG "https://github.com/sumon-98/nntrainer/tree/main/packaging/"
    click Tests "https://github.com/sumon-98/nntrainer/tree/main/test/"
    click Bench "https://github.com/sumon-98/nntrainer/tree/main/benchmarks/"
    click CI "https://github.com/sumon-98/nntrainer/tree/main/.github/"
    click CI "https://github.com/sumon-98/nntrainer/blob/main/meson.build"
```
