# woltapp/blurhash architecture

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

- Interactive diagram: https://gitdiagram.com/woltapp/blurhash
- Repository: https://github.com/woltapp/blurhash

## Overview

##### Project type and purpose
- This is an open-source, multi-language library and tooling project (“BlurHash”) that provides a compact image placeholder encoding/decoding algorithm and demos in C, Swift, Kotlin (Android), TypeScript (web), Python integration, plus a supporting website and docs.
- Purpose: allow back-ends to encode images into short strings, store those, and clients to decode them as low-res previews while main images load.

##### File structure
- Top-level folders:
- C – portable C encoder/decoder
- Swift – iOS/macOS library, demo app, XCTest suite
- Kotlin – Android library + demo app
- TypeScript – encoder/decoder + demo web page
- Python – wrapper around the C encoder
- Website – marketing/demo site built with Node, Babel, Webpack
- Media, Algorithm.md, Readme.md, Security/License, CodeOfConduct
- Build & config files: Makefile (C), Xcode project (Swift), Gradle (Kotlin), tsconfig/webpack (TypeScript), package.json, deploy.sh (website).
- Demos: each language folder contains a “demo” or “test” harness that consumes its local library.

##### README for additional insights
- Core algorithm lives in Algorithm.md and in each language’s encode/decode implementations.
- README lists dependencies (stb_image/stb_writer in C, AndroidX in Kotlin, UIKit/SwiftUI in Swift, React-less TS demo via vanilla JS, Node build tools for website).
- Use cases: back-end encoding, client-side decoding, placeholder UI, extensibility to new languages.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer: Core Algorithm
    Algo["Algorithm Core\n(Algorithm.md)"]:::core

    %% Middle Layer: Language Adapters
    subgraph "Language Adapters"
        C["C Library\nMakefile\nencode/decode"]:::module
        PythonMod["Python Module\ncffi wrapper"]:::module
        SwiftPkg["Swift Package\nBlurHashKit"]:::module
        SwiftXcode["Xcode Project\nBlurHash.xcodeproj"]:::module
        KotlinLib["Kotlin Library\nAAR"]:::module
        TSModule["TypeScript npm Module"]:::module
    end

    %% Bottom Layer: Demos & Website
    subgraph "Demos & Website"
        SwiftDemo["Swift Demo/Test App"]:::demo
        KotlinDemo["Kotlin Demo App"]:::demo
        TSDemo["TS Web Demo"]:::demo
        PythonTests["Python Tests"]:::demo
        Website["Website\nStatic Site & Live Demo"]:::website
    end

    %% External Dependencies
    subgraph "External Dependencies"
        STB1["stb_image.h"]:::external
        STB2["stb_writer.h"]:::external
        AndroidSDK["Android SDK"]:::external
        iOSSDK["iOS SDK"]:::external
        NodeTooling["Node/Babel/Webpack"]:::external
    end

    %% Relationships
    Algo -->|implemented in C| C
    Algo -->|ported| SwiftPkg
    Algo -->|ported| KotlinLib
    Algo -->|ported| TSModule
    Algo -->|wrapped via FFI| PythonMod

    C -->|wrapped by| PythonMod
    C -->|uses| STB1
    C -->|uses| STB2

    SwiftPkg -->|built with| SwiftXcode
    SwiftPkg -->|used by| SwiftDemo
    SwiftXcode -->|requires| iOSSDK

    KotlinLib -->|built with Gradle| KotlinLib
    KotlinLib -->|used by| KotlinDemo
    KotlinLib -->|requires| AndroidSDK

    TSModule -->|bundled with| NodeTooling
    TSModule -->|used by| TSDemo
    TSModule -->|imported by| Website
    Website -->|served as| TSDemo

    PythonMod -->|tested by| PythonTests

    %% Click Events for component mapping
    click Algo "https://github.com/woltapp/blurhash/blob/master/Algorithm.md"
    click C "https://github.com/woltapp/blurhash/tree/master/C/Makefile"
    click C "https://github.com/woltapp/blurhash/blob/master/C/encode.c"
    click C "https://github.com/woltapp/blurhash/blob/master/C/encode.h"
    click C "https://github.com/woltapp/blurhash/blob/master/C/decode.c"
    click C "https://github.com/woltapp/blurhash/blob/master/C/decode.h"
    click C "https://github.com/woltapp/blurhash/blob/master/C/encode_stb.c"
    click C "https://github.com/woltapp/blurhash/blob/master/C/decode_stb.c"
    click C "https://github.com/woltapp/blurhash/blob/master/C/common.h"
    click C "https://github.com/woltapp/blurhash/blob/master/C/stb_image.h"
    click C "https://github.com/woltapp/blurhash/blob/master/C/stb_writer.h"
    click C "https://github.com/woltapp/blurhash/blob/master/C/Readme.md"
    click PythonMod "https://github.com/woltapp/blurhash/blob/master/Python/Readme.md"
    click SwiftPkg "https://github.com/woltapp/blurhash/tree/master/Swift/BlurHashKit"
    click SwiftXcode "https://github.com/woltapp/blurhash/blob/master/Swift/BlurHash.xcodeproj"
    click SwiftDemo "https://github.com/woltapp/blurhash/tree/master/Swift/BlurHashTest"
    click KotlinLib "https://github.com/woltapp/blurhash/blob/master/Kotlin/lib/build.gradle"
    click KotlinLib "https://github.com/woltapp/blurhash/blob/master/Kotlin/lib/src/main/java/com/wolt/blurhashkt/BlurHashDecoder.kt"
    click KotlinLib "https://github.com/woltapp/blurhash/blob/master/Kotlin/lib/src/main/AndroidManifest.xml"
    click KotlinDemo "https://github.com/woltapp/blurhash/tree/master/Kotlin/demo"
    click TSModule "https://github.com/woltapp/blurhash/tree/master/TypeScript/src"
    click TSModule "https://github.com/woltapp/blurhash/blob/master/TypeScript/package.json"
    click TSModule "https://github.com/woltapp/blurhash/blob/master/TypeScript/tsconfig.json"
    click TSModule "https://github.com/woltapp/blurhash/blob/master/TypeScript/webpack.config.js"
    click TSDemo "https://github.com/woltapp/blurhash/blob/master/TypeScript/demo/index.html"
    click Website "https://github.com/woltapp/blurhash/blob/master/Website/package.json"
    click Website "https://github.com/woltapp/blurhash/blob/master/Website/deploy.sh"
    click Website "https://github.com/woltapp/blurhash/blob/master/Website/.babelrc"
    click Website "https://github.com/woltapp/blurhash/blob/master/Website/webpack.config.js"
    click Website "https://github.com/woltapp/blurhash/tree/master/Website/src"
    click Website "https://github.com/woltapp/blurhash/tree/master/Website/assets"
    click RootReadme "https://github.com/woltapp/blurhash/blob/master/Readme.md"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,color:#1B4F72
    classDef module fill:#ABEBC6,stroke:#1D8348,color:#1D8348
    classDef demo fill:#F9E79F,stroke:#B9770E,color:#7E5109
    classDef website fill:#F5B7B1,stroke:#922B21,color:#641E16
    classDef external fill:#D5D8DC,stroke:#566573,color:#566573
```
