# borgwang/tinynn architecture

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

- Interactive diagram: https://gitdiagram.com/borgwang/tinynn
- Repository: https://github.com/borgwang/tinynn

## Overview

##### Project Type and Purpose
- tinynn is a lightweight deep learning framework primarily intended for educational purposes and quick prototyping of neural network models.
- The README and file structure emphasize core deep learning functionality (like models, layers, optimizers, and loss functions) as well as supporting utilities (data iterators, datasets, math, etc.).
- Additionally, various examples (MNIST, GANs, reinforcement learning, etc.) showcase its use in different deep learning scenarios.

##### File Structure
- Top-Level Components:
- tinynn/   → This is the core library package. It contains the main code for building and training neural networks.
▪ tinynn/core/ contains the essential components (initializer, layer, loss, model, net, optimizer).
▪ tinynn/utils/ contains helper functions and modules for data handling (data_iterator, dataset, downloader), mathematical operations, metrics, random seeding, and parameter structuring.
- examples/ → Contains multiple sub-projects that illustrate different use cases (binary classification, autoencoder, GANs, distributed training, reinforcement learning, word2vec, etc.).
- tests/ → Organized into subdirectories (core, others, utils) to ensure the functionality of both the core framework and its utilities.
- Other files (setup.py, .github, configuration files, etc.) indicate CI/CD setups and package management requirements.

##### Essential Components
a. Core Deep Learning Engine
- Components: Initializer, Layer, Loss, Model, Net, Optimizer
- How a user constructs a network by defining layers and models and then utilizes loss functions and optimizers to train the network.
b. Utility Module
- Components: Data Iterator, Dataset, Downloader, Math, Metric, Seeder, Structured Param
- How these utilities support the core engine for handling data, mathematical operations, and parameter management.
c. Examples & Demos
- Components: Different example projects (e.g., MNIST classification, DCGAN, reinforcement learning, etc.)
- How they interact with the core engine and utilities by constructing networks and invoking training procedures.
d. Testing Suite
- Components: Tests divided into core tests, utility tests, and additional functionality tests.
- Role of automated testing (with pytest and CI tools) that ensures code quality and correctness.
e. External Tools and CI/CD
- Components: GitHub Workflows, Codecov integration, license, and versioning files.
- To illustrate how the framework is maintained and continuously integrated, though they are less central to the runtime architecture.

##### Relationships and Interactions
- From the Examples to the Core Engine: Illustrate that the demos invoke APIs in tinynn’s core components.
- Within the Core Engine: Connect the process flow from defining a network (using layers and initializers), passing data through models, computing losses, and updating weights via optimizers.
- From the Utility Module: Indicate how pre-processing, data iteration, and mathematical functions support model training.
- Testing modules should wrap around core components, ensuring that individual pieces (e.g. layers, optimizers) work as expected.

##### Architectural Patterns and Design Principles
- The design follows a modular architecture: The core deep learning logic is encapsulated in well-defined modules separated by functionality (e.g., core vs. utils).
- There is a clear separation of concerns with examples being independent demonstration projects that rely on the lightweight core framework.
- Reusability and testability as seen in the structured test directories and README’s encouragement of contributions.

- How the example applications access functions in the core library to define and train models.
- How utilities assist with data management and computation.
- Continuous integration elements (e.g., GitHub workflows) to show the engineering practices in place.
- Every component is detailed with annotations explaining its role, purpose, and the technologies/frameworks (Python, PyTest, GitHub Actions) used.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Framework Core
    subgraph "Framework Core (tinynn/core)"
        CR1["Initializer"]:::core
        CR2["Layer"]:::core
        CR3["Loss"]:::core
        CR4["Model"]:::core
        CR5["Net"]:::core
        CR6["Optimizer"]:::core
    end

    %% Supporting Utilities
    subgraph "Supporting Utilities (tinynn/utils)"
        UT1["Data Iterator"]:::utils
        UT2["Dataset"]:::utils
        UT3["Downloader"]:::utils
        UT4["Math"]:::utils
        UT5["Metric"]:::utils
        UT6["Seeder"]:::utils
        UT7["Structured Param"]:::utils
    end

    %% Examples & Demos
    subgraph "Examples & Demos (examples)"
        EX1["Binary Classification"]:::examples
        EX2["DAE"]:::examples
        EX3["DCGAN"]:::examples
        EX4["Distributed Training"]:::examples
        EX5["Knowledge Distillation"]:::examples
        EX6["MNIST"]:::examples
        EX7["NN Paint"]:::examples
        EX8["Reinforcement Learning"]:::examples
        EX9["Word2Vec"]:::examples
    end

    %% Testing Suite
    subgraph "Testing Suite (tests)"
        TS1["Core Tests"]:::tests
        TS2["Utility Tests"]:::tests
        TS3["Others Tests"]:::tests
    end

    %% CI/CD and External Tools
    subgraph "CI/CD and External Tools"
        CI1["GitHub Workflows (.github/workflows)"]:::external
        CI2["Configuration Files"]:::external
    end

    %% Internal Core Flow
    CR1 -->|"definesLayer"| CR2
    CR2 -->|"processes"| CR3
    CR3 -->|"feedsTo"| CR4
    CR4 -->|"builds"| CR5
    CR5 -->|"optimizedBy"| CR6

    %% Utilities support Core functionalities
    UT1 -->|"feedsData"| CR4
    UT2 -->|"providesData"| CR4
    UT3 -->|"downloadsData"| UT2
    UT4 -->|"calculates"| CR3
    UT5 -->|"evaluates"| CR4
    UT6 -->|"setsSeed"| CR1
    UT7 -->|"structuresParams"| CR4

    %% Examples invoke Core APIs
    EX1 -->|"callsAPIs"| CR4
    EX2 -->|"callsAPIs"| CR4
    EX3 -->|"callsAPIs"| CR4
    EX4 -->|"callsAPIs"| CR4
    EX5 -->|"callsAPIs"| CR4
    EX6 -->|"callsAPIs"| CR4
    EX7 -->|"callsAPIs"| CR4
    EX8 -->|"callsAPIs"| CR4
    EX9 -->|"callsAPIs"| CR4

    %% Testing validates both Core and Utilities (and Examples)
    TS1 -->|"validates"| CR1
    TS1 -->|"validates"| CR2
    TS1 -->|"validates"| CR3
    TS1 -->|"validates"| CR4
    TS2 -->|"checks"| UT1
    TS2 -->|"checks"| UT2
    TS2 -->|"checks"| UT3
    TS2 -->|"checks"| UT4
    TS2 -->|"checks"| UT5
    TS2 -->|"checks"| UT6
    TS2 -->|"checks"| UT7
    TS3 -->|"ensuresCoverage"| EX1
    TS3 -->|"ensuresCoverage"| EX2
    TS3 -->|"ensuresCoverage"| EX3
    TS3 -->|"ensuresCoverage"| EX4
    TS3 -->|"ensuresCoverage"| EX5
    TS3 -->|"ensuresCoverage"| EX6
    TS3 -->|"ensuresCoverage"| EX7
    TS3 -->|"ensuresCoverage"| EX8
    TS3 -->|"ensuresCoverage"| EX9

    %% CI/CD triggers testing
    CI1 -->|"triggersTests"| TS1
    CI1 -->|"triggersTests"| TS2
    CI1 -->|"triggersTests"| TS3
    CI2 -->|"configuresCI"| CI1

    %% Click Events for Core Deep Learning Engine
    click CR1 "https://github.com/borgwang/tinynn/blob/master/tinynn/core/initializer.py"
    click CR2 "https://github.com/borgwang/tinynn/blob/master/tinynn/core/layer.py"
    click CR3 "https://github.com/borgwang/tinynn/blob/master/tinynn/core/loss.py"
    click CR4 "https://github.com/borgwang/tinynn/blob/master/tinynn/core/model.py"
    click CR5 "https://github.com/borgwang/tinynn/blob/master/tinynn/core/net.py"
    click CR6 "https://github.com/borgwang/tinynn/blob/master/tinynn/core/optimizer.py"

    %% Click Events for Utility Module
    click UT1 "https://github.com/borgwang/tinynn/blob/master/tinynn/utils/data_iterator.py"
    click UT2 "https://github.com/borgwang/tinynn/blob/master/tinynn/utils/dataset.py"
    click UT3 "https://github.com/borgwang/tinynn/blob/master/tinynn/utils/downloader.py"
    click UT4 "https://github.com/borgwang/tinynn/blob/master/tinynn/utils/math.py"
    click UT5 "https://github.com/borgwang/tinynn/blob/master/tinynn/utils/metric.py"
    click UT6 "https://github.com/borgwang/tinynn/blob/master/tinynn/utils/seeder.py"
    click UT7 "https://github.com/borgwang/tinynn/blob/master/tinynn/utils/structured_param.py"

    %% Click Events for Examples & Demos
    click EX1 "https://github.com/borgwang/tinynn/tree/master/examples/binary_classification"
    click EX2 "https://github.com/borgwang/tinynn/tree/master/examples/dae"
    click EX3 "https://github.com/borgwang/tinynn/tree/master/examples/dcgan"
    click EX4 "https://github.com/borgwang/tinynn/tree/master/examples/distributed_training"
    click EX5 "https://github.com/borgwang/tinynn/tree/master/examples/knowledge_distillation"
    click EX6 "https://github.com/borgwang/tinynn/tree/master/examples/mnist"
    click EX7 "https://github.com/borgwang/tinynn/tree/master/examples/nn_paint"
    click EX8 "https://github.com/borgwang/tinynn/tree/master/examples/rl"
    click EX9 "https://github.com/borgwang/tinynn/tree/master/examples/word2vec"

    %% Click Events for Testing Suite
    click TS1 "https://github.com/borgwang/tinynn/tree/master/tests/core"
    click TS2 "https://github.com/borgwang/tinynn/tree/master/tests/utils"
    click TS3 "https://github.com/borgwang/tinynn/tree/master/tests/others"

    %% Click Events for CI/CD and External Tools
    click CI1 "https://github.com/borgwang/tinynn/tree/master/.github/workflows"
    click CI2 "https://github.com/borgwang/tinynn/blob/master/.codecov.yml"

    %% Styles
    classDef core fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef utils fill:#87CEFA,stroke:#4682B4,stroke-width:2px;
    classDef examples fill:#90EE90,stroke:#32CD32,stroke-width:2px;
    classDef tests fill:#FFB6C1,stroke:#FF69B4,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#808080,stroke-width:2px;
```
