# stmicroelectronics/stm32ai-modelzoo architecture

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

- Interactive diagram: https://gitdiagram.com/stmicroelectronics/stm32ai-modelzoo
- Repository: https://github.com/stmicroelectronics/stm32ai-modelzoo

## Overview

##### Project type and purpose
- This is an open-source “Model Zoo” repository that hosts hundreds of pre-trained ML models (H5/TFLite/ONNX) and configuration files, organized by use case (Image Classification, Object Detection, Audio Event Detection, etc.).
- It has no application code here; instead, it’s a content/artifact repository consumed by external tooling (the “stm32ai-modelzoo-services” dashboard, Hugging Face, STM32 boards).

##### File structure
- Top-level folders = “use cases” (audio_event_detection, image_classification, object_detection, …).
- Under each use-case folder are subfolders per model architecture (e.g. “efficientnet”, “miniresnet”, “ssd_mobilenet_v2_fpnlite”), and then “ST_pretrainedmodel_…” directories containing model files and YAML configs.
- A manifest.json at root and docs/images for high-level README visuals.
- There are no build scripts here: this repo relies on Git LFS for large files and is purely a content store.

##### README for additional insights
- The README describes integration with a separate “stm32ai-modelzoo-services” repo (Dash Plotly + Flask in Docker).
- Mentions Hugging Face hosting for model cards, and ST Edge AI Developer Cloud for benchmarking.
- Users clone via Git LFS, then point the dashboard or scripts at this repo to retrain, quantize, evaluate, benchmark, and generate application code for STM32 targets.

a. Main components
1. Model Zoo Repository (GitHub + Git LFS) – static content store for model binaries and config files.
2. Dashboard Service (stm32ai-modelzoo-services) –
- Backend: Flask REST API that reads the Model Zoo, drives training/evaluation pipelines.
- Frontend: Dash Plotly UI for visualization, user configuration, triggering tasks.
- Packaged as Docker container.
3. External Services
- ST Edge AI Developer Cloud – for automated benchmarking jobs.
- Hugging Face – for hosting model cards and additional diffusion.
4. User Devices / Targets
- Local developer machines (clone repo, run Docker or scripts).
- STM32 boards (STM32H7, STM32MP, STM32N6, microcontrollers running generated application code).

b. Relationships and interactions
- Developer → (git clone + Git LFS) → Model Zoo Repo
- Dashboard Service (in Docker) → pulls/clones or mounts the Model Zoo Repo
- Dashboard Service → calls ST Edge AI Developer Cloud API for benchmarking
- Dashboard Service → reads/writes to Hugging Face via HF APIs for model cards
- Developer UI (browser) → interacts with Dash Plotly frontend → calls Flask backend → interacts with Model Zoo and external services
- Generated application code → deployed onto STM32 boards via user’s toolchain

c. Architectural patterns and design principles
- Separation of concerns: Content Repository vs. Service layer vs. Visualization layer
- Containerization: Docker for environment standardization
- RESTful API: Flask backend exposes endpoints for train/eval/benchmark
- Extensibility: New models can be added by dropping folders into the repo; dashboard auto-discovers them
- External integration: Uses cloud APIs (ST Edge AI), HF APIs

d. Key technologies & frameworks
- Git + Git LFS (model storage)
- Docker (containerization)
- Python Flask (backend)
- Dash Plotly (frontend)
- ST Edge AI Developer Cloud (benchmarking)
- Hugging Face (model hosting, model cards)

##### Final advice
- Every essential element but group similar model folders under “Model Zoo Content Store”

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors and hardware
    Developer["Developer Machine"]:::hardware
    STM32Boards["STM32 Boards"]:::hardware

    %% Content repository
    ModelZooRepo["Model Zoo Repository"]:::internal
    Manifest["manifest.json"]:::internal
    README["README.md"]:::internal
    DocImgs["doc/img/"]:::internal
    subgraph "Use-Case Folders"
        Audio["audio_event_detection/"]:::internal
        ImageC["image_classification/"]:::internal
        Object["object_detection/"]:::internal
        Pose["pose_estimation/"]:::internal
        SemSeg["semantic_segmentation/"]:::internal
        HAR["human_activity_recognition/"]:::internal
        HandPosture["hand_posture/"]:::internal
        InstanceSeg["instance_segmentation/"]:::internal
        SpeechEnh["speech_enhancement/"]:::internal
    end

    %% Dashboard service
    subgraph "Dashboard Service (Docker Container)" 
        DashFrontend["Dash Plotly UI"]:::internal
        FlaskBackend["Flask REST API"]:::internal
    end

    %% External services
    STCloud["ST Edge AI Developer Cloud"]:::external
    HuggingFace["Hugging Face"]:::external

    %% Connections
    Developer -->|"git clone + Git LFS"| ModelZooRepo
    Developer -->|"run Docker"| DashFrontend
    DashFrontend -->|"HTTP requests"| FlaskBackend
    ModelZooRepo -->|"mount/clone"| FlaskBackend
    FlaskBackend -->|"benchmark requests"| STCloud
    FlaskBackend -->|"HF API: update model card"| HuggingFace
    FlaskBackend -->|"generate code"| STM32Boards

    %% Click events
    click ModelZooRepo "https://github.com/stmicroelectronics/stm32ai-modelzoo/blob/main/."
    click Manifest "https://github.com/stmicroelectronics/stm32ai-modelzoo/blob/main/manifest.json"
    click README "https://github.com/stmicroelectronics/stm32ai-modelzoo/blob/main/README.md"
    click DocImgs "https://github.com/stmicroelectronics/stm32ai-modelzoo/tree/main/doc/img/"
    click Audio "https://github.com/stmicroelectronics/stm32ai-modelzoo/tree/main/audio_event_detection/"
    click ImageC "https://github.com/stmicroelectronics/stm32ai-modelzoo/tree/main/image_classification/"
    click Object "https://github.com/stmicroelectronics/stm32ai-modelzoo/tree/main/object_detection/"
    click Pose "https://github.com/stmicroelectronics/stm32ai-modelzoo/tree/main/pose_estimation/"
    click SemSeg "https://github.com/stmicroelectronics/stm32ai-modelzoo/tree/main/semantic_segmentation/"
    click HAR "https://github.com/stmicroelectronics/stm32ai-modelzoo/tree/main/human_activity_recognition/"
    click HandPosture "https://github.com/stmicroelectronics/stm32ai-modelzoo/tree/main/hand_posture/"
    click InstanceSeg "https://github.com/stmicroelectronics/stm32ai-modelzoo/tree/main/instance_segmentation/"
    click SpeechEnh "https://github.com/stmicroelectronics/stm32ai-modelzoo/tree/main/speech_enhancement/"

    %% Styles
    classDef internal fill:#BBDEFB,stroke:#1976D2,stroke-width:2px
    classDef external fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px
    classDef hardware fill:#FFE0B2,stroke:#E65100,stroke-width:2px
```
