# kitajussus/z-ant architecture

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

- Interactive diagram: https://gitdiagram.com/kitajussus/z-ant
- Repository: https://github.com/kitajussus/z-ant

## Overview

##### Project Type and Purpose
- Z-Ant is a neural network deployment and optimization SDK focused on microcontroller environments (e.g., ARM Cortex-M, Raspberry Pi Pico).
- The project covers tasks like quantization, pruning, buffer optimization, and code generation for deploying lightweight NN models.
- It also provides deep support for processing ONNX models, transforming them through code generation modules to create static libraries for embedded devices.

##### File Structure to Extract Architectural Components
- The top-level directories and files show clear separation between:
- Project configuration and CI/CD: .devcontainer, .github, build.zig, and other configuration files.
- Datasets: Contains sample models and ONNX files in various subdirectories. This indicates that the project is data-driven with standardized model formats.
- Source Files (src): The heart of the SDK, divided mainly into:
o Code Generation (src/CodeGen): Contains scripts and modules (e.g., codegen.zig, predict.zig, shape_handler.zig) responsible for converting NN models into target code.
o Core Operations (src/Core): Implements tensor operations, quantization routines, and neural network computations. The extensive tensor math libraries (e.g., convolution, pooling, matrix multiplication, element-wise operators) are housed here.
o ONNX Parsing (src/onnx): Provides definitions and handling for ONNX protocol buffers (modelProto, tensorProto, etc.). This module transforms incoming ONNX data into internal representations.
o Utilities (src/Utils): Common helper modules for memory allocation, error handling, and type conversions.
o Main Entry (src/main.zig & src/zant.zig): High-level orchestration of the SDK’s functionality.
- Tests: A well-organized tests directory covering functionality in CodeGen, Core, and Utility modules, ensuring unit and heavy tests are clearly separated.
- Documentation (docs): Holds guides and technical details (e.g., How_TO_DOCKER, layers, tensor math) that are instrumental in understanding deployment and integration.

##### README for Additional Insights
- The README clarifies the SDK’s focus on real-time optimization, cross-platform compatibility, and end-to-end integration from model parsing to static-library generation.
- It gives clear instructions for generating code, testing models, and integrating the generated library via CMake.

(a) Main Components to Include:
- Input/Model Repository:
▪ Datasets: ONNX models and custom formats (the datasets directory).
- Model Import and Parsing:
▪ ONNX Module (src/onnx) for ingesting and translating ONNX models.
- Code Generation Module:
▪ CodeGen (src/CodeGen): Generates model-specific source code (including hardcoded examples).
- Core Computation Engine:
▪ Core (src/Core): This is split into tensor operations, quantization procedures, and NN-specific mathematical functions.
- Utilities:
▪ Helper libraries (src/Utils) that support memory allocation, error management, and logging.
- Build and Testing:
▪ Build scripts (build.zig, provided CI/CD pipelines from .github, and Docker configuration) are essential for cross-compilation and testing.
- Integration/Output Layer:
▪ Generated code libraries (public APIs, static libraries) that can be linked to embedded applications.
- CI/CD Pipeline:
▪ GitHub workflows and Docker configurations that enforce continuous testing and integration.

(b) Relationships and Interactions Between Components:
- The process begins with ingesting an ONNX model from the Datasets.
- The ONNX module parses the model and forwards the representation to the CodeGen module.
- The CodeGen module integrates the parsed information and employs components from the Core (tensor math, quantization, etc.) to produce optimized code.
- The output is then prepared as a static library or code snippet, which is integrated via build tools (references to build.zig commands for lib and tests).
- Utilities support various functions across modules.
- The CI/CD pipeline (organized in .github workflows and Docker configurations) continuously integrates and validates these interactions.

(c) Highlighting Architectural Patterns and Technologies:
- Modular Architecture: Separation of concerns among model parsing, code generation, and computation.
- Layered Design: Clearly defined layers (data ingestion, processing, code generation, and integration) promote maintainability.
- Emphasis on Build Options: Flags for logging, heavy computational tests, and dynamic code generation indicate adaptable builds.
- Use of Zig as the primary language ensures tight integration across components.
- CI/CD and Containerization: Ensures robust testing and consistent deployment across various hardware targets.

##### Final Touches
- Callouts for important build commands and options (as seen in build.zig) to demonstrate how developers trigger specific workflows (e.g., “zig build codegen”, “zig build lib”).
- On future roadmap items (like improved pruning, frontend GUI integration) if desired, either as annotations or as separate components indicating planned extensions.
- Detail without overcomplicating: capture the essential flow and modularity while ensuring each component and its relationships are clear.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Input and Parsing Layer"
        Datasets["Dataset Repository (Models)"]:::ingest
        ONNX["ONNX Parsing Module"]:::parser
    end

    subgraph "Processing and Code Generation Layer"
        CodeGen["Code Generation Engine"]:::codegen
        Core["Core Computation Engine"]:::core
    end

    subgraph "Support & Integration Layer"
        Utils["Utility Modules"]:::utils
        Main["Main Entry Orchestration"]:::main
        Build["Build and CI/CD Setup"]:::build
        Testing["Testing Suite"]:::test
    end

    Datasets -->|"ingestsModels"| ONNX
    ONNX -->|"parsedModelData"| CodeGen
    CodeGen -->|"utilizesCoreOps"| Core
    Main -->|"orchestrates"| ONNX
    Main -->|"triggersCodeGen"| CodeGen
    Utils -->|"supportsONNX"| ONNX
    Utils -->|"supportsCodeGen"| CodeGen
    Utils -->|"supportsCore"| Core
    CodeGen -->|"generatesCode"| Build
    Build -->|"runsTests"| Testing

    click Datasets "https://github.com/kitajussus/z-ant/tree/main/datasets/"
    click ONNX "https://github.com/kitajussus/z-ant/tree/main/src/onnx/"
    click CodeGen "https://github.com/kitajussus/z-ant/tree/main/src/CodeGen/"
    click Core "https://github.com/kitajussus/z-ant/tree/main/src/Core/"
    click Utils "https://github.com/kitajussus/z-ant/tree/main/src/Utils/"
    click Main "https://github.com/kitajussus/z-ant/blob/main/src/main.zig & src/zant.zig"
    click Build "https://github.com/kitajussus/z-ant/tree/main/build.zig & .github/workflows/"
    click Testing "https://github.com/kitajussus/z-ant/tree/main/tests/"

    classDef ingest fill:#D6EAF8,stroke:#2874A6,stroke-width:2px;
    classDef parser fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef codegen fill:#FADBD8,stroke:#CD6155,stroke-width:2px;
    classDef core fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef utils fill:#D5F5E3,stroke:#28B463,stroke-width:2px;
    classDef main fill:#FDEBD0,stroke:#D35400,stroke-width:2px;
    classDef build fill:#F0F3F4,stroke:#5D6D7E,stroke-width:2px;
    classDef test fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
```
