# jkvargas/russimp architecture

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

- Interactive diagram: https://gitdiagram.com/jkvargas/russimp
- Repository: https://github.com/jkvargas/russimp

## Overview

##### Project Type and Purpose
- russimp is an open-source language-binding library rather than a standalone application.
- It exposes a safe, idiomatic Rust API (`russimp` crate) on top of low-level FFI bindings (`russimp-sys` submodule) to the native Assimp C library.
- Core use case: Load and post-process 3D model files of various formats into a unified Rust data structure (`Scene`, `Mesh`, `Node`, etc.).

##### File Structure
- Top level:
– Cargo.toml / src/… → The main Rust wrapper crate (`russimp`).
– .gitmodules → Includes the `russimp-sys` submodule (low-level FFI).
– examples/ → Consumer code demonstrating usage (e.g. `load_scene_with_props.rs`).
– models/ → Sample 3D assets fed into examples/tests.
– install_assimp.bash → Script to install Assimp system library.
– .github/workflows/russimp.yml → CI pipeline that builds, tests, and produces prebuilt binaries.
- src folder subdivides responsibilities by data type (animation.rs, mesh.rs, material.rs, etc.), reflecting the key abstractions.

##### README and Build Features
- Cargo features control how Assimp is linked:
- `prebuilt` → download static libraries from GitHub releases.
- `static-link` → build Assimp from source via CMake, Ninja/Visual Studio.
- `nozlib` → toggle zlib linking.
- Runtime API: load from file or buffer, apply post-process flags, traverse `Scene` structure.

##### Main Components and Their Relationships
a. Rust Wrapper Layer (russimp crate)
- Public Rust types: Scene, Node, Mesh, Material, Light, Camera, Bone, Animation, etc.
- Conversion logic from raw FFI structs to safe Rust representations (`impl_mint.rs` handles vector types).
b. FFI / Binding Layer (russimp-sys submodule)
- Raw `extern "C"` declarations matching Assimp API.
- Build script (`build.rs` in sys crate) that either downloads prebuilt binaries or compiles Assimp from source.
c. Native Assimp C Library
- Provides model-loading core functionality.
- May link statically or dynamically depending on feature flags.
d. Build Toolchain
- CMake + Ninja / MSVC for source builds.
- GitHub Actions workflow that automates prebuild and publishing of binaries.
e. Consumer Code
- examples/ directory, any downstream crate or application calling `Scene::from_file`.
f. Sample Assets
- models/ folder containing various 3D formats (FBX, OBJ, GLTF2, COLLADA, etc.) used for testing and examples.

##### Important Architectural Patterns & Design Principles
- Layered FFI pattern: clear separation between safe Rust API and unsafe C bindings.
- Feature-flag-driven builds: compile-time switches that alter dependency resolution (download vs. build).
- Modular Rust code: one file per major domain concept to keep the codebase navigable.
- CI/CD integration for binary distribution.

##### Essential Elements
- Clear labels on each component (e.g. “russimp::Scene loader,” “russimp-sys FFI,” “Assimp C library”).
- A small inset showing feature-flag decision points (prebuilt vs. build-from-source).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build-Time Layer
    subgraph "Build-Time" 
        direction TB
        Cargo["Cargo.toml + config"]:::config
        Gitmodules[".gitmodules"]:::ffi
        InstallScript["install_assimp.bash"]:::build
        CI[".github/workflows/russimp.yml"]:::external
        Decision{"Feature Flag?"}
        Prebuilt["Prebuilt Binaries\n(GitHub Releases)"]:::external
        StaticLink["Static-Link Path"]:::build
        CMake["CMake + Ninja/MSVC"]:::build
        AssimpSrc["Assimp C Source"]:::c
        Cargo -->|build script| Gitmodules
        Gitmodules -->|submodule init| Decision
        Decision -->|prebuilt| Prebuilt
        Decision -->|static-link| StaticLink
        StaticLink --> CMake
        CMake --> AssimpSrc
        CI -->|publishes| Prebuilt
        InstallScript --> AssimpSrc
    end

    %% Runtime Layer
    subgraph "Runtime" 
        direction TB
        Consumer["Examples / Consumer"]:::consumer
        Models["models/* (3D Assets)"]:::assets
        subgraph "Rust Wrapper Layer" 
            direction TB
            Lib["lib.rs"]:::rust
            Scene["scene.rs"]:::rust
            Mesh["mesh.rs"]:::rust
            Node["node.rs"]:::rust
            Material["material.rs"]:::rust
            Light["light.rs"]:::rust
            Camera["camera.rs"]:::rust
            Bone["bone.rs"]:::rust
            Animation["animation.rs"]:::rust
            Face["face.rs"]:::rust
            Property["property.rs"]:::rust
            Metadata["metadata.rs"]:::rust
            FS["fs.rs"]:::rust
            ImplMint["impl_mint.rs"]:::rust
        end
        FFI["russimp-sys FFI"]:::ffi
        AssimpC["Assimp C Library"]:::c
        SafeRust["Safe Rust Data Structures"]:::rust
        Consumer -->|file I/O| Models
        Consumer -->|calls Scene::from_file| Lib
        Lib --> Scene
        Scene --> Mesh
        Scene --> Node
        Scene --> Material
        Scene --> Light
        Scene --> Camera
        Scene --> Bone
        Scene --> Animation
        Scene --> Face
        Scene --> Property
        Scene --> Metadata
        Scene --> FS
        Scene --> ImplMint
        Scene -->|extern C ABI| FFI
        FFI -->|calls| AssimpC
        AssimpC -->|C structs| FFI
        FFI -->|raw data| Lib
        Lib -->|rustify| SafeRust
        SafeRust -->|returned data| Consumer
    end

    %% Examples and Assets
    subgraph "Examples / Assets"
        direction TB
        Example["load_scene_with_props.rs"]:::consumer
        Models3DS["models/3DS/"]:::assets
        ModelsBLEND["models/BLEND/"]:::assets
        ModelsCOLLADA["models/COLLADA/"]:::assets
        ModelsFBX["models/FBX/"]:::assets
        ModelsGLTF2["models/GLTF2/"]:::assets
        ModelsOBJ["models/OBJ/"]:::assets
        Example --> Consumer
    end

    %% Click Events
    click Lib "https://github.com/jkvargas/russimp/blob/master/src/lib.rs"
    click Scene "https://github.com/jkvargas/russimp/blob/master/src/scene.rs"
    click Mesh "https://github.com/jkvargas/russimp/blob/master/src/mesh.rs"
    click Node "https://github.com/jkvargas/russimp/blob/master/src/node.rs"
    click Material "https://github.com/jkvargas/russimp/blob/master/src/material.rs"
    click Light "https://github.com/jkvargas/russimp/blob/master/src/light.rs"
    click Camera "https://github.com/jkvargas/russimp/blob/master/src/camera.rs"
    click Bone "https://github.com/jkvargas/russimp/blob/master/src/bone.rs"
    click Animation "https://github.com/jkvargas/russimp/blob/master/src/animation.rs"
    click Face "https://github.com/jkvargas/russimp/blob/master/src/face.rs"
    click Property "https://github.com/jkvargas/russimp/blob/master/src/property.rs"
    click Metadata "https://github.com/jkvargas/russimp/blob/master/src/metadata.rs"
    click FS "https://github.com/jkvargas/russimp/blob/master/src/fs.rs"
    click ImplMint "https://github.com/jkvargas/russimp/blob/master/src/impl_mint.rs"
    click Gitmodules "https://github.com/jkvargas/russimp/blob/master/.gitmodules"
    click InstallScript "https://github.com/jkvargas/russimp/blob/master/install_assimp.bash"
    click CI "https://github.com/jkvargas/russimp/blob/master/.github/workflows/russimp.yml"
    click Cargo "https://github.com/jkvargas/russimp/blob/master/Cargo.toml"
    click Example "https://github.com/jkvargas/russimp/blob/master/examples/load_scene_with_props.rs"
    click Models3DS "https://github.com/jkvargas/russimp/tree/master/models/3DS/"
    click ModelsBLEND "https://github.com/jkvargas/russimp/tree/master/models/BLEND/"
    click ModelsCOLLADA "https://github.com/jkvargas/russimp/tree/master/models/COLLADA/"
    click ModelsFBX "https://github.com/jkvargas/russimp/tree/master/models/FBX/"
    click ModelsGLTF2 "https://github.com/jkvargas/russimp/tree/master/models/GLTF2/"
    click ModelsOBJ "https://github.com/jkvargas/russimp/tree/master/models/OBJ/"

    %% Styles
    classDef rust fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef ffi fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef c fill:#696969,stroke:#000,stroke-width:1px
    classDef build fill:#FFA500,stroke:#000,stroke-width:1px
    classDef consumer fill:#90EE90,stroke:#000,stroke-width:1px
    classDef assets fill:#9370DB,stroke:#000,stroke-width:1px
    classDef external fill:#FFD700,stroke:#000,stroke-width:1px
    classDef config fill:#FFFFE0,stroke:#000,stroke-width:1px
```
