# instill-ai/package architecture

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

- Interactive diagram: https://gitdiagram.com/instill-ai/package
- Repository: https://github.com/instill-ai/package

## Overview

##### Project type and purpose
- This is not a web app or service; it’s a **CI/CD packaging utility**.
- Purpose: automate building/testing of MLC-AI Python wheels and Conda packages on Linux (manylinux, Ubuntu, AlmaLinux), macOS (x86_64 & Apple Silicon), Windows, and handle nightly pruning and uploads.

##### File structure
- `.github/workflows/`: GitHub Actions definitions (triggers and pipelines).
- `docker/`: Dockerfiles and install scripts to create build environments.
- `conda/`: Conda build recipes and environment definitions.
- `scripts/`: Bash/Batch/Python scripts coordinating builds, pruning, syncing, uploads.
- `3rdparty/tlcpack`: bundled third-party component.
- Root files (`.gitignore`, `LICENSE`, `README.md`, `.gitmodules`) manage governance and submodules.

##### Insights from README.md
- Badges show nightly workflows for wheel builds and prune jobs.
- Confirms CI-driven packaging across OS/architectures.

A. **Source Repository (GitHub)**
– Hosts code, workflows, Dockerfiles, conda recipes, scripts.
B. **GitHub Actions CI/CD**
– Workflow triggers (pushes, schedules).
– Jobs: build_docker_ci, wheel_*_nightly, prune_nightly, package builds.
C. **Docker Build Environments**
– Multiple Dockerfiles (CI-CPU, GPU variants, ROCm, etc.).
– `docker/install/*` scripts to install CUDA/ROCm/conda/python libs.
D. **Conda Recipes & Environments**
– Environment YAMLs to define build and deploy environments.
– Recipes (`.recipe/`) to assemble `mlc-llm` packages.
E. **Packaging Scripts**
– Build scripts (`build_mlc_*.sh/.bat`), wheel prune, sync, upload.
F. **External Services**
– Docker registry (for base images).
– Conda channels (for dependencies and upload).
– PyPI (for wheel publishing).
– Artifact storage or GitHub Packages (for intermediate artifacts).

##### Relationships & data flow
1. **Trigger**: GitHub Actions scheduled or on-push →
2. **Spin up Docker Containers** using specific Dockerfile →
3. **Run Conda Env Setup** inside container →
4. **Invoke build scripts** to compile C/C++ libs, package Python wheels & Conda tars →
5. **Prune old wheels** (prune_nightly job) →
6. **Upload artifacts** to PyPI / Conda channels / GitHub Packages.

##### Architectural patterns & principles
- **CICD as code**: pipelines defined in YAML (GitHub Actions).
- **Containerization**: deterministic build environments via Docker.
- **Modular recipes**: separate conda envs and recipes for variations.
- **Cross-platform builds**: use scripts and Docker to abstract OS differences.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Nodes
    SourceRepo["Source Repository (GitHub)"]:::repo
    GitHubActions["GitHub Actions CI/CD"]:::repo
    BuildEnvironments["Docker Build Environments"]:::container
    CondaRecipes["Conda Recipes & Environments"]:::container
    Scripts["Packaging & Orchestration Scripts"]:::repo
    ThirdParty["3rdparty/tlcpack"]:::repo
    subgraph ExternalServices["External Services"]
        DockerRegistry["Docker Registry"]:::external
        CondaChannels["Conda Channels"]:::external
        PyPI["PyPI"]:::external
        GitHubPackages["GitHub Packages"]:::external
    end

    %% Flows
    SourceRepo -->|"push / schedule"| GitHubActions
    GitHubActions -->|"spin up containers"| BuildEnvironments
    BuildEnvironments -->|"setup conda env"| CondaRecipes
    CondaRecipes -->|"invoke build scripts"| Scripts
    Scripts -->|"upload images"| DockerRegistry
    Scripts -->|"upload conda packages"| CondaChannels
    Scripts -->|"upload wheels"| PyPI
    Scripts -->|"store artifacts"| GitHubPackages
    SourceRepo --> ThirdParty

    %% Click Events
    click SourceRepo "https://github.com/instill-ai/package/tree/main//"
    click GitHubActions "https://github.com/instill-ai/package/tree/main/.github/workflows/"
    click BuildEnvironments "https://github.com/instill-ai/package/tree/main/docker/"
    click CondaRecipes "https://github.com/instill-ai/package/tree/main/conda/"
    click Scripts "https://github.com/instill-ai/package/tree/main/scripts/"
    click ThirdParty "https://github.com/instill-ai/package/tree/main/3rdparty/tlcpack"

    %% Styles
    classDef repo fill:#D0E8FF,stroke:#0366d6,stroke-width:2px
    classDef container fill:#FFE5B4,stroke:#D2691E,stroke-width:2px
    classDef external fill:#D4F8DB,stroke:#228B22,stroke-width:2px
```
