# zantfoundation/z-ant architecture

> Architecture diagram of the GitHub repository zantfoundation/z-ant, 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/zantfoundation/z-ant
- Repository: https://github.com/zantfoundation/z-ant

## Overview

##### Project Identification
- Z-Ant is an open-source SDK built in Zig for deploying optimized neural networks on microcontrollers. Its aim is to provide real-time optimizations (quantization, pruning, buffer optimizations) and support multiple hardware targets (e.g., ARM Cortex-M, RISC-V) through a modular, code–generation-based approach.
- The project contains a mix of deep learning model processing (using ONNX files), code generation, core neural network computations, and utilities to support embedded inference.

##### File Structure
- Top-level directories like “src”, “datasets”, “docs”, and “tests” immediately reveal core components.
- Inside “src” there are distinct modules:
- CodeGen: Houses the logic for generating code from NN models including model-specific “hardcoded” examples. This is essential for converting ONNX models into optimized code.
- ONNX: Contains all key files and protocols for reading and processing ONNX representations, which serve as the input format for the NN models.
- Utils: Provide supporting functions such as memory allocation, error handling, and time/event logging.
- Other directories include “datasets” where pre-trained ONNX models and test outputs are stored, “docs” for developer and user guides (including Docker, style guides, etc.), and “tests” for verifying each of these subsystems.
- Configuration files like “build.zig”, the GitHub Actions workflows, and Docker-related files outline the project’s CI/CD and development environment.

a. Main Components:
- Code Generation Module (“src/CodeGen”): Converts models (from ONNX) into Zig source code, handles generation of test files, and creates model-specific libraries.
- Core Libraries (“src/Core”): Implements tensor operations, math functions for NN layers (such as convolution, gemm, pooling), and quantization.
- ONNX Interface (“src/onnx”): Parses and translates ONNX models into an internal representation that the CodeGen module can utilize.
- Utils (“src/Utils”): Provides cross-cutting concerns including memory management, error handling, and timing.
- Datasets (“datasets”): Contains sample and production models in ONNX format plus legacy models in custom formats (.zant) that are used as inputs to both testing and code generation.
- Build and Integration (build.zig, CI/CD config files in .github, Docker): Organizes build commands, test execution, containerization, and continuous integration that unify the development process.
- Tests (“tests”): Validate interactions within CodeGen, Core functionality, and ONNX interface.

b. Component Interactions:
- Input models (stored in “datasets”) are processed by the ONNX interface within “src/onnx” to extract structured data.
- The CodeGen module consumes this processed representation to generate Zig code tailored to deploy NN inference on microcontrollers.
- The generated code uses the Core libraries to perform optimized tensor computations and real-time inference.
- The Utils module supports each component by providing essential operations (memory, error handling, utility functions).
- CI/CD pipelines (GitHub workflows) trigger builds and tests, ensuring that components (e.g., CodeGen output, Core math operations) behave as expected.

c. Architectural Patterns and Design Principles:
- Modular Separation: Distinct directories for code generation, core computational kernels, and ONNX processing promote separation of concerns.
- Layered Architecture: The data flow starts from dataset inputs → ONNX parsing → code generation → optimized runtime execution.
- Extensibility and Reusability: The design supports adding new models (via additional datasets), extending tensor math libraries, and integrating new microcontroller targets.
- Cross-platform containerization and CI/CD reflect a modern development pipeline to maintain code quality.

d. Relevant Technologies:
- Zig Compiler & Build System are central to the project build process.
- ONNX format is supported through multiple modules (e.g., attributeProto.zig, modelProto.zig).
- Docker and GitHub Actions (with workflows for heavy and standard test suites) illustrate contemporary DevOps practices.
- Testing frameworks integrated in Zig are emphasized with a robust “tests” directory.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraph: Input & Preprocessing
    subgraph "Input & Preprocessing"
        DS["Datasets"]:::dataset
        ONNX["ONNX Interface"]:::model
    end

    %% Subgraph: Model Conversion
    subgraph "Model Conversion"
        CG["Code Generation Engine"]:::model
    end

    %% Subgraph: Runtime Execution
    subgraph "Runtime Execution"
        CC["Core Computation Library"]:::runtime
    end

    %% Utility Functions (support layer)
    UT["Utility Functions"]:::utils

    %% Subgraph: Infrastructure
    subgraph "Infrastructure"
        BCI["Build & CI/CD Pipeline"]:::infra
        GW["GitHub Workflows"]:::infra
        DCK["Docker Setup"]:::infra
        TS["Tests"]:::infra
    end

    %% Main vertical flow
    DS -->|"model_input"| ONNX
    ONNX -->|"processed_model"| CG
    CG -->|"generated_code"| CC

    %% Connections to Infrastructure
    DS -->|"deployment_flow"| BCI
    ONNX -->|"deployment_flow"| BCI
    CG -->|"deployment_flow"| BCI
    CC -->|"deployment_flow"| BCI
    UT -->|"support"| BCI

    BCI -->|"triggered_by"| GW
    BCI -->|"containerized_in"| DCK
    BCI -->|"validated_by"| TS

    %% Utility Functions support arrows
    UT ---|"supports"| DS
    UT ---|"supports"| ONNX
    UT ---|"supports"| CG
    UT ---|"supports"| CC

    %% Click Events
    click DS "https://github.com/zantfoundation/z-ant/tree/main/datasets"
    click ONNX "https://github.com/zantfoundation/z-ant/tree/main/src/onnx"
    click CG "https://github.com/zantfoundation/z-ant/tree/main/src/CodeGen"
    click CC "https://github.com/zantfoundation/z-ant/tree/main/src/Core"
    click UT "https://github.com/zantfoundation/z-ant/tree/main/src/Utils"
    click BCI "https://github.com/zantfoundation/z-ant/blob/main/build.zig"
    click GW "https://github.com/zantfoundation/z-ant/blob/main/.github/workflows/zig-tests.yml"
    click DCK "https://github.com/zantfoundation/z-ant/blob/main/.devcontainer"
    click TS "https://github.com/zantfoundation/z-ant/tree/main/tests"

    %% Styles
    classDef dataset fill:#F8BBD0,stroke:#333,stroke-width:2px;
    classDef model fill:#B3E5FC,stroke:#333,stroke-width:2px;
    classDef runtime fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef infra fill:#FFCCBC,stroke:#333,stroke-width:2px;
    classDef utils fill:#D1C4E9,stroke:#333,stroke-width:2px;
```
