# albert-einshutoin/lazy-image architecture

> Architecture diagram of the GitHub repository albert-einshutoin/lazy-image, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/albert-einshutoin/lazy-image
- Repository: https://github.com/albert-einshutoin/lazy-image

## Overview

lazy-image is a Node.js image-optimization product backed by a Rust/N-API engine. Its main workflow accepts a file or buffer, queues transformations and safety policies, then decodes, processes, and encodes on demand to a buffer or file. A separate compiler workflow produces a verified responsive artifact set and manifest in a local directory; the streaming API stages input and output through temporary files. The README also documents browser/Edge upload preflight through a separate Wasm package. Source excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`src/engine/api/engine.rs`](https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/api/engine.rs) (ImageEngine API), [`lib/artifact-compiler.js`](https://github.com/albert-einshutoin/lazy-image/blob/main/lib/artifact-compiler.js) (Artifact Compiler), [`index.js`](https://github.com/albert-einshutoin/lazy-image/blob/main/index.js) (JS Package API), [`src/engine/api/output_ops.rs`](https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/api/output_ops.rs) (Output Methods)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Node Interfaces"]
  node_api["JS Package API<br/>[index.js]"]
  node_cli["Compile CLI<br/>[lazy-image.js]"]
  node_stream["Streaming API<br/>[pipeline.js]"]
end

subgraph group_compiler["Artifact Compiler"]
  node_compiler["Artifact Compiler"]
  node_policy["Artifact Policy<br/>[artifact-policy.js]"]
  node_helpers["Compiler Helpers<br/>[helpers.js]"]
end

subgraph group_engine["Image Engine"]
  node_native["Native Binding<br/>[index.js]"]
  node_engine_api["ImageEngine API<br/>[engine.rs]"]
  node_pipeline_ops["Queued Operations<br/>[pipeline_ops.rs]"]
  node_output_ops["Output Methods<br/>[output_ops.rs]"]
  node_batch_ops["Batch Operations<br/>[batch_ops.rs]"]
  node_inspect["Header Inspection<br/>[inspect.rs]"]
end

subgraph group_internals["Processing Internals"]
  node_source["Image Sources<br/>[source.rs]"]
  node_firewall["Input Firewall<br/>[firewall.rs]"]
  node_decoder["Image Decoder<br/>[decoder.rs]"]
  node_apply["Operation Pipeline<br/>[apply.rs]"]
  node_encoder["Image Encoder<br/>[encoder.rs]"]
  node_metadata["Metadata Handling<br/>[metadata.rs]"]
  node_io_metadata["Metadata I/O<br/>[mod.rs]"]
end

subgraph group_wasm["Wasm Preflight"]
  node_wasm_browser["Browser Optimizer<br/>[browser.js]"]
  node_wasm_shared["Wasm Runtime<br/>[shared.js]"]
  node_wasm_worker["Worker Handler<br/>[worker.js]"]
end

node_user(("Node.js Caller"))
node_cli_user(("CLI User"))
node_filesystem[("Local Filesystem")]

node_user -->|"calls"| node_api
node_cli_user -->|"runs"| node_cli
node_api -->|"loads binding"| node_native
node_api -->|"exports compiler"| node_compiler
node_api -->|"exports inspect"| node_inspect
node_api -->|"exports streaming"| node_stream
node_cli -->|"compiles artifacts"| node_compiler
node_compiler -->|"applies policy"| node_policy
node_compiler -->|"uses helpers"| node_helpers
node_compiler -->|"optimizes images"| node_native
node_compiler -->|"stages and commits"| node_filesystem
node_stream -->|"stages files"| node_filesystem
node_stream -->|"processes image"| node_native
node_native -->|"dispatches calls"| node_engine_api
node_engine_api -->|"creates source"| node_source
node_engine_api -->|"queues operations"| node_pipeline_ops
node_engine_api -->|"dispatches output"| node_output_ops
node_engine_api -->|"dispatches batches"| node_batch_ops
node_engine_api -->|"configures policy"| node_firewall
node_output_ops -->|"decodes input"| node_decoder
node_output_ops -->|"applies operations"| node_apply
node_output_ops -->|"encodes output"| node_encoder
node_decoder -->|"reads source"| node_source
node_decoder -->|"checks input"| node_firewall
node_apply -->|"produces pixels"| node_encoder
node_output_ops -->|"applies policy"| node_metadata
node_metadata -->|"reads and embeds"| node_io_metadata
node_user -.->|"preflights upload"| node_wasm_browser
node_wasm_worker -->|"calls optimizer"| node_wasm_browser
node_wasm_worker -->|"formats errors"| node_wasm_shared

click node_api "https://github.com/albert-einshutoin/lazy-image/blob/main/index.js"
click node_cli "https://github.com/albert-einshutoin/lazy-image/blob/main/bin/lazy-image.js"
click node_stream "https://github.com/albert-einshutoin/lazy-image/blob/main/streaming/pipeline.js"
click node_compiler "https://github.com/albert-einshutoin/lazy-image/blob/main/lib/artifact-compiler.js"
click node_policy "https://github.com/albert-einshutoin/lazy-image/blob/main/lib/artifact-policy.js"
click node_helpers "https://github.com/albert-einshutoin/lazy-image/blob/main/lib/helpers.js"
click node_native "https://github.com/albert-einshutoin/lazy-image/blob/main/index.js"
click node_engine_api "https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/api/engine.rs"
click node_pipeline_ops "https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/api/pipeline_ops.rs"
click node_output_ops "https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/api/output_ops.rs"
click node_batch_ops "https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/api/batch_ops.rs"
click node_inspect "https://github.com/albert-einshutoin/lazy-image/blob/main/src/inspect.rs"
click node_source "https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/io/source.rs"
click node_firewall "https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/firewall.rs"
click node_decoder "https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/decoder.rs"
click node_apply "https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/pipeline/apply.rs"
click node_encoder "https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/encoder.rs"
click node_metadata "https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/metadata.rs"
click node_io_metadata "https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/io/mod.rs"
click node_wasm_browser "https://github.com/albert-einshutoin/lazy-image/blob/main/packages/lazy-image-wasm/browser.js"
click node_wasm_shared "https://github.com/albert-einshutoin/lazy-image/blob/main/packages/lazy-image-wasm/shared.js"
click node_wasm_worker "https://github.com/albert-einshutoin/lazy-image/blob/main/packages/lazy-image-wasm/worker.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_cli,node_stream,node_cli_user toneBlue
class node_compiler,node_policy,node_helpers,node_filesystem toneAmber
class node_native,node_engine_api,node_pipeline_ops,node_output_ops,node_batch_ops,node_inspect toneMint
class node_source,node_firewall,node_decoder,node_apply,node_encoder,node_metadata,node_io_metadata toneRose
class node_wasm_browser,node_wasm_shared,node_wasm_worker,node_user toneIndigo
```

## Components

### Node Interfaces

- [JS Package API](https://github.com/albert-einshutoin/lazy-image/blob/main/index.js): `index.js`
- [Compile CLI](https://github.com/albert-einshutoin/lazy-image/blob/main/bin/lazy-image.js): `bin/lazy-image.js`
- [Streaming API](https://github.com/albert-einshutoin/lazy-image/blob/main/streaming/pipeline.js): `streaming/pipeline.js`

### Artifact Compiler

- [Artifact Compiler](https://github.com/albert-einshutoin/lazy-image/blob/main/lib/artifact-compiler.js): `lib/artifact-compiler.js`
- [Artifact Policy](https://github.com/albert-einshutoin/lazy-image/blob/main/lib/artifact-policy.js): `lib/artifact-policy.js`
- [Compiler Helpers](https://github.com/albert-einshutoin/lazy-image/blob/main/lib/helpers.js): `lib/helpers.js`

### Image Engine

- [Native Binding](https://github.com/albert-einshutoin/lazy-image/blob/main/index.js): `index.js`
- [ImageEngine API](https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/api/engine.rs): `src/engine/api/engine.rs`
- [Queued Operations](https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/api/pipeline_ops.rs): `src/engine/api/pipeline_ops.rs`
- [Output Methods](https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/api/output_ops.rs): `src/engine/api/output_ops.rs`
- [Batch Operations](https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/api/batch_ops.rs): `src/engine/api/batch_ops.rs`
- [Header Inspection](https://github.com/albert-einshutoin/lazy-image/blob/main/src/inspect.rs): `src/inspect.rs`

### Processing Internals

- [Image Sources](https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/io/source.rs): `src/engine/io/source.rs`
- [Input Firewall](https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/firewall.rs): `src/engine/firewall.rs`
- [Image Decoder](https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/decoder.rs): `src/engine/decoder.rs`
- [Operation Pipeline](https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/pipeline/apply.rs): `src/engine/pipeline/apply.rs`
- [Image Encoder](https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/encoder.rs): `src/engine/encoder.rs`
- [Metadata Handling](https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/metadata.rs): `src/engine/metadata.rs`
- [Metadata I/O](https://github.com/albert-einshutoin/lazy-image/blob/main/src/engine/io/mod.rs): `src/engine/io/mod.rs`

### Wasm Preflight

- [Browser Optimizer](https://github.com/albert-einshutoin/lazy-image/blob/main/packages/lazy-image-wasm/browser.js): `packages/lazy-image-wasm/browser.js`
- [Wasm Runtime](https://github.com/albert-einshutoin/lazy-image/blob/main/packages/lazy-image-wasm/shared.js): `packages/lazy-image-wasm/shared.js`
- [Worker Handler](https://github.com/albert-einshutoin/lazy-image/blob/main/packages/lazy-image-wasm/worker.js): `packages/lazy-image-wasm/worker.js`

### Other components

- **Node.js Caller**
- **CLI User**
- **Local Filesystem**

## Connections

- Node.js Caller → JS Package API: calls
- CLI User → Compile CLI: runs
- JS Package API → Native Binding: loads binding
- JS Package API → Artifact Compiler: exports compiler
- JS Package API → Header Inspection: exports inspect
- JS Package API → Streaming API: exports streaming
- Compile CLI → Artifact Compiler: compiles artifacts
- Artifact Compiler → Artifact Policy: applies policy
- Artifact Compiler → Compiler Helpers: uses helpers
- Artifact Compiler → Native Binding: optimizes images
- Artifact Compiler → Local Filesystem: stages and commits
- Streaming API → Local Filesystem: stages files
- Streaming API → Native Binding: processes image
- Native Binding → ImageEngine API: dispatches calls
- ImageEngine API → Image Sources: creates source
- ImageEngine API → Queued Operations: queues operations
- ImageEngine API → Output Methods: dispatches output
- ImageEngine API → Batch Operations: dispatches batches
- ImageEngine API → Input Firewall: configures policy
- Output Methods → Image Decoder: decodes input
- Output Methods → Operation Pipeline: applies operations
- Output Methods → Image Encoder: encodes output
- Image Decoder → Image Sources: reads source
- Image Decoder → Input Firewall: checks input
- Operation Pipeline → Image Encoder: produces pixels
- Output Methods → Metadata Handling: applies policy
- Metadata Handling → Metadata I/O: reads and embeds
- Node.js Caller → Browser Optimizer: preflights upload
- Worker Handler → Browser Optimizer: calls optimizer
- Worker Handler → Wasm Runtime: formats errors