# stac-extensions/mlm architecture

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

- Interactive diagram: https://gitdiagram.com/stac-extensions/mlm
- Repository: https://github.com/stac-extensions/mlm

## Overview

##### Main Components and Their Roles
- Specification & Documentation:
- Documentation directories (docs, best-practices.md, multiple README files) that describe the extension’s purpose, usage, and best practices.
- The JSON schema (located in the json-schema directory) that formally defines the validation rules for ML model metadata.
- Python Package (stac_model):
- Contains the implementation of the specification using Python. It uses Pydantic models for input/output structure, and PySTAC connectors to integrate with STAC Items and Collections.
- Modules such as base.py, input.py, output.py, schema.py, runtime.py help enforce structure and support conversion and validation of STAC records.
- Examples:
- Example JSON files in the examples directory that illustrate real-world usage of the extension across various model cases.
- Testing and CI/CD Infrastructure:
- The tests directory and configuration files exemplify automated testing (npm, pre-commit, GitHub workflows such as test.yaml, publish.yaml, and release-drafter.yml) to ensure quality and consistency.
- Configuration/build files like package.json, pyproject.toml, Makefile, and pre-commit-config.yaml outline build and deployment processes.
- Versioning and Contribution:
- Additional files like CHANGELOG.md, CONTRIBUTING.md, and the CITATION.cff indicate that versioning, contribution guidelines, and citation information are maintained for community engagement.

##### Relationships and Interactions Between Components
- The core specification (JSON schema and Python models) is central. The Python library (stac_model) is responsible for interpreting and validating the machine learning model metadata as defined by the schema.
- Documentation and examples illustrate how to use the specification and validate STAC ML metadata. They are “consumers” of the core schema and the Python package.
- The CI/CD pipelines (GitHub Workflows) automatically run tests (via npm and other scripts) whenever changes are committed. They interact with both the codebase and documentation (e.g., checking markdown formatting, validating examples against the schema).
- Build scripts (Makefile and package.json) and configuration files (pre-commit hooks, pyproject.toml) ensure consistent development practices and automated validation.
- Assets (model files, source code assets, container definitions) are referenced within the STAC Items as described by the specification, and are part of the broader ecosystem enabled by the extension.

##### Architectural Patterns and Technology Stack
- The design follows a modular, specification-driven architecture. It separates concerns between declaration (JSON schema, documentation) and implementation (Python code and tests).
- Use of Pydantic and PySTAC for schema definition and data validation promotes strict type checking and adherence to the STAC specification.
- CI/CD pipelines (YAML GitHub workflows) orchestrate automated testing, code quality checks, and release processes.
- Integration of community best practices is evident through the use of GitHub configuration files, issue/PR templates, and standard package management (npm, pyproject.toml).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Documentation & Specifications
    subgraph "Documentation & Specifications"
        DOC1["Documentation Files"]:::docs
        DOC2["JSON Schema"]:::docs
    end

    %% Python Package (stac_model)
    subgraph "Python Package (stac_model)"
        PKG1["stac_model (Directory)"]:::python_pkg
        PKG2["base.py"]:::python_pkg
        PKG3["input.py"]:::python_pkg
        PKG4["output.py"]:::python_pkg
        PKG5["runtime.py"]:::python_pkg
        PKG6["schema.py"]:::python_pkg
    end

    %% Examples
    subgraph "Examples"
        EX["Example JSON Files"]:::examples
    end

    %% Testing & CI/CD
    subgraph "Testing & CI/CD"
        TEST["Tests Directory"]:::testing
        WF["GitHub Workflows"]:::testing
        BT["Build Tools & Config"]:::testing
    end

    %% Development & Versioning
    subgraph "Development & Versioning"
        DEV["Versioning & Contributions"]:::dev
    end

    %% Relationships and Connections
    DOC1 -->|"derives"| PKG1
    DOC2 -->|"validates"| PKG1

    PKG1 -->|"implemented_by"| PKG2
    PKG1 -->|"implemented_by"| PKG3
    PKG1 -->|"implemented_by"| PKG4
    PKG1 -->|"implemented_by"| PKG5
    PKG1 -->|"implemented_by"| PKG6

    EX -->|"demonstrates"| DOC1
    EX -->|"demonstrates"| PKG1

    TEST -->|"tests"| DOC1
    TEST -->|"tests"| PKG1
    TEST -->|"tests"| EX
    TEST -->|"tests"| DEV

    WF -->|"automates"| DOC1
    WF -->|"automates"| PKG1
    WF -->|"automates"| EX
    WF -->|"automates"| DEV

    BT -->|"builds"| DOC1
    BT -->|"builds"| PKG1
    BT -->|"builds"| EX
    BT -->|"builds"| DEV

    DEV -->|"guides"| DOC1

    %% Click Events
    click DOC1 "https://github.com/stac-extensions/mlm/blob/main/README.md"
    click DOC2 "https://github.com/stac-extensions/mlm/blob/main/json-schema/schema.json"
    click PKG1 "https://github.com/stac-extensions/mlm/tree/main/stac_model/"
    click PKG2 "https://github.com/stac-extensions/mlm/blob/main/stac_model/base.py"
    click PKG3 "https://github.com/stac-extensions/mlm/blob/main/stac_model/input.py"
    click PKG4 "https://github.com/stac-extensions/mlm/blob/main/stac_model/output.py"
    click PKG5 "https://github.com/stac-extensions/mlm/blob/main/stac_model/runtime.py"
    click PKG6 "https://github.com/stac-extensions/mlm/blob/main/stac_model/schema.py"
    click EX "https://github.com/stac-extensions/mlm/tree/main/examples/"
    click TEST "https://github.com/stac-extensions/mlm/tree/main/tests/"
    click WF "https://github.com/stac-extensions/mlm/tree/main/.github/workflows/"
    click BT "https://github.com/stac-extensions/mlm/tree/main/Makefile"
    click DEV "https://github.com/stac-extensions/mlm/blob/main/CHANGELOG.md"

    %% Styles
    classDef docs fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef python_pkg fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef examples fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef testing fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef dev fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
```
