# kufu-ai/kinu architecture

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

- Interactive diagram: https://gitdiagram.com/kufu-ai/kinu
- Repository: https://github.com/kufu-ai/kinu

## Overview

##### Project Type and Purpose
- Kinu is a specialized backend server for image processing. Its core function is to receive image upload requests, resize images (using ImageMagick as the engine), and deliver resized versions via HTTP endpoints. It also features a sandbox for temporary uploads and supports both file system and S3 storage backends.
- The README confirms the image resizing functionality, outlines several endpoints (for upload, retrieval, sandbox operations, and version checks), and specifies environment variables that dictate the behavior (e.g., selecting the resize engine and storage type).

##### File Structure
- Top-Level Files: Files like main.go, Dockerfile, and configuration scripts indicate that this is a server application.
- Directories and Their Roles:
- config: Contains application configuration logic (e.g., config/main.go).
- engine: Implements the core image processing functionality; includes an ImageMagick module (engine/image_magick.go) suggesting that this abstraction may allow for future extension.
- handlers: Multiple handler files (e.g., handler_get_image.go, handler_upload_image.go, etc.) implement the HTTP endpoints.
- logger: Contains logging functionality (logger/logger.go) used across the project.
- resizer: Holds logic for resizing images, including calculating coordinates, geometry, and executing the resize operation.
- resource: Manages resource-related operations, including backward compatibility adjustments and the primary resource management logic.
- storage: Abstracts storage details and supports different implementations (File storage with storage/file.go, S3 storage with storage/s3.go).
- uploader: Likely handles the process of uploading images, especially in asynchronous or specialized modes.
- Additional files (e.g., go.mod, Dockerfile, .dockerignore, etc.) indicate standard Go project practices and deployment via Docker.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client (HTTP Request)"]:::external

    subgraph "Kinu Server"
        A["Main Server Entry Point"]:::service
        B["Configuration Module"]:::config
        C["Logger Module"]:::config

        subgraph "API Handlers"
            H1["Upload Handler"]:::service
            H2["Get Image Handler"]:::service
            H3["Sandbox Handler"]:::service
            H4["Version Handler"]:::service
            H5["WorkerStats Handler"]:::service
        end

        subgraph "Image Processing"
            R["Resizer Module"]:::service
            E["Image Processing Engine"]:::service
        end

        U["Uploader Module"]:::service

        subgraph "Storage"
            ST["File and S3 Storage Module"]:::service
        end

        RES["Resource Management Module"]:::service
    end

    %% Client requests to API Handlers
    Client -->|"sends_upload_request"| H1
    Client -->|"sends_get_image"| H2
    Client -->|"sends_sandbox_request"| H3
    Client -->|"sends_version_check"| H4
    Client -->|"sends_worker_stats"| H5

    %% Flow for image upload
    H1 -->|"process_upload"| U
    U -->|"register_resource"| RES
    RES -->|"store_image"| ST

    %% Flow for image retrieval
    H2 -->|"request_resize"| R
    R -->|"call_engine"| E
    E -->|"fetch_processed_image"| ST

    %% Configuration connections
    B -->|"config_init"| A
    B -->|"config_handler"| H1
    B -->|"config_handler"| H2
    B -->|"config_uploader"| U
    B -->|"config_resizer"| R
    B -->|"config_engine"| E
    B -->|"config_storage"| ST
    B -->|"config_resource"| RES

    %% Logging arrows (dotted)
    A ---|"logs"| C
    H1 ---|"logs"| C
    H2 ---|"logs"| C
    H3 ---|"logs"| C
    H4 ---|"logs"| C
    H5 ---|"logs"| C
    U ---|"logs"| C
    R ---|"logs"| C
    E ---|"logs"| C
    ST ---|"logs"| C
    RES ---|"logs"| C

    %% Click Events
    click H1 "https://github.com/kufu-ai/kinu/blob/master/handler_upload_image.go"
    click H2 "https://github.com/kufu-ai/kinu/blob/master/handler_get_image.go"
    click H3 "https://github.com/kufu-ai/kinu/blob/master/handler_sandbox.go"
    click H4 "https://github.com/kufu-ai/kinu/blob/master/handler_version.go"
    click H5 "https://github.com/kufu-ai/kinu/blob/master/handler_worker_stats.go"
    click B "https://github.com/kufu-ai/kinu/blob/master/config/main.go"
    click C "https://github.com/kufu-ai/kinu/blob/master/logger/logger.go"
    click E "https://github.com/kufu-ai/kinu/blob/master/engine/image_magick.go"
    click R "https://github.com/kufu-ai/kinu/tree/master/resizer/"
    click ST "https://github.com/kufu-ai/kinu/tree/master/storage/"
    click RES "https://github.com/kufu-ai/kinu/blob/master/resource/main.go"
    click U "https://github.com/kufu-ai/kinu/blob/master/uploader/main.go"
    click A "https://github.com/kufu-ai/kinu/blob/master/main.go"

    %% Styles
    classDef external fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef config fill:#ffa500,stroke:#333,stroke-width:2px;
    classDef service fill:#87cefa,stroke:#333,stroke-width:2px;
```
